Collecting an IBM MQ classes for Java trace dynamically

The IBM® MQ classes for Java trace mechanism can be configured to turn trace on dynamically when it finds a specific file on the file system and stop tracing when that file no longer exists. 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.

1. Start the application that needs to be traced using the following command:

   java -Dcom.ibm.msg.client.commonservices.trace.OnOffFile=filename application_name

   where filename is the fully qualified path to the file that the IBM MQ classes for Java will look for to determine if trace needs to be enabled or disabled.

   For example, to configure the IBM MQ classes for Java to start tracing an application called JMSConsumer when a file called C:\Trace\enableTrace.txt is detected, start the application with the following command:

   java -Dcom.ibm.msg.client.commonservices.trace.OnOffFile=C:\Trace\enableTrace.txt MQJavaPutter

   Note: By default, if

   -Dcom.ibm.msg.client.commonservices.trace.OnOffFile=filename

   is not specified, the library looks for a file named enableMQJavaTrace under the application's root folder.
2. When trace needs to be enabled, do this in one of the following ways:
   • Create the file specified by filename in step 1.
   • If -Dcom.ibm.msg.client.commonservices.trace.OnOffFile is not set, create a file named enableMQJavaTrace in the application's root folder.

   The IBM MQ classes for Java writes the following message to the standard output stream to show that trace has been turned on:

   The IBM MQ messaging client trace mechanism is tracing to 'trace-filename'

   where trace-filename is the fully qualified path for the trace file.

3. After you reproduce the issue, turn trace off by removing or renaming the control file in one of the following ways:
   • Delete or rename the file specified by filename in step 1.
   • If -Dcom.ibm.msg.client.commonservices.trace.OnOffFile is not set, delete or rename enableMQJavaTrace in the application's root folder.

   The IBM MQ classes for Java detect that the file is no longer available, turn off trace and write the following message to the standard output stream:

   The IBM MQ messaging client trace mechanism has stopped tracing to 'trace-filename'.