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 0/1m/1h/1d metrics, present for aggregated metrics
    "aggregationInterval": "1m",

    // 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 0/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                    ; 0
agg-1min = 1                    ; 1m
agg-1hour = 3                   ; 1h
agg-1day = 4                    ; 1d
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

System metrics are visualized in the built-in Device Dashboard.

Custom metrics

You are not limited to the system metrics listed above. Use any metricName to track application-specific values such as sensor readings, counters, or latencies. The payload format is the same.

For example, an aggregated custom metric with labels:

{
    "messageType": "METRIC",
    "metricName": "lock_operation_duration_ms",
    "aggregationInterval": "1m",
    "labels": {
        "operation": "unlock",
        "method": "nfc"
    },
    "deviceUptimeMs": 120000,
    "sequenceNumber": 5,
    "sum": 1250.0,
    "count": 10,
    "min": 45.2,
    "max": 310.7
}

metricName can be any string. Names are normalized on ingestion (lowercased, special characters replaced with underscores).
aggregationInterval is optional. Omit it or set it to "0" to send raw values without aggregation. Supported values are "0" (no aggregation), "1m" (1 minute), "1h" (1 hour), and "1d" (1 day).
labels is optional. Use it to add dimensional breakdowns to your metric.
For non-aggregated metrics, only sum is required (it represents the raw value). For aggregated metrics, include sum, count, min, and max.