MQTT Session Metadata

Establish session-scoped context for telemetry messages sent during one MQTT session, such as extra labels or firmware build ID.

A Session Metadata message lets a device describe the MQTT session before it starts sending logs, metrics, or crash data. It is optional, but it is useful whenever the same context applies to many messages: firmware build ID, SDK or agent version, device run ID, OS version, hardware revision, or any other labels you want to search and filter by later.

Send it once, right after the MQTT connection is established, before the first telemetry message. Spotflow then applies that metadata to subsequent messages in the same session.

How it works

Publish a message with messageType set to SESSION_METADATA to the normal device-to-cloud ingestion topic:

Use ingest-json for JSON payloads.
Use ingest-cbor for CBOR payloads.

The metadata describes the current MQTT connection and device run. Most integrations send it once with all known session-level fields. It applies only to messages sent after it in the same MQTT session. If you send another Session Metadata message later in the same session, the new context replaces the previous one for subsequent messages.

You can still set labels on individual log or metric messages. Message-level labels are merged with session-level labels, and message-level labels take precedence when the same key appears in both places.

One-shot MQTT CLI commands usually connect, publish one message, and disconnect. To test Session Metadata, use a client or script that can publish metadata and telemetry on the same connection.

Message schema

Only messageType is required. All other fields are optional and can be included when they add useful context for the session.

Publish Session Metadata messages to ingest-json using the following structure:

{
    // Required: identifies this message as Session Metadata
    "messageType": "SESSION_METADATA",

    // (Optional) SDK, MQTT client, or integration that opened the session
    "mqttAgent": "custom-mqtt-client/1.2.0",

    // (Optional) firmware build ID as a lowercase 40-character SHA1 hex string
    "buildId": "184952ef1dde1c12364174d40618f9cca9d1814d",

    // (Optional) current device run ID, usually changed after each boot
    "deviceRunId": 42,

    // (Optional) 64-bit monotonic device uptime in milliseconds.
    // Used to calculate deviceTimestampMs for later log messages that only provide deviceUptimeMs.
    "deviceUptimeMs": 1200,

    // (Optional) IANA time zone name used as a hint for UI defaults and queries
    "timeZone": "Europe/Prague",

    // (Optional) labels applied to subsequent messages in this MQTT session.
    // Keys must be non-empty strings; values can be strings, numbers, or booleans.
    "labels": {
        "osVersion": "0.42.0",
        "hardwareRevision": "rev-b",
        "firmwareChannel": "staging"
    }
}

Publish Session Metadata messages to ingest-cbor using the following structure. CBOR payloads can use numeric property keys to reduce payload size:

session-metadata-message = {
    0 => 1,                         ; messageType: SESSION_METADATA (required)
    ? 8 => tstr,                    ; mqttAgent: SDK, MQTT client, or integration name
    ? 14 => bstr .size 20,          ; buildId: firmware SHA1 bytes
    ? 5 => labels,                  ; labels: session-level labels applied to subsequent messages
    ? 6 => uint,                    ; deviceUptimeMs: used to calculate timestamps for later log messages
    ? 20 => tstr,                   ; timeZone: IANA time zone name
    ? 30 => uint                    ; deviceRunId: current device run ID, usually changed after boot
}

labels = {* (tstr => (tstr / int / float / bool))} ; non-empty string keys; string, number, or boolean values

JSON example

{
    "messageType": "SESSION_METADATA",
    "mqttAgent": "custom-mqtt-client/1.2.0",
    "buildId": "184952ef1dde1c12364174d40618f9cca9d1814d",
    "deviceRunId": 42,
    "labels": {
        "osVersion": "0.42.0",
        "hardwareRevision": "rev-b",
        "firmwareChannel": "staging"
    }
}

After this message, a log can be much smaller while still carrying the session context:

{
    "body": "Lock motor calibration completed",
    "severity": "INFO",
    "labels": {
        "component": "lock-motor"
    }
}

In Spotflow, the log can be filtered by component=lock-motor from the log message and by osVersion=0.42.0, hardwareRevision=rev-b, and firmwareChannel=staging from the Session Metadata message.

MQTT Session Metadata

How it works

Message schema

JSON example

Learn more

Guide: Logging with MQTT

Guide: Metrics with MQTT

Guide: Crash reports with MQTT

On this page