Use trace with IBM MQ server on IBM i

Use the TRCMQM command to start and stop tracing and specify the type of trace that you require.

There are two stages in using trace:

1. Decide whether you want early tracing. Early tracing lets you trace the creation and startup of queue managers. Note, however, that early trace can easily generate large amounts of trace, because it is implemented by tracing all jobs for all queue managers. To enable early tracing, use TRCMQM with the TRCEARLY parameter set to *YES.
2. Start tracing work using TRCMQM *ON. To stop the trace, we have two options:
   • TRCMQM *OFF, to stop collecting trace records for a queue manager. The trace records are written to files in the /QIBM/UserData/mqm/trace directory.
   • TRCMQM *END, to stop collecting trace records for all queue managers and to disable early trace. This option ignores the value of the TRCEARLY parameter.

Specify the level of detail you want, using the TRCLEVEL parameter set to one of the following values:

*DFT

For minimum-detail level for flow processing trace points.

*DETAIL

For high-detail level for flow processing trace points.

*PARMS

For default-detail level for flow processing trace points.

Specify the type of trace output you want, using the OUTPUT parameter set to one of the following values:

*MQM

Collect binary IBM MQ trace output in the directory specified by the TRCDIR parameter. This value is the default value.

*MQMFMT

Collect formatted IBM MQ trace output in the directory specified by the TRCDIR parameter.

*PEX

Collect Performance Explorer (PEX) trace output

*ALL

Collect both IBM MQ unformatted trace and PEX trace output

Selective trace

We can reduce the amount of trace data being saved, improving runtime performance, using the command TRCMQM with F4=prompt, then F9 to customize the TRCTYPE and EXCLUDE parameters:

TRCTYPE

Specifies the type of trace data to store in the trace file. If you omit this parameter, all trace points except those trace points specified in EXCLUDE are enabled.

EXCLUDE

Specifies the type of trace data to omit from the trace file. If you omit this parameter, all trace points specified in TRCTYPE are enabled.

The options available on both TRCTYPE and EXCLUDE are:

*ALL (TRCTYPE only)

All the trace data as specified by the following keywords is stored in the trace file.

trace-type-list

We can specify more than one option from the following keywords, but each option can occur only once.

*API

Output data for trace points associated with the MQI and major queue manager components.

*CMTRY

Output data for trace points associated with comments in the IBM MQ components.

*COMMS

Output data for trace points associated with data flowing over communications networks.

*CSDATA

Output data for trace points associated with internal data buffers in common services.

*CSFLOW

Output data for trace points associated with processing flow in common services.

*LQMDATA

Output data for trace points associated with internal data buffers in the local queue manager.

*LQMFLOW

Output data for trace points associated with processing flow in the local queue manager.

*OTHDATA

Output data for trace points associated with internal data buffers in other components.

*OTHFLOW

Output data for trace points associated with processing flow in other components.

*RMTDATA

Output data for trace points associated with internal data buffers in the communications component.

*RMTFLOW

Output data for trace points associated with processing flow in the communications component.

*SVCDATA

Output data for trace points associated with internal data buffers in the service component.

*SVCFLOW

Output data for trace points associated with processing flow in the service component.

*VSNDATA

Output data for trace points associated with the version of IBM MQ running.

Wrapping trace

Use the MAXSTG parameter to wrap trace, and to specify the maximum size of storage to be used for the collected trace records. The options are:

*DFT

Trace wrapping is not enabled. For each job, trace data is written to a file with the suffix .TRC until tracing is stopped.

maximum-K-bytes

Trace wrapping is enabled. When the trace file reaches its maximum size, it is renamed with the suffix .TRS, and a new trace file with suffix .TRC is opened. Any existing .TRS file is deleted. Specify a value in the range 1 through 16 000.

Formatting trace output

To format any trace output:

• Enter the QShell
• Enter the command

  /QSYS.LIB/QMQM.LIB/DSPMQTRC.PGM [-t Format] [-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

  Omit header information from the report.

  -s

  Extract trace header and put to stdout.

  -o output_filename

  The name of the file into which to write formatted data.

We can also specify dspmqtrc * to format all trace.