Trace propagation

Configuring trace propagation

Trace propagation is configured using the OTELPCTL attribute on the queue manager and local, model and remote queues.

• OTELTRAC(QMGR)

Manual propagation

Applications that cannot take advantage of automatic trace propagation can perform propagation manually by writing suitable code. This is the default.

Applications that send messages can manually create, or propagate, trace context from the application environment into the message by setting the traceparent and optional tracestate properties in the message using the IBM MQ message property APIs, and then sending the message.

Applications that receive messages can use the IBM MQ message property APIs to extract the trace context properties from the message and copy them into the environment, or into other messages.

Automatic propagation

Applications running in certain environments on z/OS® can make use of automatic propagation. This allows trace context propagation to be performed on behalf of the application, without the application needing to be changed, and without the application needing to make use of, or tolerate, message properties.

Automatic propagation is enabled on IBM MQ by setting OTELPCTL(AUTO) on the queues used by the application. Environment specific configuration, for example in CICS® or IMS, might also be required. Setting OTELPCTL(AUTO) on a queue results in the fast put to waiting getter optimization being disabled.

Automatic propagation when messages are sent

If a message is sent to a queue configured with OTELPCTL(AUTO) from an environment which supports automatic propagation, then the queue manager will take trace context from the environment and set it in the traceparent and tracestate message properties before sending the message. If the message already contains these properties, then trace context will not be automatically propagated.

If a message is sent to a queue configured with OTELPCTL(AUTO) from an environment which does not support automatic propagation, then the queue manager does not manipulate the trace context properties. Applications can manually set the properties if required.

Automatic propagation when messages are received

If messages containing trace context are received from a queue configured with OTELPCTL(AUTO) and the environment supports automatic propagation, then the queue manager removes the trace context properties from the message and passes them to the environment. If the environment is CICS, then trace context might be associated with the current transaction.

The application does not see the trace context message properties. If the only message properties in the message are the trace context properties, then no message properties are returned to the application. This is useful if the application has not been written to use message properties, or cannot tolerate RFH2 headers.

If a CICS or IMS application, running in a version of CICS or IMS that does not support automatic propagation, or has not been configured for automatic propagation, receives a message from a queue configured with OTELPCTL(AUTO), then any trace context properties are removed from the message and discarded. The application does not see the trace context message properties. If the only message properties in the message are the trace context properties, then no message properties are returned to the application. This is useful if the application has not been written to use message properties, or cannot tolerate RFH2 headers.

If messages containing trace context are received from a queue configured with OTELPCTL(AUTO) in other environments that do not support automatic propagation, trace context properties are removed before the message is returned to the application if the application sets MQGMO_PROPERTIES_AS_Q_DEF or MQGMO_NO_PROPERTIES. If the only message properties in the message are the trace context properties, then no message properties are returned to the application. This prevents the application from unexpectedly receiving an RFH2 header that it might not be able to process.

Automatic propagation using distributed queuing or queue manager processes

Messages sent or received over channels have the trace context properties flow with the message regardless of the value of the OTELPCTL attribute.

Messages that are moved via internal queue manager processes, for example the JMS delivery delay processor or the intra-group queuing agent, automatically have trace context propagated regardless of value of the OTELPCTL attribute.

Automatic propagation using OpenTelemetry instrumentation

In some environments, there are zero-code approaches available that automatically start a trace for an application and propagate that context between application components. For example, there is tooling that automatically sets trace context on a JMS message, this tooling can be used with IBM MQ for JMS. It is also possible to use similar tooling with other environments such as Node.js (https://marketaylor.synology.me/?p=1626). Trace context set up by these approaches can be used with IBM MQ on z/OS for as long as the trace context message properties are correctly set.

Automatic propagation using OpenTelemetry instrumentation can be used with IBM MQ on z/OS regardless of the value of the OTELPCTL attribute.

PROPCTL

Automatic propagation takes place before the processing controlled by the PROPCTL attribute on a queue. Therefore, automatic propagation occurs even if OTELPCTL(NONE), or MQGMO_NO_PROPERTIES are used.

In some scenarios, messages with trace context might flow from a queue manager which supports OpenTelemetry to one that does not. If the applications that consume messages from the queue manager which does not support OpenTelemetry cannot tolerate message properties, then configure the queues that they consume from with PROPCTL(NONE), which removes all message properties including the trace context properties. If this is done, the OpenTelemetry trace ends at the point where the messages left the queue manager that supported OpenTelemetry.