Using trace with IBM MQ server on IBM i

If you have an IBM® MQ server installation on IBM i, you can use the TRCMQM command to start and stop tracing and specify the type of trace that you require. Alternatively, you can control tracing from the IBM i command line by calling the QMQM/STRMQTRC and QMQM/ENDMQTRC programs, or in the IBM i Qshell using the STRMQTRC, ENDMQTRC and DSPMQTRC commands.

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.

Early tracing lets you trace the creation and startup of queue managers. However, early trace can easily generate large amounts of trace, because it is implemented by tracing all jobs for all queue managers.

If you have an IBM MQ server installation on IBM i, the TRCMQM command is the most commonly used way of starting and stopping trace. You can use the optional parameters to specify the level of tracing you want. For example:

To specify the level of detail you want, use the TRCLEVEL parameter.
To specify the type of trace output you want, use the OUTPUT parameter.
For selective component tracing, use the TRCTYPE and -EXCLUDE parameters to reduce the amount of trace data being saved, improving runtime performance. Specify the points that you want to trace by using the TRCTYPE parameter or the points you do not want to trace by using the -EXCLUDE parameter. If you omit the TRCTYPE parameter, all trace points are enabled. If you omit the -EXCLUDE parameter, all trace points specified in TRCTYPE are enabled.
To wrap trace, and to specify the maximum size of storage to be used for the collected trace records, use the MAXSTG parameter.
For selective process tracing, use the JOB parameter to restrict trace generation to specified named processes.
If you need to prevent IBM MQ from including any message data in its traces, use the DATASIZE(*NONE) parameter.

For more information, see TRCMQM (Trace MQ).

Note: You can either enter the TRCMQM command manually as shown in the examples in this task, or you can type TRCMQM and press F4 followed by F9 to enable tracing using the TRCMQM panel.

You can also use the following commands to control the trace facility:

Starting a trace

You can start tracing at the IBM i command line by calling the QMQM/STRMQTRC program, or at the IBM i Qshell by using the STRMQTRC command. You can use the optional parameters to 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. If you supply multiple trace types, each must have its own -t or -x flag. You can include any number of -t or -x flags, if each has a valid trace type associated with it. It is not an error to specify the same trace type on multiple -t or -x flags.
For selective process tracing, use the -p parameter to restrict trace generation to specified named processes.
If you need to prevent IBM MQ from including any message data in its traces, use the -d 0 parameter.

For more information, see strmqtrc (start trace).

Ending a trace

You can end tracing at the IBM i command line by calling the QMQM/ENDMQTRC program, or at the IBM i Qshell by using the ENDMQTRC command. You can end early tracing of all processes by specifying no parameters, or you can end a specific type of trace by including the appropriate parameter. For more information, see endmqtrc (end trace).

Formatting trace

The trace files generated by IBM MQ are binary. You can use the DSPMQTRC command at the IBM i Qshell to format trace output before sending it to IBM. For more information, see dspmqtrc (display formatted trace).

Procedure

Start tracing.
By default all trace points are enabled and a default-detail trace is generated. To control which processes generate trace files and what kinds of data they trace, specify the appropriate parameters.
For example:
Starting a default detail trace
- Using the TRCMQM command:
  TRCMQM SET(*ON)
- Using the command line:
  CALL PGM(QMQM/STRMQTRC)
- Using the Qshell:
  /QSYS.LIB/QMQM.LIB/STRMQTRC.PGM
Starting a default detail trace of queue manager QMA
- Using the TRCMQM command:
  TRCMQM SET(*ON) MQMNAME(QMA)
- Using the command line:
  CALL PGM(QMQM/STRMQTRC) PARM('-m' 'QMA')
- Using the Qshell:
  /QSYS.LIB/QMQM.LIB/STRMQTRC.PGM -m QMA
Starting a default detail trace of queue manager QMB with no message data included
- Using the TRCMQM command:
  TRCMQM SET(*ON) MQMNAME(QMB) DATASIZE(*NONE)
- Using the command line:
  CALL PGM(QMQM/STRMQTRC) PARM('-m' 'QMB' '-d' '0')
- Using the Qshell:
  /QSYS.LIB/QMQM.LIB/STRMQTRC.PGM -m QMB -d 0
Starting an API trace of jobs named AMQSPUT with all data
- Using the TRCMQM command:
  TRCMQM SET(*ON) TRCTYPE(*API) JOB(AMQSPUT) DATASIZE(*ALL)
- Using the command line:
  CALL PGM(QMQM/STRMQTRC) PARM('-t' 'api' '-p' 'AMQSPUT' '-d' 'all')
- Using the Qshell:
  /QSYS.LIB/QMQM.LIB/STRMQTRC.PGM -t api -p AMQSPUT -d all
Starting a high detail early trace with files that wrap at 16MB
- Using the TRCMQM command:
  TRCMQM SET(*ON) TRCEARLY(*YES) TRCLEVEL(*DETAIL) MAXSTG(16)
- Using the command line:
  CALL PGM(QMQM/STRMQTRC) PARM('-e' '-t' 'all' '-t' 'detail' '-l' '16')
- Using the Qshell:
  /QSYS.LIB/QMQM.LIB/STRMQTRC.PGM -e -t all -t detail -l 16
Reproduce the problem while tracing is active, making every attempt to keep the trace as short as possible.
To check trace status, use one of the following options:
- Use the SET parameter of the TRCMQM command:
```
TRCMQM SET(*STS)
WRKSPLF SELECT(QMQM)
```
  Use option 5 to view the TRCMQM spool file, which contains the trace status.
- On the command line, use the -s parameter of the QMQM/STRMQTRC program:
```
CALL PGM(QMQM/STRMQTRC) PARM('-s')
```
- In the Qshell, use the -s parameter of the STRMQTRC command:
```
/QSYS.LIB/QMQM.LIB/STRMQTRC.PGM -s
```
Stop tracing with the TRCMQM 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.
For example:
Stopping all traces
- Using the command line:
  CALL PGM(QMQM/ENDMQTRC) PARM('-a')
- Using the Qshell:
  /QSYS.LIB/QMQM.LIB/ENDMQTRC.PGM -a
There is no equivalent in the TRCMQM command.
Stopping a default detail trace
- Using the TRCMQM command:
  TRCMQM SET(*OFF)
- Using the command line:
  CALL PGM(QMQM/ENDMQTRC)
- Using the Qshell:
  /QSYS.LIB/QMQM.LIB/ENDMQTRC.PGM
Using endmqtrc with no parameters has the same effect as endmqtrc -e. You cannot specify the -e parameter with the -m parameter, the -i parameter, or the -p parameter.

Stopping a trace of queue manager QMA
- Using the TRCMQM command:
  TRCMQM SET(*OFF) MQMNAME(QMA)
- Using the command line:
  CALL PGM(QMQM/ENDMQTRC) PARM('-m' 'QMA')
- Using the Qshell:
  /QSYS.LIB/QMQM.LIB/ENDMQTRC.PGM -m QMA
Stopping a trace of jobs named AMQSPUT
- Using the TRCMQM command:
  TRCMQM SET(*OFF) JOB(AMQSPUT)
- Using the command line:
  CALL PGM(QMQM/ENDMQTRC) PARM('-p' 'AMQSPUT')
- Using the Qshell:
  /QSYS.LIB/QMQM.LIB/ENDMQTRC.PGM -p AMQSPUT
Stopping an early trace
- Using the TRCMQM command:
  TRCMQM SET(*OFF) TRCEARLY(*YES)
- Using the command line:
  CALL PGM(QMQM/ENDMQTRC) PARM('-e')
- Using the Qshell:
  /QSYS.LIB/QMQM.LIB/STRMQTRC.PGM -e
Optional: Format the binary trace files.
The trace files generated by IBM MQ are binary, and must be formatted before they can be read. You can either send the binary traces to IBM, or you can format them at the Qshell at a time when your system is not under heavy load. For example:
```
/QSYS.LIB/QMQM.LIB/DSPMQTRC.PGM [-t FormatTemplate] [-h] [-s]
[-o OutputFileName] InputFileName
```
where:
- InputFileName is a required parameter specifying the name of the file containing the unformatted trace. For example, /QIBM/UserData/mqm/trace/AMQ12345.TRC.
- -t FormatTemplate specifies the name of the template file containing details of how to display the trace. The default value is /QIBM/ProdData/mqm/lib/amqtrc.fmt.
- -h omits header information from the report.
- -s extracts trace header and puts it to stdout.
- -o output_filename specifies the name of the file into which to write formatted data.
You can also specify dspmqtrc * to format all trace.
If you format the traces yourself, delete the binary trace files before sending your files to IBM:
- Using the command line to delete the binary trace files:
```
RMVLNK OBJLNK('/QIBM/UserData/mqm/trace/AMQ*.?.TR?')
```
- Using the Qshell to display a formatted trace file using the DSPMQTRC command and then delete the binary trace files:
```
cd /QIBM/UserData/mqm/trace
/QSYS.LIB/QMQM.LIB/DSPMQTRC.PGM AMQ*.TR?
rm -f AMQ*.?.TR?
```
Collect the traces and any other troubleshooting information relating to your problem.
You can do this either automatically or manually:
- Collect the data automatically by using the runmqras command as described in Collecting troubleshooting information automatically with runmqras. 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.
  You must run the runmqras command at the Qshell as shown in the following example:
```
/QIBM/ProdData/mqm/bin/runmqras -section trace,defs,cluster -caseno TS001234567 -qmlist QMA
```
- Alternatively, collect the data manually as described in Collecting troubleshooting information manually.
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 to reclaim space and also to make sure you are ready to generate new traces in future, if necessary.
- Using the command line:
```
RMVLNK OBJLNK('/QIBM/UserData/mqm/trace/AMQ*.*')
```
- Using the Qshell:
```
cd /QIBM/UserData/mqm/trace
rm -f AMQ*.*
```