For those who may not be aware, the IBM MQ Appliance is a dedicated hardware appliance that runs IBM MQ. It hosts queue managers to which business applications can connect to send and receive messages. The appliance has built-in support for high availability and disaster recovery, providing total cost of ownership savings over deploying MQ as a software offering through simplified management and easy-to-install firmware updates.
Observability over one’s MQ real estate is becoming an increasingly essential requirement, with many seeking a better understanding of their message flows. MQ administrators can use this information to improve their MQ implementation. Although MQ includes features such as application activity trace for gathering data on application data flows, these are specific to the MQ offering.
One technology that many are taking advantage of for monitoring is OpenTelemetry (also known as OTel), a vendor-neutral open-source observability framework designed to collect metrics, logs, and trace from a wide range of offerings. This allows customers to view end-to-end application flows and correlate activity throughout their IT estate.
From version 9.3.5, MQ on distributed came with the Instana tracing exit, which could be configured to capture and forward tracing data to existing OpenTelemetry solutions. This allowed customers to observe how applications were behaving within a data flow and identify potential application pain points that could be addressed. At that time, there was no OpenTelemetry support on the MQ Appliance. With the release of 9.4.3, this is no longer the case. The MQ Appliance firmware now includes the OpenTelemetry Tracing Service, which can be configured to send span/trace data to either an IBM Instana endpoint in Instana format or to an alternative endpoint in OTel format.
To support this new service, we have created two new mqcli commands: “setmqots” and “dspmqots”. These commands provide the ability to configure, enable/disable, and display the configuration settings for the OpenTelemetry tracing service on a per-Queue Manager basis.
Golden Path configuration example:
Golden Path configuration example: In this scenario, we will configure a queue manager to send Instana span data to an Instana agent running on a remote node. It is essential to note that the OpenTelemetry tracing service configuration is done on a per-queue manager basis.
Firstly, we have several configuration keys to set up. We can do this using the setmqots command as follows:
setmqots -m QM1 -k INSTANA_AGENT_HOST -v 192.168.20.1
This command specifies the remote Instana agent to which we will send our tracing data for queue manager QM1.
For our example, we end up with the following configuration for QM1, which we can obtain with the following command:
dspmqots -m QM1
INSTANA_AGENT_HOST="192.168.20.1"
LOG_LEVEL="debug"
MONITOR_LEVEL="debug"
SPAN_FORMAT="instana"
If we just want to see the value of one key, we can issue the command:
dspmqots -m {QM_name} -k {key_name}
which will report back just the value for the key.
dspmqots -m QM1 -k LOG_LEVEL
debug
After setting up the configuration for our tracing service, we can enable the service using the command:
setmqots -m QM1 -e
Likewise, we can disable the service for the queue manager with
setmqots -m MAJMON_qm -d
Any configuration changes made and the enablement/disablement of the OpenTelemetry tracing service itself will require a queue manager restart to be applied.
The “setmqots” command provides protection against misconfigurations by confirming the configuration is complete and valid when requested to enable the service, in addition to only permitting the setting of valid keys with syntactically correct values.
We can now start the queue manager and put a message onto one of the queues using the “amqsputc” sample application. Then, using the “amqsiqmc” application, we can get that message. From the above configuration, you should see that the resulting “amqsiqmc” output is something like the following:
Sample AMQSIQMA start
property name <traceparent> value <00-000000000000000008c5f607f9535458-50ed2e9d4e115f57-01>
property name <tracestate> value <in=08c5f607f9535458;50ed2e9d4e115f57>
property name <X_INSTANA_S> value <50ed2e9d4e115f57>
property name <X_INSTANA_T> value <08c5f607f9535458>
property name <X_INSTANA_L> value <1>
message text <Test>
Sample AMQSIQMA end
This shows the RFH2 headers that the OpenTelemetry tracing service added to our messages. You should then be able to use the tracing ID from “X_INSTANA_T” to find the data flow of the messages on the Instana server (assuming the span trace found its way to the Instana agent and then to the server).
If you have configured the span format to be “otel” rather than “instana”, then you will instead see something like the following:
Sample AMQSIQMA start
property name <traceparent> value <00-00000000000000006355a1ea3014a2cb-93fdd9ad53a2962d-01>
property name <tracestate> value <in=00000000000000006355a1ea3014a2cb;93fdd9ad53a2962d>
message text <Test>
Sample AMQSIQMA end
The following JSON shows information about the data flow of the message, which we got from the Instana server based on the X_INSTANA_T ID, we can see information about both the MQPUT and MQGET of the message.
{
"items": [
{
"id": "08c5f607f9535458",
"timestamp": 1749810356666,
"parentId": null,
"foreignParentId": null,
"name": "PUT q1",
"duration": 0,
"minSelfTime": 0,
"networkTime": null,
"callCount": 1,
"errorCount": 0,
"destination": {
"service": {
"id": "cf206726b8ebb88a5337fd8209a8cc0b6b72bcef",
"label": "QM1@MQAppliance"
},
"endpoint": {
"id": "xCNTrRSberRTBxVlWcsuMzlrz10",
"label": "q1",
"type": "MESSAGING"
},
"technologies": [
"ibmMqQueueManager"
]
},
"cursor": {
"@class": ".IngestionOffsetCursor",
"ingestionTime": 1749810487000,
"offset": 1
}
},
{
"id": "50ed2e9d4e115f57",
"timestamp": 1749810356666,
"parentId": "08c5f607f9535458",
"foreignParentId": null,
"name": "GET q1",
"duration": 88,
"minSelfTime": 88,
"networkTime": null,
"callCount": 1,
"errorCount": 0,
"destination": {
"service": {
"id": "cf206726b8ebb88a5337fd8209a8cc0b6b72bcef",
"label": " QM1@MQAppliance "
},
"endpoint": {
"id": "xCNTrRSberRTBxVlWcsuMzlrz10",
"label": "q1",
"type": "MESSAGING"
},
"technologies": [
"ibmMqQueueManager"
]
},
"cursor": {
"@class": ".IngestionOffsetCursor",
"ingestionTime": 1749810487000,
"offset": 2
}
}
],
"canLoadMore": false,
"totalHits": 2,
"totalRepresentedItemCount": 2,
"totalRetainedItemCount": 2
}
Also check out:
IBM MQ and IBM MQ Appliance firmware 9.4.3 Announcement blog: https://community.ibm.com/community/user/blogs/ian-harwood1/2025/06/13/mq943ga
IBM MQ Appliance OpenTelemetry tracing service documentation: https://www.ibm.com/docs/en/mq-appliance/9.4.x?topic=reporting-opentelemetry-integration
IBM MQ Appliance what’s new in 9.4.3: https://www.ibm.com/docs/en/mq-appliance/9.4.x?topic=appliance-whats-new-changed-in-release-943