.. py:currentmodule:: metricq

.. _metric-metadata:

Metric Metadata
===============

Each :term:`metric<Metric>` known to the MetricQ network includes metadata in the form of arbitrary
`name`/`value` pairs, where `name` are strings and `values` are `JSON` values.
Metadata values are free-form and can be used to store any information useful and related to a metric.
Though, some restrictions apply in the form of :ref:`reserved fields <metric-metadata-reserved>`
and :ref:`standardized fields <metricq-metadata-standardized>`.
Since this is JSON, the `name` should be in camelCase.

.. _metric-metadata-reserved:

Reserved Fields
---------------

Reserved fields may not be used when declaring metadata for a metric.
Tools consuming metadata are free to make use of these fields, though.

All fields starting with :literal:`_`
    Reserved for the metadata storage backend implementation.

:literal:`_id` (`string`)
    The name of the metric associated to this set of metadata.

:literal:`date` (`string`)
    `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ formatted date at which the metadata was last updated (by :meth:`Source.declare_metrics`).
    This is generated by the manager but can be overwritten by the source.

:literal:`historic` (`bool`)
    Indicates whether this is stored in a database or not.
    Set by the manager.

:literal:`source` (`string`)
    :term:`Token` of the source that produces this metric.
    Set by the manager.

.. _metricq-metadata-standardized:

Standardized Fields
-------------------

Some `fields` have a defined meaning that should be respected.
Consuming tools might handle and display these fields in a special way.

:literal:`description` (`string`)
    A human readable description of the measured quantity.
    For example, `"Temperature of rack A2 in room E13"` would be a description for a metric :literal:`example.room-E13.rack-A2.temperature`.

:literal:`unit` (`string`)
    The unit symbol according to SI, e.g. :literal:`"V"` for voltage or :literal:`"s"` for time.
    If necessary, the SI prefix is included, e.g., :literal:`"kV"`, :literal:`"ms"`, or :literal:`"kiB/s"`.
    Dimensionless quantities (e.g. counts) use either an empty string :literal:`""` or the appropriate symbol, e.g., :literal:`"rad"`.
    That is, the SI unit `1` is omitted as it is typically not shown.

:literal:`rate` (`number`)
    The rate in `Sa/s` (samples per second) or `Hz` at which new values of this metric are typically produced.
    This is a hint to consumers and should be treated as a "best guess",
    a source does not need to produce values at a perfectly constant rate.

:literal:`interval` (`string`)
    This is the reciprocal of :literal:`rate`, but as a string.
    It corresponds to :meth:`Timedelta.from_string` /  :attr:`Timedelta.precise_string`.
    This can allow for more precise values and less floating point shenanigans, e.g., `3s` instead of a rate of `0.3333333`.


:literal:`scope` (one of :literal:`"last"`, :literal:`"next"` or :literal:`"point"`)
    This describes the temporal validity of a single measurement value.

:literal:`quantity` (`string`)
    The quantity being measured.
    Ideally this is the same as the last segment of the metric name, e.g. :literal:`"power"` or :literal:`"temperature"`.

:literal:`chunkSize` (`number` or :literal:`null`)
    In Python, this is set by the metricq library itself and should not be set by the user.
    The number of data points sent to the network in a single message,
    see :meth:`Source.chunk_size` and :meth:`Source.send`.

    Setting this to :literal:`null` means that the chunk size is either
    not known or varies between messages.

    This is useful for monitoring, as :literal:`rate` / :literal:`chunkSize`
    gives an estimate of the expected message rate for a source.