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.
[[!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.
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.
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
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
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.
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"
}
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?
For binary payload - Trace Context: binary protocol may be used to propagate trace context fields.