Collecting an IBM MQ classes for Java trace dynamically by using the traceControl utility

The traceControl utility that is shipped with the IBM® MQ classes for Java allows trace to be collected from a running application. This can be very useful if IBM Support need to see a trace from an application once an issue has occurred, or if trace needs to be collected from a critical application that cannot be stopped.

Before you begin

Note: For Continuous Delivery, the trace control utility is removed from the product at IBM MQ 9.3.3. IBM MQ 9.3.2 is the last Continuous Delivery release that it is delivered with. If dynamic trace is needed to diagnose an issue, IBM Support can guide you through the steps to gather trace as required.

About this task

For more information about the traceControl utility, see Controlling trace in a running process by using IBM MQ classes for Java and IBM MQ classes for JMS.

To collect a trace by using the traceControl utility, complete the following steps.

Procedure

Bring up a command prompt, and navigate to the directory MQ_INSTALLATION_PATH\java\lib.
Run the command:
```
java -jar com.ibm.mq.traceControl.jar ...
```
This command brings up a list of all of the Java processes on the system.
Identify the process identifier for the IBM MQ classes for Java application that needs to be traced, and run the command:
```
java -jar com.ibm.mq.traceControl -i process identifier -enable
```
Trace is now turned on for the application.
When trace is enabled, the IBM MQ classes for Java start writing trace information to a trace file in the application's current working directory. The name of the trace file depends on the environment that the application is running in:
- For IBM MQ classes for Java for IBM MQ 9.0.0 Fix Pack 1 or earlier, trace is written to a file called mqjms_%PID%.trc.
- From IBM MQ 9.0.0 Fix Pack 2, if the application has loaded the IBM MQ classes for Java from the JAR file com.ibm.mq.jar, trace is written to a file called mqjava_%PID%.trc.
- From IBM MQ 9.0.0 Fix Pack 2, if the application has loaded the IBM MQ classes for Java from the relocatable JAR file com.ibm.mq.allclient.jar, trace is written to a file called mqjavaclient_%PID%.trc.
- From IBM MQ 9.1.5 and IBM MQ 9.1.0 Fix Pack 5, if the application has loaded the IBM MQ classes for Java from the JAR file com.ibm.mq.jar, trace is written to a file called mqjava_%PID%.cl%u.trc.
- From IBM MQ 9.1.5 and IBM MQ 9.1.0 Fix Pack 5, if the application has loaded the IBM MQ classes for Java from the relocatable JAR file com.ibm.mq.allclient.jar, trace is written to a file called mqjavaclient_%PID%.cl%u.trc.
- From IBM MQ 9.3.0, if the application has loaded the IBM MQ classes for Java from the relocatable JAR file com.ibm.mq.jakarta.client.jar (Jakarta Messaging 3.0) or com.ibm.mq.allclient.jar (JMS 2.0), trace is written to a file called mqjavaclient_%PID%.cl%u.trc.
where %PID% is the process identifier of the application that is being traced, and %u is a unique number to differentiate files between threads running trace under different Java classloaders.

To turn trace off, run the command:

java -jar com.ibm.mq.traceControl -i process identifier -disable