Trace Context: MQTT protocol

This is an extension document for the [[[TRACE-CONTEXT]]] specification. It defines the mapping of Trace Context fields to the MQTT protocol.

This is the First Public Working Draft (FPWD) of a MQTT Trace Context specification.

MQTT v5.0 format

[[!MQTT5]] is a messaging protocol. As any messaging protocol it is commonly used as a mechanism for asynchronous or postponed execution of tasks. In those scenarios message publishers need to communicate the trace context of execution to the consumer of that same message. So publishing and consuming tasks can be analyzed as a part of a single distributed trace.

Trace context fields placement in a message

Starting [[[!MQTT5]]] MQTT defines a message as a payload with the associated User Properties. User properties MUST be used to propagate trace context and MUST follow the following convention.

Field traceparent

Field traceparent MUST be set in user properties under the name traceparent. All lower case, no delimiters. Value of the traceparent field MUST follow the [[!TRACE-CONTEXT]] format. Example of traceparent field value:

traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

Field tracestate

Field tracestate MUST be set in user properties under the name tracestate. All lower case, no delimiters. Value of the tracestate field MUST follow the [[!TRACE-CONTEXT]] format - comma delimited list of name-value pairs. Example of tracestate field value:

tracestate: congo=lZWRzIHRoNhcm5hbCBwbGVhc3VyZS4,rojo=00f067aa0ba902b7

MQTT v3 recommendation

Before [[[MQTT5]]] there were no extensibility metadata defined for the messages. Thus this section is only a set of recommendations on how trace context can be implemented, not the specification.

JSON payload

It is common that MQTT message payloads are represented as a JSON string. In this case it is recommended to set traceparent and tracestate fields as a fields on a outermost JSON object.

For example, if original payload looks like following:

{
    "_type": "cmd",
    "action": "setConfiguration",
    "configuration": {
        "_type":"configuration",
        "settingA": "value A",
        "settingB": 42
        }
}

Payload with trace context configured will look like following:

{
    "_type": "cmd",
    "action": "setConfiguration",
    "configuration": {
        "_type":"configuration",
        "settingA": "value A",
        "settingB": 42
        },
    "traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
    "tracestate": "congo=BleGNlZWRzIHRohbCBwbGVhc3VyZS4"
}

Handling end-to-end encryption

TBD: Should there be a note that for e2e encryption one may decide to send trace context un-encrypted while the rest of the message can be encrypted?

Binary payload

For binary payload - Trace Context: binary protocol may be used to propagate trace context fields.