IBM MQ Tracing Technical Preview 2021.2.0 (2021.2.0-IBM-MQ-TRACING-USER-EXITS)

Fix Download for Linux

• mqtracingexit_r, the IBM MQ user exits, intercepting the IBM MQ API calls and invoking the wrapped go jaeger client library to create spans.
• tracelibrary.so, the wrapped go jaeger client, provides functions to manage the lifecycle of spans and sends spans to the target tracing system.
• mqtracingexit.conf, the configuration file to specify the target tracing system (Jaeger or Instana) and the parameters for span generation.

You need to edit mqs.ini or qm.ini file to configure user exits. The mqs.ini file contains information relevant to all the queue managers on a particular node, the mqs.ini file is located at /var/mqm on Linux platform. The qm.ini file contains information relevant to a specific queue manager. The qm.ini file is located at /var/mqm/qmgrs/<QMNAME> on Linux platform.

Follow steps to enable tracing for all the queue managers on a particular node

Add the following content to enable user exits for all queue managers on this node. When any queue manager starts, the attributes in this stanza are read, and then overridden by the user exits defined in qm.ini.

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

Follow steps to enable tracing for a particular queue manager or you want to change user exits settings for a particular queue manager.

Add the following content:

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

Where:

• Sequence identifies the sequence of this exit in relation to other exits. An exit with a low sequence number is called before an exit with a higher sequence number.
• Function identifies the name of the function entry point into the module containing 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 using the ExitsDefaultPath attribute in the ExitPath in qm.ini.
• Name is the descriptive name of the user exits.

See more information at Configuring API exits in IBM MQ document library.

You need to save changes to the configuration files and restart queue managers to make changes taking effect.

Configuring IBM MQ tracing

2. Edit mqtracingexit.conf file.

# configuration for MQ exit
LOG_LEVEL="info" #Log level: info, warn, error, debug
SPAN_FORMAT="jaeger" #specify opentracing span format as instana or jaeger
JAEGER_ENDPOINT = "http://<jaeger_collector_host>:14268/api/traces"
JAEGER_SAMPLER_TYPE = "const"
JAEGER_SAMPLER_PARAM = 1.0

Where:

• LOG_LEVEL specifies the log level, which can be one of info, warn, error and debug, the log file is located at /var/mqm/trace directory on Linux platform.
• SPAN_FORMAT specifies where the span data is sent to. The SPAN format can be set to instana or jaeger. If SPAN_FORMAT is set to instana, span data is sent to Instana (This requires Instana Host Agent running on the same node), ApiExit code auto-connects to localhost:42699, in such a case you can ignore JAEGER_* parameters in mqtracingexit.conf file. If SPAN_FORMAT is set to jaeger, you need to configure JAEGER_* parameters. You should have the  same SPAN_FORMAT setting for all IBM MQ nodes.
• JAEGER_ENDPOINT specifies jaeger collector endpoint.
• JAEGER_SAMPLER_TYPE specifies the sample type. The value can be one of const, probabilistic, ratelimiting and remote.
• JAEGER_SAMPLER_PARAM is interpreted based on the value of JAEGER_SAMPLER_TYPE. See more details at https://www.jaegertracing.io/docs/1.22/sampling/#client-sampling-configuration.