Understanding Metrics

Applies to CoCoCo platform v1.0.0-rc.31. Sending a metric over MQTT and viewing it were both run on that version.

What are Metrics?

A Metric is a time series of numeric values that belongs to a Device, for example a temperature, a speed or a counter. Each Metric has a name, a kind (Gauge, Counter, Status or Rate) and a unit. When a Device sends a data point for a name it has not used before, CoCoCo creates the Metric automatically.

Sending Metrics over MQTT

Before you start: the Device needs an MQTT protocol and a Device Token (see How to Create and Manage Device Tokens).

1. Connect to the MQTT URL from the token dialog, presenting the Client certificate and Client key and trusting the Server CA. The broker accepts certificate connections only.
2. Use the Suggested client ID from the token dialog as the MQTT client ID.
3. Publish to the topic s/metrics. The payload is a batch of one or more points:

{
  "points": [
    {
      "name": "temperature",
      "value": 21.5,
      "kind": "GAUGE",
      "unit": "CELSIUS",
      "tags": { "location": "hall-1" },
      "displayName": "Temperature"
    }
  ]
}

Field
name	required — identifies the Metric on this Device
value	required — a finite number
kind	optional — GAUGE, COUNTER, STATUS or RATE; only used when the Metric is created; default GAUGE
unit	optional — for example CELSIUS, PERCENT or COUNT; only used when the Metric is created; default NONE. For a unit that is not in the list, such as sheets, use CUSTOM
customUnit	optional — the name of the unit when unit is CUSTOM, for example Sheets
tags	optional — key-value labels for the point; every value must be text
timestamp	optional — ISO 8601; default is the time the point arrives
displayName	optional — readable name; only used when the Metric is created

Write kind and unit in capital letters and use only the listed values, and send every tag value as text. One message can carry up to 10,000 points.

A new data point can take a few seconds before it shows up.

Viewing Metrics

1. In the sidebar, under IoT, click Metrics.
2. Click a Metric. Its page shows the kind, the number of data points, the Device, and a Time Series chart. Choose the period with 1h, 6h, 24h, 7d, 30d or all; 24h is selected when the page opens. Below the chart, Recent Data Points lists the latest values.

To see the Metrics list you need permission to list metrics (metric:list).