13. System Metrics

This chapter describes how to report and read system metrics. System metrics are a diagnostic tool allowing to retrieve data relating to the a machine health and performance.

13.1. Overview

System metrics intend to provide machine-level diagnostics. Any host/machine participating in the system should be able to be configured and reports its system metrics data.

A SystemMetrics Unify cluster has been designed for this reporting purpose. It operates as all other clusters, with Attributes, SupportedCommands and Commands.

The difference about this cluster, is that it does not use any UNID, but instead Machine IDs. An overview of the publications under this cluster is shown below:

ucl/by-machine-id/<id>/SystemMetrics/Attributes/<AttributeName>/Reported - { "value": 23 }
ucl/by-machine-id/<id>/SystemMetrics/SupportedCommands - { "value": ["WriteAttributes"] }
ucl/by-machine-id/<id>/SystemMetrics/Commands/<CommandName> - { "field1": 42 }

No endpoints are used for this cluster.

Note that all communications and commands executions are expected to be instantaneous in the ucl/by-machine-id/ topic space. Therefore, the Desired value of attributes MUST NOT be published under this topic space.

13.2. Machine ID

Each Machine connecting to the system is responsible for creating a unique Machine ID.

If no unique machine-id is available natively on the platform running Unify components, the following elements can be used as a Machine ID:

• FQDN: Fully Qualified Domain Name

• hostname: Hostname assigned to the machine

• uuid: Disk UUIDs

Developers and system integrators SHOULD ensure make sure that Machine IDs connected to a given MQTT brokers are unique, so no collisions will happens when reporting SystemMetrics.

13.3. Example

The minimum required attribute for the System Metrics is the ReportingIntervalSeconds attribute. This attribute is a setting that controls how often the system metrics attributes are reported, in seconds. The value 0 means that the system metrics are not reported.

System Metrics attributes MUST be published once at startup, and subsequently following the frequency configured in the ReportingIntervalSeconds attribute.

ReportingIntervalSeconds SHOULD be set to 0 by default and reporting metrics SHOULD be disabled by default.

13.4. System Metrics attributes

System Metrics attributes help reporting the state of a machine on which the unify applications are running.

System Metrics attributes MUST be reported following the ReportingIntervalSeconds, but some exceptions MAY be made if an attribute changes sporadically, like the PowerPlugged attribute.