IBM Support

Generating IBM MQ traces

Technote (troubleshooting)


Problem(Abstract)

Follow these instructions to generate IBM MQ traces in order to investigate and solve problems.

Cause

IBM MQ provides the ability to generate trace files containing information about its internal processing. These traces can capture problems reported by the operating system or the network, report on application activity, and pinpoint the root cause of unexpected or unwanted behavior. This document provides instructions for generating IBM MQ traces in many different environments across all supported IBM MQ platforms in order to investigate and solve problems.



Resolving the problem


IBM MQ Queue Managers and Applications

These instructions explain how to trace the queue manager as well as native MQI client and server applications written in C, C++, COBOL, .NET, pTAL, RPG and Visual Basic.





IBM MQ Java Message Service (JMS) and Java Applications

These instructions explain how to trace applications using the MQ classes for Java Message Service (JMS), whether they are running in WebSphere Application Server, in another Java EE application server, or in Java SE environments. Tracing instructions are also provided for applications using the MQ classes for Java, sometimes called the base Java classes, which are intended for Java SE environments but may be used in Java EE environments subject to several important restrictions.





IBM MQ Components

These instructions explain how to trace IBM MQ components such as Managed File Transfer (formerly File Transfer Edition), the MQ Explorer on Linux and Windows systems, and MQ Telemetry.




IBM MQ Network Communications

These instructions provide instructions for advanced tracing of IBM MQ network communications. These techniques may be used in addition to, or in place of, standard MQ traces based on the advice of IBM support.




IBM MQ and Other Products

These instructions provide instructions for tracing other products with which IBM MQ interacts.













WebSphere MQ V6.0 Standalone JMS Trace


Follow the instructions below to start, stop and format JMS trace in V6 and V7 for standalone (Java SE) applications.

NOTE: This method is still available in V7, but it is deprecated. It is suggested to use the new JMS trace facilities introduced in V7. See next section.

  • Start trace:
    WebSphere MQ JMS applications normally invoke trace by using command line arguments to the 'java' command. For example:
    java -DMQJMS_TRACE_LEVEL=base -DMQJMS_TRACE_DIR=/tmp myApp

    Sometimes this is not possible and you may need to invoke trace from within the source code. This can be done as follows:

    com.ibm.mq.jms.services.ConfigEnvironment.start("base");

    ...

    com.ibm.mq.jms.services.ConfigEnvironment.stop();

    The value of MQJMS_TRACE_DIR may also be controlled programmatically:

      java.util.Properties pros = System.getProperties();
      props.put("MQJMS_TRACE_DIR", "/tmp");
      System.setProperties(props);
  • Format trace:

      Formatting is not required

The trace records are written to a file called mqjms.trc in the current directory if the MQJMS_TRACE_DIR property is not set. Although the directory can be changed, the file name is always mqjms.trc.For additional details, refer to the WebSphere MQ Using Java manual:






WebSphere MQ V7.x Standalone JMS Trace


Follow the instructions below to start, stop and format JMS trace using the new features introduced in V7.
These trace instructions are for standalone (Java SE) applications that are not running under an application server.

==> Method 1: Using runtime tracing properties

- When invoking the application using the "java" program, include the properties com.ibm.msg.client.commonservices.trace.status and com.ibm.msg.client.commonservices.trace.outputName such as:

java -Djava.library.path="%MQ_JAVA_LIB_PATH%" -Dcom.ibm.msg.client.commonservices.trace.status=ON -Dcom.ibm.msg.client.commonservices.trace.outputName="%MQ_JAVA_DATA_PATH%"\trace ApplicationName

- The trace file defaults to a file named:
mqjms_PID.trc
... in the directory specified with com.ibm.msg.client.commonservices.trace.outputName, where PID is the current process ID.
If a process ID is not available, a random number is generated and prefixed with the letter f.

An example of using the full path for the outputName:
UNIX: com.ibm.msg.client.commonservices.trace.outputName=/var/mqm/trace/mqjms_%PID%.trc

==> Method 2: Using JMS configuration file jms.config

If you want to use the JMS configuration file, you need to explicitly indicate it at runtime.
There is no default JMS configuration file.

- Locate the sample JMS configuration file: jms.config
Windows: C:\Program Files\IBM\WebSphere MQ\Java\bin.
UNIX platforms (except AIX): /opt/mqm/java/bin
AIX: /usr/mqm/java/bin.

- Copy this sample jms.config into a directory that is outside the MQ code directory structure and give it another name. For example:
UNIX: cp /opt/mqm/java/bin/jms.config /var/mqm/myjms.config
Note: ideally the original sample jms.config file should not be changed, to keep the philosophy that none of the files under the MQ code directory structure should be modified by the users.

- Modify the following property in your own copy of jms.config file to enable the tracing:
com.ibm.msg.client.commonservices.trace.status=ON

- Execute the JMS program using the property com.ibm.msg.client.config.location as follows:

java -Djava.library.path="%MQ_JAVA_LIB_PATH%" -Dcom.ibm.msg.client.config.location="file:/var/mqm/myjms.config" ApplicationName

- The trace file defaults to a file named:
mqjms_PID.trc
... in the current working directory where PID is the current process ID.
If a process ID is not available, a random number is generated and prefixed with the letter f.
Note: This assumes using the default value for the following property in the jms.config:
#com.ibm.msg.client.commonservices.trace.outputName=mqjms_%PID%.trc
If you want the trace file to be placed under /var/mqm/trace, then change the outputName property as follows:
com.ibm.msg.client.commonservices.trace.outputName=/var/mqm/trace/mqjms_%PID%.trc

- To turn tracing off, set the property to OFF:
com.ibm.msg.client.commonservices.trace.status=OFF

  • Format trace:

Formatting is not required
  • For more details of using the JMS configuration file for WebSphere MQ classes for JMS, see:






WebSphere MQ JCA Resource Adapter Trace


JCA Resource Adapter trace
For details on how to enable JCA Resource adapter trace, refer to the WebSphere MQ Using Java manual. The ra.xml file provided with the 6.0.2.1 resource adapter has these properties defined, so they just need editing to enable trace:

Note : MQ JMS/Java trace needs enabling as above, how this is done will depend on the application server in use. Two files will need collecting mqjms.trc from the JMS client, and the trace file created by the JCA RA.





WebSphere MQ JMS Trace for WebLogic Server V8.1


Follow the instructions listed below to enable JMS trace under WebLogic:

    • Ensure that the WebLogic Server that you want to enable trace is stopped
    • Edit the file <WLS_home>\startWebLogic.cmd on Windows systems, or <WLS_home>\startWebLogic.sh on UNIX platforms (where <WLS_home> is the directory that contains the server configuration) and add the following statements before the echo statements that output the current values for the system's CLASSPATH and PATH environment variables:
      • set JAVA_OPTIONS=%JAVA_OPTIONS% -DMQJMS_TRACE_DIR=<The directory where the mqjms.trc file will be written to>
      • set JAVA_OPTIONS=%JAVA_OPTIONS% -DMQJMS_LOG_DIR=<The directory used by WebSphere MQ to log information on serious problems>
      • set JAVA_OPTIONS=%JAVA_OPTIONS% -DMQJMS_TRACE_LEVEL=base
    • Save the updated file.
Now whenever the WebLogic Server is started, WebSphere MQ JMS trace information will be written to the file <MQJMS_TRACE_DIR>\mqjms.trc.

Cross reference information
Segment Product Component Platform Version Edition
Application Servers WebSphere Application Server General AIX, HP-UX, IBM i, Linux, Solaris, Windows, z/OS
Business Integration WebSphere Enterprise Service Bus General AIX, HP-UX, i5/OS, Linux, Solaris, Windows, z/OS
Business Integration WebSphere Message Broker Documentation AIX, HP-UX, Linux, Solaris, Windows, z/OS
Business Integration WebSphere MQ Workflow Documentation AIX, HP-UX, Linux, Solaris, Windows, z/OS
Business Integration IBM MQ Problem Determination AIX, HP-UX, IBM i, Linux, OpenVMS, Solaris, Windows, z/OS, z/VSE 9.0, 8.0, 7.5

Product Alias/Synonym

WebSphere MQ WMQ

Document information

More support for: WebSphere MQ
Problem Determination

Software version: 3.0, 5.3, 5.3.1, 6.0, 7.0, 7.0.1, 7.1, 7.5, 8.0, 9.0

Operating system(s): AIX, HP-UX, IBM i, Linux, OpenVMS, Solaris, Windows, z/OS, z/VSE

Software edition: All Editions

Reference #: 1174924

Modified date: 30 August 2017


Translate this page: