Trace context

IBM® MQ will take part in an OpenTelemetry trace if there is trace context in the message. Trace context consists of message properties which can be set manually by an application, or by the environment the application is running in.

Two message properties make up trace context: traceparent and tracestate. These properties follow the W3C specification for trace context (https://www.w3.org/TR/trace-context/). You only need to understand the format of these properties if you are setting them, or manipulating them yourself.

If a distributed queue manager using the IBM MQ OpenTelemetry tracing service is sending messages to IBM MQ on z/OS®, then Instana® specific properties are also set. You do not need to understand the format of these properties.

traceparent

The traceparent property is required for IBM MQ to take part in a trace. If this property is set, then IBM MQ optionally emits spans, and performs automatic propagation. IBM MQ manipulates the content of the traceparent property as it emits spans.

The format of the traceparent property is defined by the W3C specification. An example traceparent is:

00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

A traceparent consists of four fields separated by a hyphen:

version:: The version of the W3C specification used to form the traceparent and tracestate properties. Currently the only available version is 00.
trace-id: This is the globally unique value of the current trace in the form of 32 lower case hexadecimal characters. IBM MQ never changes the value of the trace-id, it is constant for all spans in a trace. In the example, the trace-id is: 0af7651916cd43dd8448eb211c80319c.
parent-id: The ID for a span. This value must be unique for the trace and is in the form of 16 lower case hexadecimal properties. When sending a message to IBM MQ, this is the span ID associated with the application component that sends the message. When receiving messages, this value will have been changed to a new unique value by the queue manager if OTELTRAC(ON) is specified on the queue. In the example, the parent-id is: b7ad6b7169203331
flags: For a version 00 traceparent this can have one of two values: 00 or 01. These two values are used for sampling, as described in the W3C specification. If the flags value is 00, then IBM MQ does not emit spans, even if OTELTRAC(ON) has been specified on the relevant queue. If the flags value is 01, then IBM MQ does emit spans, if OTELTRAC(ON) has been specified on the relevant queue.

If a message is sent or received from a queue with the traceparent property set and that queue has OTELTRAC(ON) or OTELPCTL(AUTO) set, then the format of the traceparent property is validated according to the rules described in the W3C specification. These rules are as follows, where HD is a lower-case hexadecimal digit, 0-9a-f:

Header must start with 2HD-
If version is 00, then header must be in the form 2HD-32HD-16HD-2HD
version cannot be ff
trace-id cannot be all zeroes
parent-id cannot be all zeroes
If version > 0 then after version expect 32HD-
If version > 0 then after trace-id expect 16HD-
If version > 0 then after parent-id expect 2HD
If version > 0 and the above rules apply treat as a version 0 traceparent

If validation fails, then both the traceparent and tracestate properties are removed from the message and no span is emitted. This is tracked using SMF statistics QMSTOCPD, QMSTOCGD, QQSTOCPD and QQSTOCGD. For more information, see Message manager data records and Queue data records.

tracestate

The tracestate property is an optional extension to traceparent and contains vendor specific data in name value pairs. For example: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE.

IBM MQ does not perform any validation on tracestate, and never alters its contents, unless automatic context propagation is enabled. For more information, see Trace propagation.

Instana trace context

If messages are sent to IBM MQ for z/OS with trace context provided by the IBM MQ OpenTelemetry tracing service, then five properties make up trace context: traceparent, tracestate, and three beginning with X_INSTANA. If IBM MQ for z/OS has been configured to emit spans or perform automatic trace propagation, then any X_INSTANA properties are deleted from the message.