IBM Support

IBM MQ Tracing Support (IBM-MQ-TRACING-USER-EXITS)

Fix Readme


Abstract

The document describes how to install and enable IBM MQ tracing on your IBM MQ hosts, the tracing data can be sent to Instana or other observability platforms depending on the configurations.
Update Name/Fix ID: IBM-MQ-TRACING-USER-EXITS

Content

 
 

Download location

IBM MQ Tracing

This download link for the exit version applies to IBM MQ versions 9.0 and later.

Fix download for multiple platforms

The following is a list of components, platforms, and file names that apply to this readme file:
 

Product or component name

Platforms

Fix

IBM MQ Tracing User ExitsAIX pSeries
Linux x86_64
Linux ppc64le
Linux s390x
Windows x86_64

IBM-MQ-TRACING-USER-EXITS

 

Prerequisites and co-requisites

 

General description

This fix provides tracing capability for IBM MQ messages. You can download IBM MQ Tracing user exits implementation and configure your IBM MQ server to enable tracing for messages. The tracing data is sent to Instana or other observability platforms depending on your configuration.

 

Platforms and prerequisites 

 

Supported platforms for containerized IBM MQ deployments

Operating system

Version

Hardware

AIX

7.2 and 7.3

Power System - Big Endian

Red Hat Enterprise Linux

9, 8, and Server 7

IBM z Systems, POWER systems - Little Endian, and x86-64

 

Supported platforms for on-premises IBM MQ

Operating system

Version

Architecture

Linux®

 

x86_64, ppc64le, and s390x

Windows®

 

x86_64

AIX

7.2 and 7.3

 

 

Container and Operator support

IBM MQ Operator 2.2.0 and later supports native tracing. To get native support, use IBM MQ queue manager container image 9.3.1.0-r2 or later versions.

To enable IBM MQ Tracing for queue managers that are deployed by using IBM MQ Operator 2.2.0 or later versions on an IBM Cloud Pak for Integration cluster or a Red Hat OpenShift Container Platform cluster, see IBM MQ guide. IBM MQ Tracing is supported on Linux on x86_64, ppc64le, and s390x Kubernetes nodes.

 

Prerequisites

 
  • Install and configure IBM MQ server and queue manager instances before installing and configuring IBM MQ Tracing.
  • Install the supported OpenSSL version depending on your platform.
    • Linux and Windows: OpenSSL 3.2.3 or later
    • AIX: OpenSSL 3.0.16.1000 or later
 

Platform-specific prerequisites

  • Windows: Install Microsoft Visual C++ Redistributable 2019 or later. Download the latest package from the Microsoft website.
  • AIX:

    1. Install XL C/C++ Runtime for AIX 17.1.3.0 or later versions, including the following file sets libc++.rte, libc++abi.rte, and libunwind.rte.
      To verify that the file sets are installed, run:

      
lslpp -l | grep -e libc++.rte -e libc++abi.rte -e libunwind.rte

    2. Ensure that the following AIX system library versions are installed:

      1. pthreads 7.2.5.203 or later
      2. libc 7.2.5.206 or later      

      To verify the library versions, run:

      lslpp -l | grep -e bos.rte.libc -e bos.rte.libpthreads
 

Tracing requirements

Instana and other otel supported vendors are the supported tracing systems. If you choose to send tracing data to Instana, you must have Instana host agent installed. To install and run Instana Host Agent, see Installing and configuring host agents. The IBM MQ Tracing user exits report tracing data to the Instana host agent on the same host by default. You also can configure it to report data to a remote Instana host agent. See Configuring IBM MQ tracing for details.

The trace correlation information is automatically added to IBM MQ messages with MQRFH2 headers or message properties by default. If you want to append trace correlation information to all the traced messages, you need to change the value of MONITOR_LEVEL to debug in the configuration file of IBM MQ Tracing user exits.

 
 

Known issues

A known issue on the Windows platform prevents the use of the destination queue monitor levels (IBMMQ_DEST_MONITOR_LEVEL_*) and the global monitor level (MONITOR_LEVEL) together.

On the AIX platform, the OTLP gRPC protocol (activated when you set OTLP_EXPORTER_GRPC_ENDPOINT) is unavailable, so HTTP is used by default.

 
 

Installing

Before you enable tracing for on-premises IBM MQ, download and configure the IBM MQ Tracing user exit package.

Note: The IBM MQ user exit no longer includes a static link to OpenSSL. To maintain compatibility with OpenTelemetry, you must install a supported OpenSSL version on your system. For installation instructions:

To download the IBM MQ Tracing user exit package, complete the following steps:

  1. Download the IBM MQ Tracing user exit .tar.gz file from IBM MQ. 
  2. Extract the downloaded .tar.gz file to a temporary location. After extraction, find five user-exit packages, each for a different platform, in the directory.
  3. Transfer the platform-specific user exit package to your IBM MQ server.
  4. Extract the user exit package in the following directory:
    • Linux or AIX IBM MQ server: /var/mqm/exits64
    • Windows IBM MQ server: C:\ProgramData\IBM\MQ\exits64
  5. Place the following files into the exits64 directory:
    • IBM MQ user exit binary file (intercepts the IBM MQ API calls and initiates calls to the wrapped OpenTelemetry C++ client library to create spans)
      • Linux and AIX: mqtracingexit_r
      • Windows: mqtracingexit.dll
    • Wrapped OpenTelemetry C++ client binary file (provides functions to manage the lifecycle of spans and sends spans to the Instana host agent)
      • Linux and AIX: tracelibrary.so
      • Windows: tracelibrary.dll
    • mqtracingexit.conf configuration file: This file is the configuration file for all the queue manager instances on the MQ server. To create a configuration file that is specific to a queue manager, copy mqtracingexit.conf to mqtracingexit_<QMNAME>.conf.
  6. Ensure that the tracer can resolve the OpenTelemetry client shared libraries at runtime by completing the following steps:
    • Linux/AIX
      • Copy the libopentelemetry_*.so files in the /opt/instana/tracing/ibmmq/lib directory.

    • Windows

      • Copy the opentelemetry_*.dll files in the C:\ProgramData\IBM\MQ\exits64 directory.
      • Add the C:\ProgramData\IBM\MQ\exits64 directory to your PATH environment variable through the System Environment Variables dialog.
      • Restart your terminal.


      Note: These steps must be performed for the IBM MQ user (mqm on Linux and AIX and MQ_USER on Windows) and any other user that starts MQ services.

  7. Install a compatible OpenSSL version if needed. Ensure that the tracer can resolve the OpenSSL binaries for the required version. If you cannot update the system's primary OpenSSL installation, complete one of the following actions:
    • Linux or AIX: Install or link a secondary OpenSSL installation to the /opt/instana/tracing/ibmmq/lib directory.
    • Windows: Install or link a secondary OpenSSL installation to the C:\ProgramData\IBM\MQ\exits64 directory.
 
 

Configuring

This section describes how to configure your IBM MQ to enable tracing, including two parts - Enabling IBM MQ Tracing user exit and Configuring IBM MQ tracing.
 

Enabling IBM MQ Tracing user exit for on-premises IBM MQ

To enable a user exit for on-premises IBM MQ, edit the mqs.ini (for tracing all the queue manager instances on a host) or qm.ini (for tracing a specific queue manager) file.

The files are located in the following directories based on your IBM MQ server platform:

  • Linux and AIX
    • mqs.ini: /var/mqm
    • qm.ini: /var/mqm/qmgrs/<QMNAME>
  • Windows
    • mqs.ini: C:\ProgramData\IBM\MQ
    • qm.ini: C:\ProgramData\IBM\MQ\qmgrs\<QMNAME>

<QMNAME> is the name of the queue manager.

 

Enabling tracing for a specific queue manager

To enable tracing for a specific queue manager, complete the following steps:

  1. Back up the qm.ini file.
    • Linux and AIX: /var/mqm/qmgrs/<QMNAME>/qm.ini
    • Windows: C:\ProgramData\IBM\MQ\qmgrs\<QMNAME>\qm.ini

  2. Edit the qm.ini file and add the following configuration:

    • Linux and AIX:

      ApiExitLocal:
    Sequence=100
    Function=EntryPoint
    Module=/var/mqm/exits64/mqtracingexit
    Name=TracingApiExit
       

    • Windows:

      ApiExitLocal:
    Sequence=100
    Function=EntryPoint
    Module=C:\ProgramData\IBM\MQ\exits64\mqtracingexit
    Name=TracingApiExit
       

    Where:

    • Sequence: Identifies the sequence of this exit in relation to other exits. An exit with a lower sequence number is called before an exit with a higher sequence number.
    • Function: Identifies the name of the function entry point into the module that contain the user exits code.
    • Module: Contains the user exits code. If this field contains the full path name of the module, it is used as is. If this field contains only the module name, the module is located by using the ExitsDefaultPath attribute in the ExitPath in the qm.ini file.
    • Name: The descriptive name of the user exits.
  3. Save the changes.
  4. Restart the queue manager instance to apply the changes.

For more information about enabling a user exit for IBM MQ, see IBM MQ guide.

 

Enabling tracing for all queue manager instances

To enable tracing for all the queue manager instances on a host, complete the following steps:

  1. Back up the mqs.ini file.
    • Linux and AIX: /var/mqm/mqs.ini
    • Windows: C:\ProgramData\IBM\MQ\mqs.ini

  2. Edit the mqs.ini file and add the following configurations:

    • On Linux and AIX, add the following lines:

      ApiExitCommon:
  Sequence=100
  Function=EntryPoint
  Module=/var/mqm/exits64/mqtracingexit
  Name=TracingApiExit
       

    • On Windows, add the following lines:

      ApiExitCommon:
  Sequence=100
  Function=EntryPoint
  Module=C:\ProgramData\IBM\MQ\exits64\mqtracingexit
  Name=TracingApiExit
       
    Note: When queue manager starts, the attributes in this stanza are read, and then overridden by the user exit that is defined in the qm.ini file.
  3. Save the changes.
  4. Restart the queue manager instances to apply the changes.
 

Enabling IBM MQ Tracing on Red Hat OpenShift clusters

Install IBM MQ Operator 2.2.0 and later for native tracing. To get native support, use IBM MQ queue manager container image 9.3.1.0-r2 or later versions.

To enable IBM MQ Tracing for queue managers that are deployed by using IBM MQ Operator 2.2.0 or later versions on an IBM Cloud Pak for Integration cluster or a Red Hat OpenShift Container Platform cluster, see IBM MQ guide. IBM MQ Tracing is supported on Linux on x86_64, ppc64le, and s390x Kubernetes nodes.

Note: To enable IBM MQ Tracing by using IBM MQ Operator on a Red Hat OpenShift Container Platform cluster, you must use an IBM Cloud Pak for Integration license with the IBM MQ Operator.
 
 

Configuring IBM MQ tracing for on-premises IBM MQ

To configure tracing for on-premises IBM MQ, complete the following steps:

  1. Go to the exits64 directory:
    • Linux and AIX: /var/mqm/exits64
    • Windows: C:\ProgramData\IBM\MQ\exits64

  2. Edit the mqtracingexit.conf file for all the queue manager instances or the mqtracingexit_<QMNAME>.conf file for specific queue manager.

    # configuration for IBM MQ Tracing user exit
LOG_LEVEL="info" #Log level: info, warn, error, debug
SPAN_FORMAT="instana" #Span Format: instana, otel
MONITOR_LEVEL="normal" #MQ tracing level: normal, quiet, off, debug
IBMMQ_DEST_MONITOR_LEVEL_OFF = "" Regex for message destinations with tracing level off, for example: "^TMPQ.*". An example for multiple conditions: "^SYSTEM\\.AUTH\\..*|^TEMP\\.QUEUE\\..*".
IBMMQ_DEST_MONITOR_LEVEL_QUIET = "" #Regex for message destinations with tracing level quiet
IBMMQ_DEST_MONITOR_LEVEL_NORMAL = "" #Regex for message destinations with tracing level normal
IBMMQ_DEST_MONITOR_LEVEL_DEBUG = "" #Regex for message destinations with tracing level debug
IBMMQ_PUBSUB_SUPPORT = "off" #The switch for the publish/subscribe support: on, off
IBMMQ_RFH2_HEADERS_TO_EXPOSE = "" #A list of message headers that must be included in the `PUT` span payload, and each header is separated by commas.
INSTANA_AGENT_HOST = "localhost" #(optional) Applies only when the SPAN_FORMAT is set to instana
INSTANA_AGENT_PORT = 42699 #(optional) Applies only when the SPAN_FORMAT is set to instana
INSTANA_AGENT_PROTO = "http" #(optional) Applies only when the SPAN_FORMAT is set to instana
HOST_ALIAS="<YOUR-HOST-NAME>" #(optional) Applies only when the SPAN_FORMAT is set to instana
LOCAL_SOURCE_ADDRESS = "" #(optional) The local source ip address for outgoing traffic
OTLP_EXPORTER_GRPC_ENDPOINT = "" #(optional) Applies only when the SPAN_FORMAT is set to otel
OTLP_EXPORTER_SSL_CACERT_PATH = "" #(optional) Applies only when the SPAN_FORMAT is set to otel
OTLP_EXPORTER_HTTP_URL = "" #(optional) Applies only when the SPAN_FORMAT is set to otel
     

    For more information about the configuration parameters, see Configuration parameters.

  3. Save the file.
  4. Restart queue manager instances.
Note: Instana 246 and later versions support setting a custom service name for IBM MQ Tracing user exit. To set a custom service name, set the INSTANA_SERVICE_NAME environment variable for the IBM MQ processes.
 

Configuration parameters

The following table lists the configuration parameters:

Parameter

Description

LOG_TARGET

Specifies the target for log output. Supported values are system and file. The default value is file. The system option writes logs to the syslog on Linux and UNIX systems and to the event log on Windows systems.

LOG_LEVEL

Specifies the log level:info, warn, error, or debug. Log files are stored in /tmp/ibmmqtrace (Linux or AIX) or C:\ProgramData\IBM\MQ\trace (Windows). 

SPAN_FORMAT

Specifies the trace system to which the span data is sent. Set this variable toinstana. By default, data is sent to the host agent endpoint http://localhost:42699. To send the span data to a remote host agent by using the HTTPS protocol, update the configuration items INSTANA_AGENT_HOST and INSTANA_AGENT_PROTO. The SPAN_FORMAT setting must be the same for the IBM MQ hosts.

MONITOR_LEVEL

Specifies default tracing level for queue managers: off, quiet, normal, or debug. off: No tracing data is collected. quiet: The trace correlation information is not added to all the messages, but the messages can still be traced in the IBM MQ server. normal: The trace correlation information is added to the messages with RFH2 headers or named properties, but is not added to the text messages. debug: The trace correlation information is added to all messages that are being traced.

IBMMQ_DEST_MONITOR_LEVEL_OFF

Specifies message destinations with tracing level off. Value must be a regular expression, such as "^TMPQ.*". It means that the messages that are sent to the destinations that start withTMPQ are not traced. To ensure the integrity of the transaction, keep the same tracing level for message destinations in the same messaging chain. If a message destination matches multiple regular expressions, then the priority order of the effective regular expressions is as follows: OFF, QUIET, NORMAL, and DEBUG.

IBMMQ_DEST_MONITOR_LEVEL_QUIET

Specifies message destinations with the tracing levelquiet. The value must be a regular expression. If a message destination matches this regular expression, then the trace correlation information is not added to all the messages that are sent to the message destination. But you can still trace the messages in the IBM MQ server.

IBMMQ_DEST_MONITOR_LEVEL_NORMAL

Specifies message destinations with tracing levelnormal. The value must be a regular expression. If the message destination matches this regular expression, then the trace correlation information is added to the messages with RFH2 headers or named properties. But the trace correlation information is not added to the text messages.

IBMMQ_DEST_MONITOR_LEVEL_DEBUG

Specifies the message destinations with the tracing level debug. The value must be a regular expression. If the message destination matches this regular expression, then the trace correlation information is added to all the messages that are sent to the message destination. On Windows, the destination queue monitor levels (IBMMQ_DEST_MONITOR_LEVEL_*) and the global monitor level (MONITOR_LEVEL) cannot be used together due to a known issue.

IBMMQ_FF_SEND_METRICS

Set this flag to enable sending numeric attributes as metrics in Instana spans. Only the MQMDBackoutCount attribute is supported.

IBMMQ_PUBSUB_SUPPORT

Controls support for tracing publish and subscribe messages. Set it to on to enable and off to disable the support.

IBMMQ_RFH2_HEADERS_TO_EXPOSE

Specifies a list of message headers that must be included in the span payload, and each header is separated by a comma, for example, IBMMQ_RFH2_HEADERS_TO_EXPOSE="rfh2_folder1.header1, rfh2_folder2.header2, header3". Any message header with a size larger than 256 bytes is truncated to avoid creating a span size that is too large and affects the overall performance. Also, the total length of all the collected message headers in a span must not exceed 3 KB. Therefore, only the most important headers must be configured for the collection.

INSTANA_AGENT_HOST

Specifies the agent host where the Instana format span data is sent to, and localhost is used by default. If you specify a remote agent host, add a line http.listen=* in*instanaAgentDir*/etc/instana/com.instana.agent.main.config.Agent.cfg for the remote host agent first as the host agent is not reachable from other hosts by default.

INSTANA_AGENT_PORT

Specifies the port where the Instana agent is listening, and 42699 is used by default. You need to change the port only when the agent is listening on another port.

INSTANA_AGENT_PROTO

Specifies the connection type between the IBM MQ Tracing exit and the host agent. IBM MQ sensor supports both HTTP and HTTPS protocols. However, HTTP is used by default. To change the protocol to HTTPS, you must first secure the agent endpoint. For more information about how to secure the agent endpoint, see Setting up TLS encryption for agent endpoint.

HOST_ALIAS

Specifies a host alias for the span data that is collected by IBM MQ Tracing user exit. You can link calls to IBM MQ to the infrastructure entity if the IBM MQ sensor also monitors the queue manager. The FQDN of the MQ host is used by default. The host alias value needs to match with the IBM MQ host that is specified in the host agent configuration yaml. If the FQDN of IBM MQ host is not used in the IBM MQ sensor configuration and the host agent is not on the local IBM MQ host, specify a host alias. The IBM MQ sensor can discover the FQDN for the local queue manager instances.

LOCAL_SOURCE_ADDRESS

Specifies the local source IP address for outgoing traffic from IBM MQ Tracing user exit. You need to configure it only if your IBM MQ server has multiple network interfaces and you want to bind all outgoing traffic from IBM MQ Tracing user exit to a specific network interface.

OTLP_EXPORTER_GRPC_ENDPOINT

Specifies the OTLP gRPC endpoint to which OpenTelemetry span data is sent when SPAN_FORMAT is set to otel. The default is localhost:4317. If TLS is enabled on the gRPC endpoint, also configure OTLP_EXPORTER_SSL_CACERT_PATH. On the AIX platform, the OTLP gRPC protocol (activated when you set OTLP_EXPORTER_GRPC_ENDPOINT) is unavailable, so HTTP is used by default.

 

Configuring tracing on a Red Hat OpenShift cluster

 

To change the configuration of IBM MQ Tracing for a queue manager running on a Red Hat OpenShift cluster, add new environment variables to the queue manager pod.

The environment variable name must match the configuration item name that is listed in the Configuring IBM MQ Tracing for on-premises IBM MQ section. To add an environment variable for a queue manager pod, complete the following steps:

  1. Log in to your Red Hat OpenShift cluster web console.
  2. From the navigation menu, click Operators > Installed Operators. All installed Operators in the specified project are displayed.
  3. Select IBM MQ Operator. The IBM MQ Operator window is displayed.
  4. Go to the queue manager tab. The queue manager Details window is displayed.
  5. Select the queue manager for which you want to change the tracing configuration.
  6. Go to the YAML tab.

  7. Add the environment variable in the spec > template > pod > containers > env section. For example, use the following snippet to change the log level of IBM MQ Tracing to debug:

    template:
 pod:
   containers:
     - env:
         - name: LOG_LEVEL
           value: debug
     
  8. Save the updated queue manager YAML file.
 
 

Trace correlation

Tracing data that is collected by IBM MQ Tracing user exit and other tracers can be correlated if trace context headers (trace correlation information) are set in IBM MQ messages.

IBM MQ Tracing supports the following trace context headers:

  • Instana trace context headers (X_INSTANA_T, X_INSTANA_S, and X_INSTANA_L)
  • W3C trace context headers (traceparent and tracestate)

When IBM MQ Tracing user exit requires propagating trace correlation information, it propagates Instana tracing headers and W3C trace context headers in IBM MQ messages.

 

Upgrade

 

Upgrading IBM MQ Tracing in on-premises environments

When a new version of IBM MQ Tracing user exit is released, you can upgrade it as follows:

On Linux or AIX:

To upgrade IBM MQ Tracing on Linux or AIX, complete the following steps:

  1. If the Instana agent is running on the IBM MQ server, stop the queue manager instances and the Instana agent.
  2. Back up the configuration files for the IBM MQ Tracing user exit in the /var/mqm/exits64 directory on the IBM MQ server.
  3. Extract the downloaded IBM MQ Tracing user exit files and replace the corresponding files in the /var/mqm/exits64 directory.
  4. In the /opt/instana/tracing/ibmmq/lib directory, replace the libopentelemetry dependencies with the updated libopentelemetry dependencies.
  5. If the Instana agent was stopped in step 1, restart the queue manager instances and the Instana agent.

On Windows:

To upgrade IBM MQ Tracing on Windows, complete the following steps:

  1. If the Instana agent is running on the IBM MQ server, stop the queue manager instances, IBM MQ Explorer, and the Instana agent.
  2. Back up the configuration files for the IBM MQ Tracing user exit in the C:\ProgramData\IBM\MQ\exits64 directory on the IBM MQ server.
  3. Extract the downloaded IBM MQ Tracing user exit file, and replace the corresponding files in the C:\ProgramData\IBM\MQ\exits64 directory.
  4. If the Instana agent was stopped in step 1, restart the queue manager instances, IBM MQ Explorer, and the Instana agent.
 

Upgrading IBM MQ Tracing on Red Hat OpenShift clusters

To upgrade IBM MQ Tracing on a Red Hat OpenShift cluster, complete one of the following steps:

  • If IBM MQ Tracing is enabled by using IBM MQ Operator 2.2.0 or later versions, upgrade IBM MQ queue manager.
  • If IBM MQ Tracing is enabled by using Instana AutoTrace webhook, deploy the Instana AutoTrace webhook again, and restart queue manager pods.
 
 

Unconfiguring

To disable the collection of tracing data in IBM MQ, set MONITOR_LEVEL to off in the mqtracingexit.con file.

To disable IBM MQ Tracing user exit, complete the following steps on IBM MQ hosts:

  1. Remove the ApiExitCommon and ApiExitLocal stanzas that you configured in the /var/mqm/mqs.ini or C:\ProgramData\IBM\MQ\mqs.ini file.
  2. Remove the /var/mqm/qmgrs/<QMNAME>/qm.ini or C:\ProgramData\IBM\MQ\qmgrs\<QMNAME>\qm.ini file from the IBM MQ hosts where IBM MQ Tracing is enabled.
  3. Restart the queue manager instances, IBM MQ Explorer, and the Instana agent if the Instana agent is running on the IBM MQ server.

To disable IBM MQ Tracing on a Red Hat OpenShift cluster, set the Enable Instana tracing toggle to false in IBM Cloud Pak for Integration Platform UI or the Red Hat OpenShift web console. See the IBM MQ guide.

 
 

Troubleshooting

You might encounter the following issues with IBM MQ Tracing:

 

IBM MQ queue manager fails to start

To troubleshoot, complete the following steps:

  1. Ensure that tracelibrary.so (on Linux/AIX) or tracelibrary.dll (on Windows) can resolve all dependencies for all users that start IBM MQ services, including the mqm user on Linux or AIX and the MQ_USER on Windows. To verify, use the following commands:
    • Linux: ldd
    • AIX: dump -H or ldd
    • Windows: dump bin /dependents
  2. Confirm that all required files are present in the expected locations:
    • Linux: .so
    • AIX: .a or .so
    • Windows: .dll
  3. Verify that the system has the required OpenSSL version installed and that tracelibrary.so or tracelibrary.dll can resolve it at runtime.
 

Message processing error

To propagate trace correlation information, IBM MQ Tracing user exit adds additional MQRFH2 headers (X_INSTANA_T , X_INSTANA_S, X_INSTANA_L, traceparent, and tracestate) to the messages that are being traced when the messages already contain MQRFH2 headers or when the monitor level of the message destination is set to debug. But the presence of additional header data in messages can cause message processing errors and message rejection in some IBM MQ consumer applications. If the additional MQRFH2 headers cause errors in an IBM MQ client application, do one of the following actions:

  • Modify the IBM MQ client application to ignore the additional MQRFH2 headers with trace correlation information that Instana added.
  • Disable trace correlation propagation by adding the queues in the messaging chain to the IBM MQ Tracing user exit configuration parameter IBMMQ_DEST_MONITOR_LEVEL_QUIET.
  • Change the value of PROPCTL property to NONE for the queue connected by the IBM MQ client application.
 

Trace correlation missing in IBM MQ messages

By default, the trace correlation information is automatically added to the IBM MQ messages that contain MQRFH2 headers or message properties. To avoid breaking your IBM MQ client applications, IBM MQ Tracing user exit doesn't add trace correlation information to plain text messages. If you still want to append the trace correlation information to the messages, you can add the message destinations to the IBM MQ Tracing user exit configuration parameter IBMMQ_DEST_MONITOR_LEVEL_DEBUG. However, you need to ensure that your IBM MQ client application can parse messages with additional MQRFH2 headers.

 

Infrastructure link is not displayed in call details

You can link a call that is generated by the IBM MQ Tracing user exit to a monitored infrastructure entity of the IBM MQ queue manager, which is collected by the Instana IBM MQ sensor in the Instana UI. The infrastructure link might not be available in IBM MQ high-availability scenarios because the entity ID of a queue manager that is collected by the Instana IBM MQ sensor contains the host of both active and standby IBM MQ nodes. This contrasts with the entity ID generated by the IBM MQ Tracing user exit, which only includes the host of the active IBM MQ node. The mismatch disrupts the link between call details and the queue entity. To resolve this issue, you can take the following actions:

  1. Go to the high-availability queue manager dashboard within the Infrastructure view in the Instana UI.
  2. Locate the Name attribute in the sidebar of the queue manager dashboard to extract the queue manager host information. The host for the high-availability queue manager is the part of the Name string that comes after the @ symbol. For example, if the queue manager name appears as haqm1@ibmmqnode1.ibm.com-ibmmqnode2.ibm.com-ibmmqnode3.ibm.com, then the queue manager host is ibmmqnode1.ibm.com-ibmmqnode2.ibm.com-ibmmqnode3.ibm.com.
  3. Access the IBM MQ server, and open the mqtracingexit.conf configuration file for IBM MQ Tracing user exit.
  4. Set the HOST_ALIAS field to the queue manager hostname that is obtained in step 2.
  5. Save the configuration file.
  6. Restart the high-availability queue manager to apply the changes.
 
 

Document change history

VersionDateDescription of change
19.017 June 2026Updated IBM MQ Tracing user exits version to 3.8.0.
Added support for exporting the MQMDBackoutCount attribute as a metric.
Added support for sending tracer logs to OS logging services:
  - Syslog on Linux and Unix systems
  - Windows Event Log on Windows systems
Reduced verbosity of debug-level logging.
Improved dependency handling on Linux and Unix systems by automatically discovering dependencies in /opt/instana/tracing/ibmmq/lib.
Updated AIX system requirements:
  - pthreads 7.2.5.203 or later
  - libc 7.2.5.206 or later
  - OpenSSL 3.0.16.1000 or later
Removed writes to stdout and stderr during startup.
The tracer is no longer statically linked against OpenSSL on Windows and Linux.
OpenSSL 3.2.3 is now required on both platforms.
18.02 June 2023Updated IBM MQ Tracing user exits version to 2023.2.1.
Fixed an unexpected MQ API exit error on AIX.
17.08 May 2023Updated IBM MQ Tracing user exits version to 2023.2.0.
Changed the length of the MQ message header X_INSTANA_T that contains the Instana trace ID to 16 characters in length.
16.027 Mar 2023Updated IBM MQ Tracing user exits version to 2023.1.1.
Added support for displaying message headers on Instana UI.
Added support for environment variable INSTANA_SERVICE_NAME.
Changed the default value of configuration item IBMMQ_PUBSUB_SUPPORT to off.
15.027 Feb 2023Updated IBM MQ Tracing user exits version to 2023.1.0.
Added support for tracing publish/subscribe messages.
Added a new monitor level 'quiet' to prevent trace context propagation.
Fixed the service name extraction issue in Instana when the MQ server name contains the character "-".
14.02 Dec 2022Updated IBM MQ Tracing user exits version to 2022.4.3.
Added support for Windows 64.
Fixed the correlation issue with the ACE OpenTelemetry trace.
13.022 Nov 2022Updated IBM MQ Tracing user exits version to 2022.4.2.
Fixed the log file permission issue in the environment where both MQ and ACE are installed.
Moved the log files of IBM MQ tracing user exit to the directory /tmp/ibmmqtrace.
Removed the unexpected message headers from the messages to ACE system queues.
Fixed the issue of the unexpected API exit error (reason code 2374) in MQ error logs.
12.010 Nov 2022Updated IBM MQ Tracing user exits version to 2022.4.1, upgraded the OpenSSL version to 1.1.1s in trace library.
11.01 Nov 2022Updated IBM MQ Tracing user exits version to 2022.4.0, added support for W3C trace context when the span format is instana.
10.030 Sep 2022Updated IBM MQ Tracing user exits version to 2022.3.4, added support for non-default Instana agent port.
9.022 Sep 2022Updated IBM MQ Tracing user exits version to 2022.3.1, added support for AIX 7.3.
8.027 July 2022Updated IBM MQ Tracing user exits version to 2022.3.0, added support for Linux ppc64le.
7.022 June 2022Updated IBM MQ Tracing user exits version to 2022.2.2, added support for monitoring level debug.
6.03 June 2022Updated IBM MQ Tracing user exits version to 2022.2.1, added support for container IBM MQ in CP4I.
5.012 May 2022Updated IBM MQ Tracing user exits version to 2022.2.0, added support for Linux s390x.
4.08 Apr 2022Updated IBM MQ Tracing user exits version to 2022.1.1, added support for AIX 7.2.
3.017 Mar 2022Updated IBM MQ Tracing user exits version to 2022.1.0.
2.018 Nov 2021Updated IBM MQ Tracing user exits version to 2021.4.0.
1.027 Aug 2021Initial Version.

[{"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SSVJUL","label":"IBM Application Performance Management"},"Component":"","Platform":[{"code":"PF016","label":"Linux"}],"Version":"8.1.4","Edition":"","Line of Business":{"code":"LOB77","label":"Automation Platform"}}]

Document Information

Modified date:
17 June 2026

UID

ibm16484595

Page Feedback