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

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


To collect a trace by using the IBM MQ classes for JMS configuration file, complete the following steps.


Procedure

  1. Create an IBM MQ classes for JMS configuration file. For more information about this file, see The IBM MQ classes for JMS configuration file.
  2. Edit the IBM MQ classes for JMS 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 JMS configuration file Java Standard Edition Trace Settings.
  4. Run the IBM MQ classes for JMS 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 JMS 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/myjms.config 
MyAppClass
    This command identifies the IBM MQ classes for JMS configuration file as the file D:\mydir\myjms.config on the local Windows system. By default, the IBM MQ classes for JMS start writing trace information to a trace file in the application's current working directory when the application starts up. The name of the trace file depends on the environment that the application is running in:

    • For IBM MQ classes for JMS for Version 9.0.0, Fix Pack 1 or earlier, trace is written to a file called mqjms_%PID%.trc.
    • From Version 9.0.0, Fix Pack 2, if the application has loaded the IBM MQ classes for JMS from the JAR file com.ibm.mqjms.jar, trace is written to a file called mqjava_%PID%.trc.
    • From Version 9.0.0, Fix Pack 2, if the application has loaded the IBM MQ classes for JMS from the relocatable JAR file com.ibm.mq.allclient.jar, trace is written to a file called mqjavaclient_%PID%.trc.
    • From Version 9.1.5 and Version 9.1.0, Fix Pack 5, if the application has loaded the IBM MQ classes for JMS from the JAR file com.ibm.mqjms.jar, trace is written to a file called mqjava_%PID%.cl%u.trc.
    • From Version 9.1.5 and Version 9.1.0, Fix Pack 5, if the application has loaded the IBM MQ classes for JMS 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 JMS 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 JMS to write trace information for an application to a file called C:\Trace\trace.trc, the IBM MQ classes for JMS configuration file that the application uses needs to contain the following entry:

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

Parent topic: Tracing IBM MQ classes for JMS applications