Collecting an IBM MQ classes for Java trace by using the IBM MQ classes for Java configuration file

If an application must run for a long period of time before an issue occurs, IBM® MQ classes for Java trace should be collected by using the IBM MQ classes for Java configuration file. The configuration file allows you to specify various options to control the amount of trace data that is collected.

1. Create an IBM MQ classes for Java configuration file.
   For more information about this file, see The IBM MQ classes for Java configuration file.
2. Edit the IBM MQ classes for Java configuration file so that the property com.ibm.msg.client.commonservices.trace.status is set to the value ON.
3. Optional: Edit the other properties that are listed in the IBM MQ classes for Java configuration file Java Standard Edition Trace Settings.
4. Run the IBM MQ classes for Java application by using the following command:

   java -Dcom.ibm.msg.client.config.location=config_file_url
   application_name

   where config_file_url is a uniform resource locator (URL) that specifies the name and location of the IBM MQ classes for Java configuration file. URLs of the following types are supported: http, file, ftp, and jar.

   Here is an example of a Java command:

   java -Dcom.ibm.msg.client.config.location=file:/D:/mydir/myJava.config 
   MyAppClass

   This command identifies the IBM MQ classes for Java configuration file as the file D:\mydir\myJava.config on the local Windows system.
   By default, trace information is written to a trace file in the current working directory of the application. The name of the trace file depends upon the environment that the application is running in:

   • For IBM MQ classes for Java for Version 8.0.0, Fix Pack 6 or earlier, trace is written to a file called mqjms_%PID%.trc.
   • From Version 8.0.0, Fix Pack 7, 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 Version 8.0.0, Fix Pack 7, 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 Version 8.0.0, Fix Pack 15, 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 Version 8.0.0, Fix Pack 15, 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.

   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 change the name of the trace file, and the location where it is written, ensure that the IBM MQ classes for Java configuration file that the application uses contains an entry for the property com.ibm.msg.client.commonservices.trace.outputName. The value for the property can be either of the following:

   • The name of the trace file that is created in the application's working directory.
   • The fully qualified name of the trace file, including the directory in which the file is created.

   For example, to configure the IBM MQ classes for Java to write trace information for an application to a file called C:\Trace\trace.trc, the IBM MQ classes for Java configuration file that the application uses needs to contain the following entry:

   com.ibm.msg.client.commonservices.trace.outputName=C:\Trace\trace.trc