MetricQ Management Protocol 0.1.0

RPCs

MetricQ Management Protocol 0.1.0

Clients on the MetricQ network are managed via an RPC protocol, where messages are encoded in a JSON format. A request consists of a JSON object with a property "function", identifying the action to perform. Arguments are passed by specifying properties on the request object. Replies are arbitrary JSON objects. If a request could not be processed successfully, the reply has a single property "error" containing an error message as a string.

RPCs are grouped into three categories and are tagged as such:

  • management: Management RPCs are sent to an exchange called metricq.management, management clients subscribe to messages on this queue. Replies from management clients arrive on a dedicated management queue.
  • broadcast: Broadcast RPCs are sent to an exchange called metric.broadcast. All clients will receive such an request simultaneously and are expected to reply.
  • direct: Some RPCs are sent directly into a client's RPC queue, bypassing any exchange.

Servers

metricq.zih.tu-dresden.de ampq

RPCs

RPC get_metrics

Query the network for available metrics

Request

Request information about available metrics

Payload
object oneOf
Examples: { "function": "get_metrics", "selector": "taurus\\.taurusi\\d{4}\\.cpu\\d\\+.power", "limit": 20 } { "function": "get_metrics", "prefix": "taurus", "historic": true }
function
required
string
must match ([a-z_]+\.)+[a-z_]+

A string identifying the requested RPC function

Const: "get_metrics"
format
string

Whether to return an array of metric names or an object mapping metric names to their metadata

Default: "array"
Enum: "array" "object"
historic
boolean

If given, limit returned metrics to either historic (true) or non-historic (false) metrics. If omitted, no filter is applied.

limit
integer
>= 0

Number of matched metrics to include in response. If omitted, all matching metrics are returned.

hidden
boolean

If given, limit returned metrics to either hidden (true) or not hidden (false) metrics. If omitted, this filter is not applied.

Additional properties are allowed.

0
selector
oneOf

A selector matching a set of metrics, either by regex or explicit listing

0
string
regex

A regular expression matching a set of metric names

Examples: "taurus\\.taurusi\\d{4}\\.cpu\\d\\+.power"
1
array<string>
Unique

A list of metric names

Items:

0
string
must match ([a-zA-Z][a-zA-Z0-9_]+\.)+[a-zA-Z][a-zA-Z0-9_]+
Examples: "elab.bahka.power" "elab.ariel.package0.dram.current" "taurus.taurusi4101.cpu0.power"

Additional items are allowed.

1
prefix
string

A prefix matching the start of a metric name

Request examples

Payload
Example #1
{
  "function": "get_metrics",
  "selector": "taurus\\.taurusi\\d{4}\\.cpu\\d\\+.power",
  "limit": 20
}
Example #2
{
  "function": "get_metrics",
  "prefix": "taurus",
  "historic": true
}

Reply

A list of matching metrics, with optional metadata

Payload
object
metrics
oneOf

A collection of metric names, with optional metadata attached

0
array<string>
Unique

A list of metric names

Items:

0
string
must match ([a-zA-Z][a-zA-Z0-9_]+\.)+[a-zA-Z][a-zA-Z0-9_]+
Examples: "elab.bahka.power" "elab.ariel.package0.dram.current" "taurus.taurusi4101.cpu0.power"

Additional items are allowed.

1
object

A mapping of metric names to metadata objects

Examples: { "elab.bahka.power": { "rate": 20, "scope": "last", "unit": "W" } }

Additional properties must adhere to the following schema:

(property name)
object

A metadata object

Examples: { "rate": 0.1 }
unit
string

The unit symbol according to SI, such as "V" for voltage or "s" for time.

If necessary, the SI prefix is included, e.g. "kV", "ms", or "kiB/s". Dimensionless quantities such as counts use either an empty string ("") or the appropriate symbol (e.g. "rad").

Examples: "V" "kV" "s" "kiB/s" "rad" ""
rate
integer

The rate in Sa/s (samples per second) or Hz at which new values of this metric are typically produced. In practice, a source does not necessarily need to produce values exactly at this rate, but the value given should be good estimate.

scope

The temporal validity of a single measured value.

A scope of "last" indicates that a measured value was valid up to now, "next" that it is valid from now on. A scope of "point" means that any measurement is only valid at exactly the moment it was taken.

Enum: "last" "next" "point"
quantity
string

The name of the measured quantity.

Ideally, this is the same as the last segment of the metric name.

Examples: "power" "temperature"
description
string

A human-readable description of the measurement quantity

Additional properties are allowed.

Additional properties are allowed.

Reply examples

Payload 
{
  "metrics": [
    "elab.bahka.power"
  ]
}
This example has been generated automatically.

RPC get_configs

Retrieve the configuration object for a set of clients

Request

Retrieve configuration objects for matching clients

Payload
object
function
required
string
must match ([a-z_]+\.)+[a-z_]+

A string identifying the requested RPC function

Const: "get_configs"
selector
oneOf

A selector matching clients by their token

0
array<string>

A list of client tokens

Items:

0
string

Additional items are allowed.

1
string
regex

A regular expression matching a set of client tokens

Additional properties are allowed.

Request examples

Payload 
{
  "function": "get_configs",
  "selector": [
    "string"
  ]
}
This example has been generated automatically.

Reply

A mapping of client names to their configuration objects

Payload
object
Examples: { "source-py-dummy": { "rate": 0.5 } }

Additional properties must adhere to the following schema:

(property name)
object

A client configuration object

Examples: { "reportNeighboursDogActivity": true, "metricSourceChannels": { "kittens.front-flap.opened.count": "automation.doors.front.catflap.triggered#cumulative", "kittens.water-bowl.1.volume": "automation.volume-sensors[5]" } } { "clientSpecificOption": 42, "monitorKittenHealth": true }

Additional properties are allowed.

Reply examples

Payload
Example #1
{
  "source-py-dummy": {
    "rate": 0.5
  }
}

RPC sink.register

Register a new sink on the network

Request

Payload
object
Examples: { "function": "sink.register" }
function
required
string
must match ([a-z_]+\.)+[a-z_]+

A string identifying the requested RPC function

Const: "sink.register"

Additional properties are allowed.

Request examples

Payload
Example #1
{
  "function": "sink.register"
}

Reply

On success, this contains the information necessary to start consuming metrics from the network. Optionally, a configuration object for this sink is returned.

Payload
object
dataServerAddress
string
url

URL pointing to the AMQP broker where data queues are handled

Examples: "amqp://user:pass@localhost/data-vhost" "amqps://metricq.example.com:50505/"
config
object

A client configuration object

Examples: { "reportNeighboursDogActivity": true, "metricSourceChannels": { "kittens.front-flap.opened.count": "automation.doors.front.catflap.triggered#cumulative", "kittens.water-bowl.1.volume": "automation.volume-sensors[5]" } } { "clientSpecificOption": 42, "monitorKittenHealth": true }

Additional properties are allowed.

Additional properties are allowed.

Reply examples

Payload 
{
  "dataServerAddress": "amqp://user:pass@localhost/data-vhost",
  "config": {
    "reportNeighboursDogActivity": true,
    "metricSourceChannels": {
      "kittens.front-flap.opened.count": "automation.doors.front.catflap.triggered#cumulative",
      "kittens.water-bowl.1.volume": "automation.volume-sensors[5]"
    }
  }
}
This example has been generated automatically.

RPC sink.subscribe

Request to receive data points for a set of metrics.

Request

Payload
object
Examples: { "function": "sink.subscribe", "metrics": [ "building-F.room-A14.temperature.celcius" ], "metadata": true }
function
required
string
must match ([a-z_]+\.)+[a-z_]+

A string identifying the requested RPC function

Const: "sink.subscribe"
metrics
required
array<string>
Unique

A list of metrics to subscribe to.

Items:

0
string
must match ([a-zA-Z][a-zA-Z0-9_]+\.)+[a-zA-Z][a-zA-Z0-9_]+
Examples: "elab.bahka.power" "elab.ariel.package0.dram.current" "taurus.taurusi4101.cpu0.power"

Additional items are allowed.

dataQueue
string
uri

The AMQP queue on which data points should arrive.

Examples: "amqp://user:pass@localhost/vhost" "amqps://metricq.example.com:50505/"
expires
number
seconds > 0

The number of seconds after which the data queue should expire if not connected to a sink. If omitted, a default value is set.

metadata
boolean

Whether to include metadata for each metric in the reponse.

If set to false, the result is an array of metric names, if set to true, an object mapping metric names to metadata objects is returned.

Default: false

Additional properties are allowed.

Request examples

Payload
Example #1
{
  "function": "sink.subscribe",
  "metrics": [
    "building-F.room-A14.temperature.celcius"
  ],
  "metadata": true
}

Reply

After successful subscription, this contains the broker address and queue on which data points for the requested metrics arrive. The metrics in question are returned, optionally with their metadata attached.

Payload
object
dataServerAddress
string
url

URL pointing to the AMQP broker where data queues are handled

Examples: "amqp://user:pass@localhost/data-vhost" "amqps://metricq.example.com:50505/"
dataQueue
string
uri

The AMQP queue at which data points for the subscribed metrics will arrive.

Examples: "amqp://user:pass@localhost/vhost" "amqps://metricq.example.com:50505/"
metrics
oneOf

A collection of metric names, with optional metadata attached

0
array<string>
Unique

A list of metric names

Items:

0
string
must match ([a-zA-Z][a-zA-Z0-9_]+\.)+[a-zA-Z][a-zA-Z0-9_]+
Examples: "elab.bahka.power" "elab.ariel.package0.dram.current" "taurus.taurusi4101.cpu0.power"

Additional items are allowed.

1
object

A mapping of metric names to metadata objects

Examples: { "elab.bahka.power": { "rate": 20, "scope": "last", "unit": "W" } }

Additional properties must adhere to the following schema:

(property name)
object

A metadata object

Examples: { "rate": 0.1 }
unit
string

The unit symbol according to SI, such as "V" for voltage or "s" for time.

If necessary, the SI prefix is included, e.g. "kV", "ms", or "kiB/s". Dimensionless quantities such as counts use either an empty string ("") or the appropriate symbol (e.g. "rad").

Examples: "V" "kV" "s" "kiB/s" "rad" ""
rate
integer

The rate in Sa/s (samples per second) or Hz at which new values of this metric are typically produced. In practice, a source does not necessarily need to produce values exactly at this rate, but the value given should be good estimate.

scope

The temporal validity of a single measured value.

A scope of "last" indicates that a measured value was valid up to now, "next" that it is valid from now on. A scope of "point" means that any measurement is only valid at exactly the moment it was taken.

Enum: "last" "next" "point"
quantity
string

The name of the measured quantity.

Ideally, this is the same as the last segment of the metric name.

Examples: "power" "temperature"
description
string

A human-readable description of the measurement quantity

Additional properties are allowed.

Additional properties are allowed.

Reply examples

Payload 
{
  "dataServerAddress": "amqp://user:pass@localhost/data-vhost",
  "dataQueue": "amqp://user:pass@localhost/vhost",
  "metrics": [
    "elab.bahka.power"
  ]
}
This example has been generated automatically.

RPC sink.unsubscribe

Request

Subscribe to receive data points for a set of metrics

Payload

Stop receiving data points for a set of metrics

dataQueue
required
string
uri

The AMQP queue at which data points should no longer be sent.

Examples: "amqp://user:pass@localhost/vhost" "amqps://metricq.example.com:50505/"
metrics
required
array<string>
Unique

A list of metric names

Items:

0
string
must match ([a-zA-Z][a-zA-Z0-9_]+\.)+[a-zA-Z][a-zA-Z0-9_]+
Examples: "elab.bahka.power" "elab.ariel.package0.dram.current" "taurus.taurusi4101.cpu0.power"

Additional items are allowed.

end
boolean

If true, the manager sends a type="end" message after unbinding the routing keys to indicate that no more message will arrive at this queue.

Default: true

Request examples

Payload 
{
  "dataQueue": "amqp://user:pass@localhost/vhost",
  "metrics": [
    "elab.bahka.power"
  ],
  "end": true
}
This example has been generated automatically.

Reply

An acknowledgement of unsubscription

Payload
object
dataServerAddress
string
url

URL pointing to the AMQP broker where data queues are handled

Examples: "amqp://user:pass@localhost/data-vhost" "amqps://metricq.example.com:50505/"
metrics
oneOf

The collection of metrics this client is no longer subscribed to

0
array<string>
Unique

A list of metric names

Items:

0
string
must match ([a-zA-Z][a-zA-Z0-9_]+\.)+[a-zA-Z][a-zA-Z0-9_]+
Examples: "elab.bahka.power" "elab.ariel.package0.dram.current" "taurus.taurusi4101.cpu0.power"

Additional items are allowed.

1
object

A mapping of metric names to metadata objects

Examples: { "elab.bahka.power": { "rate": 20, "scope": "last", "unit": "W" } }

Additional properties must adhere to the following schema:

(property name)
object

A metadata object

Examples: { "rate": 0.1 }
unit
string

The unit symbol according to SI, such as "V" for voltage or "s" for time.

If necessary, the SI prefix is included, e.g. "kV", "ms", or "kiB/s". Dimensionless quantities such as counts use either an empty string ("") or the appropriate symbol (e.g. "rad").

Examples: "V" "kV" "s" "kiB/s" "rad" ""
rate
integer

The rate in Sa/s (samples per second) or Hz at which new values of this metric are typically produced. In practice, a source does not necessarily need to produce values exactly at this rate, but the value given should be good estimate.

scope

The temporal validity of a single measured value.

A scope of "last" indicates that a measured value was valid up to now, "next" that it is valid from now on. A scope of "point" means that any measurement is only valid at exactly the moment it was taken.

Enum: "last" "next" "point"
quantity
string

The name of the measured quantity.

Ideally, this is the same as the last segment of the metric name.

Examples: "power" "temperature"
description
string

A human-readable description of the measurement quantity

Additional properties are allowed.

Additional properties are allowed.

Reply examples

Payload 
{
  "dataServerAddress": "amqp://user:pass@localhost/data-vhost",
  "metrics": [
    "elab.bahka.power"
  ]
}
This example has been generated automatically.

RPC sink.release

Request

sink.release

Release a data queue

Payload
object
function
required
string
must match ([a-z_]+\.)+[a-z_]+

A string identifying the requested RPC function

Const: "sink.release"
dataQueue
string
uri

The data queue to be released

Examples: "amqp://user:pass@localhost/vhost" "amqps://metricq.example.com:50505/"

Additional properties are allowed.

Request examples

Payload 
{
  "function": "sink.release",
  "dataQueue": "amqp://user:pass@localhost/vhost"
}
This example has been generated automatically.

Reply

Payload
object

Acknowledgement of successful release

Additional properties are allowed.

Reply examples

Payload 
{}
This example has been generated automatically.

RPC source.register

Request

Register a source on the network

Payload
object
function
required
string
must match ([a-z_]+\.)+[a-z_]+

A string identifying the requested RPC function

Const: "source.register"

Additional properties are allowed.

Request examples

Payload 
{
  "function": "source.register"
}
This example has been generated automatically.

Reply

Payload
object
dataServerAddress
string
url

URL pointing to the AMQP broker where data queues are handled

Examples: "amqp://user:pass@localhost/data-vhost" "amqps://metricq.example.com:50505/"
dataExchange
string

Name of the exchange to which data points should be published

Examples: "metricq.data"
config
object

A client configuration object

Examples: { "reportNeighboursDogActivity": true, "metricSourceChannels": { "kittens.front-flap.opened.count": "automation.doors.front.catflap.triggered#cumulative", "kittens.water-bowl.1.volume": "automation.volume-sensors[5]" } } { "clientSpecificOption": 42, "monitorKittenHealth": true }

Additional properties are allowed.

Additional properties are allowed.

Reply examples

Payload 
{
  "dataServerAddress": "amqp://user:pass@localhost/data-vhost",
  "dataExchange": "metricq.data",
  "config": {
    "reportNeighboursDogActivity": true,
    "metricSourceChannels": {
      "kittens.front-flap.opened.count": "automation.doors.front.catflap.triggered#cumulative",
      "kittens.water-bowl.1.volume": "automation.volume-sensors[5]"
    }
  }
}
This example has been generated automatically.

RPC source.declare_metrics

Request

Declare a list of metrics which this source provides

Payload
object
function
string
must match ([a-z_]+\.)+[a-z_]+

A string identifying the requested RPC function

Const: "source.declare_metrics"
metrics
required
oneOf

A collection of metric names, with optional metadata attached

0
array<string>
Unique

A list of metric names

Items:

0
string
must match ([a-zA-Z][a-zA-Z0-9_]+\.)+[a-zA-Z][a-zA-Z0-9_]+
Examples: "elab.bahka.power" "elab.ariel.package0.dram.current" "taurus.taurusi4101.cpu0.power"

Additional items are allowed.

1
object

A mapping of metric names to metadata objects

Examples: { "elab.bahka.power": { "rate": 20, "scope": "last", "unit": "W" } }

Additional properties must adhere to the following schema:

(property name)
object

A metadata object

Examples: { "rate": 0.1 }
unit
string

The unit symbol according to SI, such as "V" for voltage or "s" for time.

If necessary, the SI prefix is included, e.g. "kV", "ms", or "kiB/s". Dimensionless quantities such as counts use either an empty string ("") or the appropriate symbol (e.g. "rad").

Examples: "V" "kV" "s" "kiB/s" "rad" ""
rate
integer

The rate in Sa/s (samples per second) or Hz at which new values of this metric are typically produced. In practice, a source does not necessarily need to produce values exactly at this rate, but the value given should be good estimate.

scope

The temporal validity of a single measured value.

A scope of "last" indicates that a measured value was valid up to now, "next" that it is valid from now on. A scope of "point" means that any measurement is only valid at exactly the moment it was taken.

Enum: "last" "next" "point"
quantity
string

The name of the measured quantity.

Ideally, this is the same as the last segment of the metric name.

Examples: "power" "temperature"
description
string

A human-readable description of the measurement quantity

Additional properties are allowed.

Additional properties are allowed.

Request examples

Payload 
{
  "function": "source.declare_metrics",
  "metrics": [
    "elab.bahka.power"
  ]
}
This example has been generated automatically.

Reply

Payload
object

Acknowledgement that metrics have been declared successfully

Additional properties are allowed.

Reply examples

Payload 
{}
This example has been generated automatically.

RPC transformer.register

Request

Register a transformer on the network

Payload
object
function
required
string
must match ([a-z_]+\.)+[a-z_]+

A string identifying the requested RPC function

Const: "transformer.register"

Additional properties are allowed.

Request examples

Payload 
{
  "function": "transformer.register"
}
This example has been generated automatically.

Reply

Payload
object
dataExchange
string

Name of the exchange to which data points should be published

Examples: "metricq.data"
config
object

A client configuration object

Examples: { "reportNeighboursDogActivity": true, "metricSourceChannels": { "kittens.front-flap.opened.count": "automation.doors.front.catflap.triggered#cumulative", "kittens.water-bowl.1.volume": "automation.volume-sensors[5]" } } { "clientSpecificOption": 42, "monitorKittenHealth": true }

Additional properties are allowed.

Additional properties are allowed.

Reply examples

Payload 
{
  "dataExchange": "metricq.data",
  "config": {
    "reportNeighboursDogActivity": true,
    "metricSourceChannels": {
      "kittens.front-flap.opened.count": "automation.doors.front.catflap.triggered#cumulative",
      "kittens.water-bowl.1.volume": "automation.volume-sensors[5]"
    }
  }
}
This example has been generated automatically.

RPC transformer.declare_metrics

Request

Declare a list of metrics which this transformer provides

Payload
object
function
string
must match ([a-z_]+\.)+[a-z_]+

A string identifying the requested RPC function

Const: "transformer.declare_metrics"
metrics
required
oneOf

A collection of metric names, with optional metadata attached

0
array<string>
Unique

A list of metric names

Items:

0
string
must match ([a-zA-Z][a-zA-Z0-9_]+\.)+[a-zA-Z][a-zA-Z0-9_]+
Examples: "elab.bahka.power" "elab.ariel.package0.dram.current" "taurus.taurusi4101.cpu0.power"

Additional items are allowed.

1
object

A mapping of metric names to metadata objects

Examples: { "elab.bahka.power": { "rate": 20, "scope": "last", "unit": "W" } }

Additional properties must adhere to the following schema:

(property name)
object

A metadata object

Examples: { "rate": 0.1 }
unit
string

The unit symbol according to SI, such as "V" for voltage or "s" for time.

If necessary, the SI prefix is included, e.g. "kV", "ms", or "kiB/s". Dimensionless quantities such as counts use either an empty string ("") or the appropriate symbol (e.g. "rad").

Examples: "V" "kV" "s" "kiB/s" "rad" ""
rate
integer

The rate in Sa/s (samples per second) or Hz at which new values of this metric are typically produced. In practice, a source does not necessarily need to produce values exactly at this rate, but the value given should be good estimate.

scope

The temporal validity of a single measured value.

A scope of "last" indicates that a measured value was valid up to now, "next" that it is valid from now on. A scope of "point" means that any measurement is only valid at exactly the moment it was taken.

Enum: "last" "next" "point"
quantity
string

The name of the measured quantity.

Ideally, this is the same as the last segment of the metric name.

Examples: "power" "temperature"
description
string

A human-readable description of the measurement quantity

Additional properties are allowed.

Additional properties are allowed.

Request examples

Payload 
{
  "function": "transformer.declare_metrics",
  "metrics": [
    "elab.bahka.power"
  ]
}
This example has been generated automatically.

Reply

Payload
object

Acknowledgement that metrics have been declared successfully

Additional properties are allowed.

Reply examples

Payload 
{}
This example has been generated automatically.

RPC transformer.subscribe

Request

transformer.subscribe

Subscribe to receive data points for a set of metrics

Payload
object
function
required
string
must match ([a-z_]+\.)+[a-z_]+

A string identifying the requested RPC function

Const: "transformer.subscribe"
metrics
required
array<string>
Unique

A list of metric names

Items:

0
string
must match ([a-zA-Z][a-zA-Z0-9_]+\.)+[a-zA-Z][a-zA-Z0-9_]+
Examples: "elab.bahka.power" "elab.ariel.package0.dram.current" "taurus.taurusi4101.cpu0.power"

Additional items are allowed.

metadata
boolean

Whether to include metadata for each metric in the reponse.

If set to false, the result is an array of metric names, if set to true, an object mapping metric names to metadata objects is returned.

Default: false

Additional properties are allowed.

Request examples

Payload 
{
  "function": "transformer.subscribe",
  "metrics": [
    "elab.bahka.power"
  ],
  "metadata": false
}
This example has been generated automatically.

Reply

transformer.subscribe

transformer.subscribe response

Payload
object
dataServerAddress
string
url

URL pointing to the AMQP broker where data queues are handled

Examples: "amqp://user:pass@localhost/data-vhost" "amqps://metricq.example.com:50505/"
dataQueue
string
uri

The AMQP queue at which data points for the subscribed metrics will arrive.

Examples: "amqp://user:pass@localhost/vhost" "amqps://metricq.example.com:50505/"
metrics
oneOf

A collection of metric names, with optional metadata attached

0
array<string>
Unique

A list of metric names

Items:

0
string
must match ([a-zA-Z][a-zA-Z0-9_]+\.)+[a-zA-Z][a-zA-Z0-9_]+
Examples: "elab.bahka.power" "elab.ariel.package0.dram.current" "taurus.taurusi4101.cpu0.power"

Additional items are allowed.

1
object

A mapping of metric names to metadata objects

Examples: { "elab.bahka.power": { "rate": 20, "scope": "last", "unit": "W" } }

Additional properties must adhere to the following schema:

(property name)
object

A metadata object

Examples: { "rate": 0.1 }
unit
string

The unit symbol according to SI, such as "V" for voltage or "s" for time.

If necessary, the SI prefix is included, e.g. "kV", "ms", or "kiB/s". Dimensionless quantities such as counts use either an empty string ("") or the appropriate symbol (e.g. "rad").

Examples: "V" "kV" "s" "kiB/s" "rad" ""
rate
integer

The rate in Sa/s (samples per second) or Hz at which new values of this metric are typically produced. In practice, a source does not necessarily need to produce values exactly at this rate, but the value given should be good estimate.

scope

The temporal validity of a single measured value.

A scope of "last" indicates that a measured value was valid up to now, "next" that it is valid from now on. A scope of "point" means that any measurement is only valid at exactly the moment it was taken.

Enum: "last" "next" "point"
quantity
string

The name of the measured quantity.

Ideally, this is the same as the last segment of the metric name.

Examples: "power" "temperature"
description
string

A human-readable description of the measurement quantity

Additional properties are allowed.

Additional properties are allowed.

Reply examples

Payload 
{
  "dataServerAddress": "amqp://user:pass@localhost/data-vhost",
  "dataQueue": "amqp://user:pass@localhost/vhost",
  "metrics": [
    "elab.bahka.power"
  ]
}
This example has been generated automatically.

RPC db.register

Register a database on the network.

Request

Payload
object
function
required
string
must match ([a-z_]+\.)+[a-z_]+

A string identifying the requested RPC function

Const: "db.register"

Additional properties are allowed.

Request examples

Payload 
{
  "function": "db.register"
}
This example has been generated automatically.

Reply

Payload
object
dataServerAddress
string
url

URL pointing to the AMQP broker where data queues are handled

Examples: "amqp://user:pass@localhost/data-vhost" "amqps://metricq.example.com:50505/"
dataExchange
string

Name of the exchange to which data points should be published

Examples: "metricq.data"
dataQueue
string
uri

Metrics to be saved in the DB arrive on this queue

Examples: "amqp://user:pass@localhost/vhost" "amqps://metricq.example.com:50505/"
historyQueue
string
uri

Requests for historic data arrive on this queue

Examples: "amqp://user:pass@localhost/history" "amqps://metricq.example.com:50505/"
config
object

A client configuration object

Examples: { "reportNeighboursDogActivity": true, "metricSourceChannels": { "kittens.front-flap.opened.count": "automation.doors.front.catflap.triggered#cumulative", "kittens.water-bowl.1.volume": "automation.volume-sensors[5]" } } { "clientSpecificOption": 42, "monitorKittenHealth": true }

Additional properties are allowed.

Additional properties are allowed.

Reply examples

Payload 
{
  "dataServerAddress": "amqp://user:pass@localhost/data-vhost",
  "dataExchange": "metricq.data",
  "dataQueue": "amqp://user:pass@localhost/vhost",
  "historyQueue": "amqp://user:pass@localhost/history",
  "config": {
    "reportNeighboursDogActivity": true,
    "metricSourceChannels": {
      "kittens.front-flap.opened.count": "automation.doors.front.catflap.triggered#cumulative",
      "kittens.water-bowl.1.volume": "automation.volume-sensors[5]"
    }
  }
}
This example has been generated automatically.

RPC db.subscribe

Request to receive data points for metrics to be saved in the DB.

Request

Payload
object
Examples: { "function": "db.subscribe", "metrics": [ "building-F.room-A14.temperature.celcius" ], "metadata": true } { "function": "db.subscribe", "metrics": [ { "name": "history-name.foo-metric", "input": "test.foo-metric" } ] }
function
required
string
must match ([a-z_]+\.)+[a-z_]+

A string identifying the requested RPC function

Const: "db.subscribe"
metrics
required
oneOf

A list of metrics to save, possibly with custom names for history requests.

0
array<string>

A list of metrics to save in the DB

Items:

0
string
must match ([a-zA-Z][a-zA-Z0-9_]+\.)+[a-zA-Z][a-zA-Z0-9_]+
Examples: "elab.bahka.power" "elab.ariel.package0.dram.current" "taurus.taurusi4101.cpu0.power"

Additional items are allowed.

1
array<object>

A list of metrics to save, with custom names for history requests. Queue bindings for the dataQueue will use input, while queue bindings for the historyQueue will use name.

name
required
string
must match ([a-zA-Z][a-zA-Z0-9_]+\.)+[a-zA-Z][a-zA-Z0-9_]+
Examples: "elab.bahka.power" "elab.ariel.package0.dram.current" "taurus.taurusi4101.cpu0.power"
input
required
string
must match ([a-zA-Z][a-zA-Z0-9_]+\.)+[a-zA-Z][a-zA-Z0-9_]+
Examples: "elab.bahka.power" "elab.ariel.package0.dram.current" "taurus.taurusi4101.cpu0.power"

Additional items are allowed.

metadata
boolean

Whether to include metadata for each metric in the reponse.

If set to false, the result is an array of metric names, if set to true, an object mapping metric names to metadata objects is returned.

Default: false

Additional properties are allowed.

Request examples

Payload
Example #1
{
  "function": "db.subscribe",
  "metrics": [
    "building-F.room-A14.temperature.celcius"
  ],
  "metadata": true
}
Example #2
{
  "function": "db.subscribe",
  "metrics": [
    {
      "name": "history-name.foo-metric",
      "input": "test.foo-metric"
    }
  ]
}

Reply

After successful subscription, this contains the broker address and queue on which data points for the requested metrics arrive. The metrics in question are returned, optionally with their metadata attached.

Payload
object
dataServerAddress
string
url

URL pointing to the AMQP broker where data queues are handled

Examples: "amqp://user:pass@localhost/data-vhost" "amqps://metricq.example.com:50505/"
dataQueue
string
uri

The AMQP queue at which data points for the subscribed metrics will arrive.

Examples: "amqp://user:pass@localhost/vhost" "amqps://metricq.example.com:50505/"
metrics
oneOf

A collection of metric names, with optional metadata attached

0
array<string>
Unique

A list of metric names

Items:

0
string
must match ([a-zA-Z][a-zA-Z0-9_]+\.)+[a-zA-Z][a-zA-Z0-9_]+
Examples: "elab.bahka.power" "elab.ariel.package0.dram.current" "taurus.taurusi4101.cpu0.power"

Additional items are allowed.

1
object

A mapping of metric names to metadata objects

Examples: { "elab.bahka.power": { "rate": 20, "scope": "last", "unit": "W" } }

Additional properties must adhere to the following schema:

(property name)
object

A metadata object

Examples: { "rate": 0.1 }
unit
string

The unit symbol according to SI, such as "V" for voltage or "s" for time.

If necessary, the SI prefix is included, e.g. "kV", "ms", or "kiB/s". Dimensionless quantities such as counts use either an empty string ("") or the appropriate symbol (e.g. "rad").

Examples: "V" "kV" "s" "kiB/s" "rad" ""
rate
integer

The rate in Sa/s (samples per second) or Hz at which new values of this metric are typically produced. In practice, a source does not necessarily need to produce values exactly at this rate, but the value given should be good estimate.

scope

The temporal validity of a single measured value.

A scope of "last" indicates that a measured value was valid up to now, "next" that it is valid from now on. A scope of "point" means that any measurement is only valid at exactly the moment it was taken.

Enum: "last" "next" "point"
quantity
string

The name of the measured quantity.

Ideally, this is the same as the last segment of the metric name.

Examples: "power" "temperature"
description
string

A human-readable description of the measurement quantity

Additional properties are allowed.

Additional properties are allowed.

Reply examples

Payload 
{
  "dataServerAddress": "amqp://user:pass@localhost/data-vhost",
  "dataQueue": "amqp://user:pass@localhost/vhost",
  "metrics": [
    "elab.bahka.power"
  ]
}
This example has been generated automatically.

RPC history.register

Register a history client on the network.

Request

Payload
object
function
required
string
must match ([a-z_]+\.)+[a-z_]+

A string identifying the requested RPC function

Const: "history.register"

Additional properties are allowed.

Request examples

Payload 
{
  "function": "history.register"
}
This example has been generated automatically.

Reply

Payload
object
dataServerAddress
string
url

URL pointing to the AMQP broker where data queues are handled

Examples: "amqp://user:pass@localhost/data-vhost" "amqps://metricq.example.com:50505/"
historyExchange
string
Examples: "metricq.history"
historyQueue
string
uri

Requests for historic data arrive on this queue

Examples: "amqp://user:pass@localhost/history" "amqps://metricq.example.com:50505/"
config
object

A client configuration object

Examples: { "reportNeighboursDogActivity": true, "metricSourceChannels": { "kittens.front-flap.opened.count": "automation.doors.front.catflap.triggered#cumulative", "kittens.water-bowl.1.volume": "automation.volume-sensors[5]" } } { "clientSpecificOption": 42, "monitorKittenHealth": true }

Additional properties are allowed.

Additional properties are allowed.

Reply examples

Payload 
{
  "dataServerAddress": "amqp://user:pass@localhost/data-vhost",
  "historyExchange": "metricq.history",
  "historyQueue": "amqp://user:pass@localhost/history",
  "config": {
    "reportNeighboursDogActivity": true,
    "metricSourceChannels": {
      "kittens.front-flap.opened.count": "automation.doors.front.catflap.triggered#cumulative",
      "kittens.water-bowl.1.volume": "automation.volume-sensors[5]"
    }
  }
}
This example has been generated automatically.

RPC discover

Request

A discovery request sent to all clients online

Payload
object
function
required
string
must match ([a-z_]+\.)+[a-z_]+

A string identifying the requested RPC function

Const: "discover"

Additional properties are allowed.

Request examples

Payload 
{
  "function": "discover"
}
This example has been generated automatically.

Reply

A discovery response including operational information of a client

Payload
alive
boolean
Default: true
currentTime
string
date-time

Current time on this host

startingTime
string
date-time

When this client was started and first connected to the network

uptime
integer
nanoseconds

Number of nanoseconds since startup of this client. If missing, assume this is the difference between currentTime and startingTime.

metricqVersion
string

The version of the MetricQ client library that this client uses to communicate with the network. This value is intended for human consumption and its format should not be relied opon. Nonetheless, a format of <library-name>/<version> is encouraged.

Examples: "metricq-python/1.1.4" "metricq-cpp/r501.ge944379"
pythonVersion
string

The version of the running Python interpreter, if the client uses the MetricQ Python bindings.

Examples: "3.9.2"
hostname
string

The hostname identifying the machine that this client runs on.

Examples: "bahka" "192.0.2.42"

Reply examples

Payload 
{
  "alive": true,
  "currentTime": "2019-08-24T14:15:22Z",
  "startingTime": "2019-08-24T14:15:22Z",
  "uptime": 0,
  "metricqVersion": "metricq-python/1.1.4",
  "pythonVersion": "3.9.2",
  "hostname": "bahka"
}
This example has been generated automatically.

RPC config

Request

Provide an updated configuration object to a client

Payload
object
function
required
string
must match ([a-z_]+\.)+[a-z_]+

A string identifying the requested RPC function

Const: "config"

Additional properties are allowed.

Request examples

Payload 
{
  "function": "config"
}
This example has been generated automatically.

Reply

Configuration acknowledgement

Payload
object

Acknowledgement that configuration has been received successfully

Additional properties are allowed.

Reply examples

Payload 
{}
This example has been generated automatically.