Tracing the telemetry (MQXR) service

The trace facility provided by the IBM MQ telemetry (MQXR) service is provided to help IBM Support diagnose customer issues related to the service.

There are two ways to control trace for the IBM MQ telemetry service:

By using the strmqtrc and endmqtrc commands to start and stop trace. Enabling trace, using the strmqtrc command, generates trace information for the entire queue manager where the IBM MQ telemetry service is running. This includes the IBM MQ telemetry service itself, and the underlying Java Message Queuing Interface (JMQI) that the service uses to communicate with other queue manager components.
From IBM MQ Version 9.1.5, we can also generate trace information for selected areas of interest.
By running the controlMQXRChannel command. Note, that turning trace on using the controlMQXRChannel command traces only the IBM MQ telemetry service.

If we are unsure which option to use, contact the IBM Support representative and they will be able to advise you on the best way to collect trace for the issue that we are seeing.

Procedure

Method one
1. Bring up a command prompt and navigate to the directory: MQ_INSTALLATION_PATH\bin
2. Run the strmqtrc command to enable trace: For Long Term Support and Continuous Delivery before IBM MQ Version 9.1.5, run the following command:
```
strmqtrc -m qmgr_name
```
  where qmgr_name is the name of the queue manager where the IBM MQ MQXR service is running. From IBM MQ Version 9.1.5, run the following command:
```
strmqtrc -m qmgr_name -t mqxr
```
  where qmgr_name is the name of the queue manager where the IBM MQ MQXR service is running, and -t mqxr restricts trace output to the MQXR service only.
3. Reproduce the issue.
4. Stop trace, by running the command:
```
endmqtrc -m qmgr_name
```
Method two.
1. Bring up a command prompt and navigate to the directory: MQ_INSTALLATION_PATH\mqxr\bin
2. Run the following command to enable trace:
  - ```
  controlMQXRChannel -qmgr=qmgr_name -mode=starttrace [clientid=ClientIdentifier]
```
- ```
./controlMQXRChannel.sh -qmgr=qmgr_name -mode=starttrace [clientid=ClientIdentifier]
```
  where qmgr_name is the name of the queue manager where the MQXR Service is running. Set ClientIdentifier to the client identifier of an MQTT client. If you specify the clientid parameter, the IBM MQ telemetry service trace captures activity for only the MQTT client with that client identifier.
  To trace the IBM MQ telemetry service activity for more than one specific MQTT client, we can run the command multiple times, specifying a different client identifier each time.
3. Reproduce the issue.
4. When the issue occurs, stop trace by running the following command:
  - ```
  controlMQXRChannel -qmgr=qmgr_name -mode=stoptrace
```
- ```
./controlMQXRChannel.sh -qmgr=qmgr_name -mode=stoptrace [clientid=ClientIdentifier]
```
  where qmgr_name is the name of the queue manager where the MQXR Service is running.

Results

To view the trace output, go to the following directory:

MQ_DATA_PATH\trace.
/var/mqm/trace.

The trace files containing the information from the MQXR service are called mqxr_N.trc, where N is a number.

From IBM MQ Version 9.1.5, the trace files are named as follows:

The trace files containing the information from the MQXR service are called mqxrRunMQXRService_PPPPP.N.trc, where PPPPP is the process identifier for the MQXR service and N is a number.
The trace files containing the information from the controlMQXRChannel command are called mqxrControlMQXRChannel_PPPPP.N.trc, where PPPPP is the process identifier for the MQXR service and N is a number.

Trace information generated by the JMQI is written to a trace file called mqxr_PPPPP.trc, where PPPPP is the process identifier for the MQXR Service.

Parent topic: MQ Telemetry troubleshooting

Related information

strmqtrc