Glossary

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Client

An application that connects to the MetricQ network. It is uniquely identified on the network by its Token. Clients may produce and consume data (see Source, Sink) or perform management tasks (see Manager).

Data Point

A time-value pair, describing a measurement of a measurand at a specific point in time.

Manager

A Client responsible for managing RPC requests on the network.

Metadata

Each Metric may be declared by a Source with additional metadata attached. These are arbitrary field-value pairs where value is an arbitrary JSON values. See Metric Metadata for more details.

Metric

A named series of time-value pairs, called Data Points. Metrics are at the core of the MetricQ data exchange. They describe how one specific measurand (e.g. the temperature in room E27 in ℃, CPU utilization on system hal-9000 in %) evolves over time. Clients must ensure the following properties for metrics they produce:

Metric names must be unique on the network: For any metric $m$, at any point in time, there shall be at most one Source online producing data points for $m$. A single source may of course produce values for many distinct metrics.
Any valid Metric must be ordered strictly chronologically:: Suppose $(t₁, v₁)$ and $(t₂, v₂)$ are two Data Points of the same Metric. If $(t₁, v₁)$ is sent to the network before $(t₂, v₂)$, then it is necessary that $t₁ < t₂$.

Sink

A Client that receives Data Points for one or several Metrics provided by other clients on the network.

Use metricq.Sink to build your own Sinks; see Building a MetricQ Sink for a quick how-to.

Source

A Client that produces Data Points for one or several Metrics. These are then available for consumption by other Clients on the network.

Token

A string uniquely identifying a Client on the MetricQ network.

Tokens shall be unique on the network:

Any set of Clients online at the same time must have distinct Tokens.

Tokens should be formatted in kebab-case and have a prefix identifying the type of source:

Examples of good client tokens are:

source-sysinfo-hal-9000: a Source measuring system information of the system hal-9000, for example CPU utilization, free disc space, etc.
sink-websocket-sysinfo-display: a Sink build with metric-sink-websocket that streams system information to a web frontend for display

Optimally, a client token is written as <$type>-<$implementation>-<$instance>. source-sysinfo-hal-9000 identifies a client of type Source, using an implementation producing system-info related metrics, for the concrete host (instance) hal-9000.

Sometimes it is desirable for multiple instances of the same Client to be online at same. They shall be distinguished by a unique suffix:

Append a UUID, version 4 (according to RFC 4122#section-4.1.3) as a hex string to the token like so:
client-example-4198bdddab794e9f8d774a590651cdc1