Generating WebSphere MQ traces

Technote (troubleshooting)


Problem(Abstract)

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

Cause

WebSphere 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 WebSphere MQ traces in many different environments across all supported WebSphere MQ platforms in order to investigate and solve problems.


Resolving the problem



WebSphere 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, RPG and assembler.





WebSphere MQ Java Message Service (JMS) and Java Applications

These instructions explain how to trace applications using the WebSphere 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 WebSphere 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.





WebSphere MQ Components and Telemetry

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




WebSphere MQ Network Communications

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




WebSphere MQ and Other Products

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













WebSphere MQ V7.0 and V6.0 for Windows Explorer Trace


Follow the instructions listed below to run trace for the WebSphere MQ for Windows V6 and V7 Explorer using the MQ Java API:


1. Modify the files runmqcfg.cmd and runmqcfg_rcp.cmd in the directory:

C:\Program Files\IBM\WebSphere MQ\bin

Add the following line, which specifies the properties file in C:\TEMP\internal.properties.

set AMQ_EXPLORER=%AMQ_EXPLORER% "-Dcom.ibm.mq.commonservices=C:\TEMP\internal.properties"

Note: The command must be typed on ONE LINE in the runmqcfg.cmd and runmqcfg_rcp.cmd files and BEFORE the statement:

start "WebSphere MQ Explorer" %AMQ_EXPLORER%

2. Create a file internal.properties in the C:\TEMP directory as with the following text:

Diagnostics.MQ=enabled
Diagnostics.Java=explorer,wmqjavaclasses,all
#Diagnostics.Java=explorer
Diagnostics.Java.Trace.Detail=high
Diagnostics.Java.Trace.Destination.File=enabled
Diagnostics.Java.Trace.Destination.Console=disabled
Diagnostics.Java.Trace.Destination.Pathname=C:\\temp\\trace
Diagnostics.Java.FFDC.Destination.Pathname=C:\\temp\\FFDC
Diagnostics.Java.Errors.Destination.Filename=C:\\temp\\errors\\AMQJERR.LOG

3. You may also need to create the following directories:

C:\temp\FFDC
C:\temp\trace
C:\temp\errors

4. In the C:\temp\trace directory you will find files with the format AMQyyyymmddhhmmsssss.*.TRC
which contain the MQ Java trace output.




WebSphere MQ V7.0 and V6.0 for Linux Explorer Trace


Follow the instructions listed below to run trace for the WebSphere MQ for Linux V6 and V7 Explorer using the MQ Java API:

1. Modify the files runmqcfg.cmd and runmqcfg_rcp.cmd in the directory:

/opt/mqm/bin

Modify the line:
AMQ_EXPLORER="./eclipse"
to the following, according to the version of MQ:
v6.0:
AMQ_EXPLORER="/opt/mqm/ies30/eclipse/eclipse"
v7.0:
AMQ_EXPLORER="/opt/mqm/eclipseSDK33/eclipse/eclipse"

And add the single line:
AMQ_EXPLORER="$AMQ_EXPLORER -Dcom.ibm.mq.commonservices=/tmp/internal.properties"
before the statement
cd $AMQECLIPSE

2. Both of these scripts are dependent on the environment variable AMQECLIPSE. If this environment variable does not exist then it should be created as the first line in the script. For example:

v6.0:
export AMQECLIPSE="/opt/mqm/ies30/eclipse"
v7.0:
export AMQECLIPSE="/opt/mqm/eclipseSDK33/eclipse"

Note: If you want, you can include the above line in the user's profile.

3. Create a file called "internal.properties" in the /tmp directory with the following text.

Diagnostics.MQ=enabled
Diagnostics.Java=explorer,wmqjavaclasses,all
#Diagnostics.Java=explorer
Diagnostics.Java.Trace.Detail=high
Diagnostics.Java.Trace.Destination.File=enabled
Diagnostics.Java.Trace.Destination.Console=disabled
Diagnostics.Java.Trace.Destination.Pathname=/tmp/trace
Diagnostics.Java.FFDC.Destination.Pathname=/tmp/FFDC
Diagnostics.Java.Errors.Destination.Filename=/tmp/errors/AMQJERR.LOG

4. Ensure that the file permissions for the above file allow it to be read by all processes:

chmod a+r /tmp/internal.properties

5. You may also need to create the following directories:
/tmp/FFDC
/tmp/trace
/tmp/errors

6. Ensure that the file permissions for these directories allow other users to write, such as:

chmod 777 /tmp/FFDC
chmod 777 /tmp/trace
chmod 777 /tmp/errors

7. From a command prompt, invoke the script:

runmqcfg

8. In the /tmp/trace directory you will find files with the format AMQyyyymmddhhmmsssss.*.TRC
which contain the MQ Java trace output.




WebSphere MQ V7.5 and V7.1 for Windows Explorer Trace


To trace WebSphere MQ Explorer, close and restart the WebSphere MQ Explorer using the runwithtrace.cmd.
The runwithtrace.cmd is located in

    [WebSphereMQ_Install_Path]\MQExplorer\Eclipse

where [WebSphereMQ_Install_Path is the WebSphere MQ installation path.

When you start the WebSphere MQ Explorer using the runwithtrace.cmd, additional parameters are incorporated that enable tracing of the WebSphere MQ Explorer. Note that the runwithtrace.cmd takes no parameters itself.

The output location of the trace file is printed to the command line when the command runs, because the actual location:
  • Is dependent upon the status of the WebSphere MQ installation
  • User permissions




WebSphere MQ V7.5 and V7.1 for Linux Explorer Trace


To trace WebSphere MQ Explorer, close and restart the WebSphere MQ Explorer using the runwithtrace.cmd.
The runwithtrace.cmd is located in

    /opt/mqm/mqexplorer/eclipse

where opt/mqm is the WebSphere MQ installation directory.

When you start the WebSphere MQ Explorer using the runwithtrace.cmd, additional parameters are incorporated that enable tracing of the WebSphere MQ Explorer. Note that the runwithtrace.cmd takes no parameters itself.

The output location of the trace file is printed to the command line when the command runs, because the actual location:
  • Is dependent upon the status of the WebSphere MQ installation
  • User permissions




WebSphere MQ Standalone Base Java Class Trace


Follow the instructions listed below to start, stop and format trace for the WebSphere MQ base Java classes for standalone (Java SE) applications:

MQ V7:
The method shown for MQ V6 has been deprecated in MQ V7.

Distributed Platforms:

Create an MQ Java properties file.
#
# Base WebSphere MQ diagnostics are disabled
#
Diagnostics.MQ=enabled
#
# Java diagnostics for WebSphere MQ Transport for SOAP
# and the WebSphere MQ Java Classes are both enabled
#
Diagnostics.Java=soap,wmqjavaclasses
#
# High detail Java trace
#
Diagnostics.Java.Trace.Detail=high
#
# Java trace is written to a file and not to the console.
#
Diagnostics.Java.Trace.Destination.File=enabled
Diagnostics.Java.Trace.Destination.Console=disabled
#
# Directory for Java trace file
# Windows:
# Diagnostics.Java.Trace.Destination.Pathname=c:\\tracedir
# UNIX:
# Diagnostics.Java.Trace.Destination.Pathname=/var/mqm/trace
# IBM i:
# Diagnostics.Java.Trace.Destination.Pathname=/qibm/userdata/mqm/trace
#
# Directory for First Failure Data Capture
# Windows:
# Diagnostics.Java.FFDC.Destination.Pathname=c:\\errorsdir
# UNIX:
#Diagnostics.Java.FFDC.Destination.Pathname=/var/mqm/errors
# IBMi:
#Diagnostics.Java.FFDC.Destination.Pathname=/qibm/userdata/mqm/errors


Specify the full path of the properties file when executing the Java program.
Some examples are given below. There is only one command, which is long, and should take only one line.

Windows:
java -Djava.library.path="C:\Program Files\IBM\WebSphere MQ\Java\lib" -Dcom.ibm.mq.commonservices="C:\temp\mq7-java-prop-test.txt" MQSamplePut

UNIX:
java -Djava.library.path=/opt/mqm/java/lib -Dcom.ibm.mq.commonservices=/tmp/mq7-java-prop.txt MQSamplePut


IBMi:
java -Djava.library.path=/qibm/proddata/mqm/java/lib -Dcom.ibm.mq.commonservices=/tmp/mq7-java-prop.txt MQSamplePut

If the Java program is running on the same machine as a queue manager
Generated trace data will be sent to the queue manager for processing. This means that the trace will be in the standard WebSphere MQ queue manager format for the platform that the application is running on, and will need to be formatted appropriately.

If the Java program is not running on the same machine as a queue manager
Formatting of the trace file is not required.

z/OS Platform:
WMQ for z/OS does not have the queue manager common services implementation to allow the Java trace to be written into the queue manager trace, so you need to ensure that it is configured to produce stand-alone trace. The main difference in the properties is that Diagnostic.MQ should be disabled on z/OS.

The resulting trace will be written to files in the directory specified by the Diagnostics.Java.Trace.Destination.Pathname variable.

Create an MQ Java properties file.
#
# Base WebSphere MQ diagnostics are disabled
#
Diagnostics.MQ=disabled
#
Diagnostics.Java=wmqjavaclasses
#
Diagnostics.Java.Trace.Detail=high
#
Diagnostics.Java.Trace.Destination.File=enabled
Diagnostics.Java.Trace.Destination.Console=disabled
#
Diagnostics.Java.Trace.Destination.Pathname=/u/burnsd/mqtrace
#
Diagnostics.Java.FFDC.Destination.Pathname=/u/burnsd/mqtrace
#

Specify the full path of the properties file when executing the Java program.
As with distributed, this file should be specified as a property on the Java command line, e.g.

java -Dcom.ibm.mq.commonservices=/u/burnsd/mqjavatraceconfig.txt MyTest


MQ V6:

  • Start and stop trace:

    WebSphere MQ base Java classes includes a trace facility which you can use to produce diagnostic output if you suspect that there might be a problem with the code. Your program must control tracing using the enableTracing and disableTracing methods of the MQEnvironment class. For example:



  • Format trace:

      Formatting is not required

The trace records are by default written to the Java console, but if you specify an output file name the trace output will be written there instead.

For additional details regarding trace, refer to the publication:
WebSphere MQ Using Java.




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 regarding trace, refer to the publication:
WebSphere MQ Using Java.




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



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

Product Alias/Synonym

WMQ MQ

Rate this page:

(0 users)Average rating

Add comments

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

Operating system(s):

AIX, HP NonStop, HP-UX, IBM i, Linux, OpenVMS, Solaris, Windows, z/OS, z/VSE

Software edition:

All Editions

Reference #:

1174924

Modified date:

2014-04-17

Translate my page

Machine Translation

Content navigation