Metrics with MQTT

Collect metrics from any device using standard MQTT interface and analyze them in Spotflow dashboards.

This guide explains how to send metrics from devices running a MQTT client and analyze them in the Spotflow web application.

Connect to the Spotflow MQTT broker

As the very first step, check the following basic integration guide:

Quickstart: Connect via MQTT

Publish metrics in JSON or CBOR format

Metrics can be sent over MQTT using either JSON or CBOR payloads.

Publish metric messages to the ingest-json topic using the following schema:

{
    "messageType": "METRIC",
    "metricName": "cpu_utilization_percent",

    // Optional for PT0S/PT1M/PT1H/P1D metrics, present for aggregated metrics
    "aggregationInterval": "PT1M",

    // Optional labels for dimensional metrics
    "labels": {
        "interface": "wlan0"
    },

    // Device uptime when metric sample/window was produced
    "deviceUptimeMs": 123456,

    // Sequence number within a metric stream
    "sequenceNumber": 42,

    // For aggregated metrics: sum over the window
    // For PT0S/no aggregation: raw sample value
    "sum": 318.7,

    // Optional overflow marker for integer sums
    "sumTruncated": false,

    // Present for aggregated metrics
    "count": 30,
    "min": 5.2,
    "max": 18.1
}

Publish metric messages to the ingest-cbor topic using the following schema:

metric-message = {
    0 => 5,                      ; messageType: metric
    21 => tstr,                  ; metricName
    ? 22 => agg-interval,        ; aggregationInterval (0/1/3/4)
    ? 5 => labels,               ; labels map
    ? 6 => int,                  ; deviceUptimeMs
    ? 13 => uint,                ; sequenceNumber
    24 => metric-value,          ; sum (or raw value for no aggregation)
    ? 25 => bool,                ; sumTruncated (optional)
    ? 26 => uint,                ; count (for aggregated metrics)
    ? 27 => metric-value,        ; min (for aggregated metrics)
    ? 28 => metric-value         ; max (for aggregated metrics)
}

labels = {* (tstr => tstr)}
metric-value = int / float

; Aggregation interval enum values used by device module
agg-none = 0                    ; PT0S
agg-1min = 1                    ; PT1M
agg-1hour = 3                   ; PT1H
agg-1day = 4                    ; P1D
agg-interval = (agg-none / agg-1min / agg-1hour / agg-1day)

Available system metrics

When using Spotflow system metrics, the following metric names, value data, and labels are used:

Metric name	Value data	Expected labels
`heap_free_bytes`	Free heap bytes (`int`)	None
`heap_allocated_bytes`	Allocated heap bytes (`int`)	None
`cpu_utilization_percent`	CPU utilization in percent (`float`)	None
`thread_stack_free_bytes`	Free stack bytes per thread (`int`)	`thread`
`thread_stack_used_percent`	Used stack percentage per thread (`float`)	`thread`
`network_tx_bytes`	Transmitted bytes per network interface (`int`)	`interface`
`network_rx_bytes`	Received bytes per network interface (`int`)	`interface`
`connection_mqtt_connected`	MQTT connection state (`int`, `0` or `1`)	None
`boot_reset`	Reset event marker (`int`, value `1`)	`reason`
`uptime_ms`	Device uptime in milliseconds (`int`)	None