Tracing on Windows

On Windows, you can use the strmqtrc and endmqtrc commands to start and end tracing. You can also use IBM® MQ Explorer to start and end tracing.

Before you begin

To format or view a trace file, you must be either the creator of the trace file, or a member of the mqm group.

Before you enable tracing in IBM MQ, ensure that there is plenty of free disk space in the trace directory, otherwise, if this directory gets filled with trace files, it could impact the running of the queue managers due lack of available disk space.

When taking long traces of an IBM MQ queue manager or a C-based IBM MQ client application, you can mitigate any potential disk space issues by using the environment variable MQTRACEPATH to point to a directory that has more disk space as shown in the following example:

set MQTRACEPATH=D:\mqtrace

Notes:

Before setting MQTRACEPATH, make sure that the queue manager is not already running, otherwise setting this environment variable will NOT change the location when traces are generated.
You must ensure that the directory has the same file permissions and ownership as /var/mqm/trace.

For more information, see the IBM Support technote Approaches to mitigate the disk space issue when taking long traces for IBM MQ

About this task

Traces can capture the root cause of many IBM MQ problems. It is important to limit how long tracing is active in order to avoid affecting performance or generating excessively large trace files and filling up your disk.

On Windows, you use the following commands to control the trace facility:

strmqtrc

On Windows systems, you enable or modify tracing using the strmqtrc control command. The command has optional parameters that specify the level of tracing you want. For example:

For selective component tracing, use the -t and -x parameters to control the amount of trace detail to record. Specify the points that you want to trace by using the -t parameter or the points you do not want to trace by using the -x parameter. You can run multiple traces with different parameters at the same time, if necessary.
For selective process tracing, use the -p parameter to restrict trace generation to specified named processes.
To prevent IBM MQ from including any message data in its traces, use the -d 0 parameter.

For more information, see strmqtrc (start trace).

endmqtrc

To stop tracing, you use the endmqtrc control command. The endmqtrc command ends only the trace that is described by its parameters. Using endmqtrc with no parameters ends early tracing of all processes. For more information, see endmqtrc (end trace).

On Windows systems, you can alternatively use IBM MQ Explorer to start and stop tracing as follows:

Start the IBM MQ Explorer from the Start menu.
In the Navigator View, right-click the IBM MQ tree node, and select Trace.... The Trace Dialog is displayed.
Click Start or Stop as appropriate.

The output files are created in the MQ_DATA_PATH/trace directory.

Trace files are named AMQppppp.qq.TRC where the variables are:

ppppp: The ID of the process reporting the error.
qq: A sequence number, starting at 0. If the full file name exists, this value is incremented by one until a unique trace file name is found. A trace file name can exist if a process is reused.

Note:

The process identifier can contain fewer, or more, digits than shown in the example.
There is one trace file for each process running as part of the entity being traced.

SSL trace files have the names AMQ.SSL.TRC and AMQ.SSL.TRC.1.

The trace files generated by IBM MQ on Windows are readable text files (except for AMQ.SSL.TRC and AMQ.SSL.TRC.1, if present). On Windows, trace files do not need to be formatted before you send them to IBM Support.

Procedure

If you have multiple installations of IBM MQ on a single Windows system, make sure that your environment is set for the installation that you want to trace.
For example, if you are tracing a queue manager or application associated with Installation1, then you must use the setmqenv command to switch to Installation1 before running any of the commands to start, stop, or format traces, otherwise, your trace will capture no useful information.
Check the /etc/opt/mqm/mqinst.ini file to determine the location of the IBM MQ installations on your system. Use the setmqenv command to set your environment for the installation you want to trace.
For example:
Setting your environment for Installation1
```
"C:\Program Files\IBM\MQ\bin\setmqenv" -n Installation1
```
Setting your environment for the installation with queue manager QMA
```
"C:\Program Files\IBM\MQ\bin\setmqenv" -m QMA
```
The traces are written to the trace subdirectory under the path given by the MQ_DATA_PATH environment variable. After running setmqenv, you can find the location of the trace directory by running:
```
echo "%MQ_DATA_PATH%\trace"
```
Start tracing with the strmqtrc command.
By default all trace points are enabled and a default-detail trace is generated. The parameters passed to strmqtrc control which processes generate trace files and what kinds of data they trace. For example:
Tracing only data flowing over communications networks
```
strmqtrc -x all -t comms
```
Starting a default detail trace of queue manager QMA
```
strmqtrc -m QMA
```
Starting a default detail trace of queue manager QMB with no message data included
```
strmqtrc -m QMB -d 0
```
Starting an API trace of processes named amqsput with all message data included
```
strmqtrc -t api -p amqsput -d all
```
Starting a high detail trace of everything with files that wrap at 100MB
```
strmqtrc -e -t all -t detail -l 100
```
Reproduce the problem while tracing is active, making every attempt to keep the trace as short as possible.
To check trace status use the -s parameter of the strmqtrc command:
```
strmqtrc -s
```
Stop tracing with the endmqtrc command.
As soon as the problem has occurred, stop tracing immediately. If you wait to stop the trace, the data that IBM Support needs might be lost or overwritten. You can stop all traces at once, or you can stop each trace individually. For example:
Stopping all traces in an installation
```
endmqtrc -a
```
Stopping a trace of queue manager QMA
```
endmqtrc -m QMA
```
Stopping a trace of processes named amqsput
```
endmqtrc -p amqsput
```
Collect the traces and any other troubleshooting information relating to your problem.
If you are using the runmqras command to collect IBM MQ troubleshooting information and you need to include trace data, you must include trace in the section names that you specify for the -section parameter. If the traces are very large, you might need to use the -workdirectory option to package the files in a directory with plenty of free space. For more information, see Collecting troubleshooting information automatically with runmqras.
Send the traces and any other troubleshooting information that you have collected for the same problem to IBM.
For more information, see Sending troubleshooting information to IBM.
Clean up the trace directory
Save a copy of the trace files as long as you are working with IBM Support, but keep them somewhere other than the trace directory. Clean up the trace directory to reclaim space and also to make sure you are ready to generate new traces in future, if necessary. For example:
```
C:\> CD "%MQ_DATA_PATH%\trace"
C:\ProgramData\IBM\MQ\trace> DEL AMQ*.TRC AMQ*.TRS
```