Use trace on UNIX and Linux systems

Use the strmqtrc and endmqtrc commands to start and end tracing, and dspmqtrc to display a trace file

UNIX and Linux systems use the following commands for the IBM MQ MQI client trace facility:

    strmqtrc
    to start tracing

    endmqtrc
    to end tracing

    dspmqtrc filename
    to display a formatted trace file

The trace facility uses a number of files, which are:

  • One file for each entity being traced, in which trace information is recorded
  • One additional file on each machine, to provide a reference for the shared memory used to start and end tracing
  • One file to identify the semaphore used when updating the shared memory

Files associated with trace are created in a fixed location in the file tree, which is /var/mqm/trace.

All client tracing takes place to files in this directory.

We can handle large trace files by mounting a temporary file system over this directory.

On AIX we can use AIX system trace in addition to using the strmqtrc and endmqtrc commands. For more information, see Tracing with the AIX system trace.


Trace files on IBM MQ for UNIX and Linux systems

Trace files are created in the directory /var/mqm/trace.

Note: We can accommodate the production of large trace files by mounting a temporary file system over the directory that contains your trace files. Alternatively, rename the trace directory and create the symbolic link /var/mqm/trace to a different 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:

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

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

SSL trace files have the names AMQ.SSL.TRC and AMQ.SSL.TRC.1. We cannot format SSL trace files; send them unchanged to IBM support.


How to start and stop a trace

In IBM MQ for UNIX and Linux systems, you enable or modify tracing using the strmqtrc control command (see strmqtrc ). To stop tracing, you use the endmqtrc control command (see endmqtrc ). On IBM MQ for Linux (x86 and x86-64 platforms) systems, we can alternatively use the IBM MQ Explorer to start and stop tracing. However, we can trace only everything using the function provided, equivalent to using the commands strmqtrc -e and endmqtrc -e.

Trace output is unformatted; use the dspmqtrc control command to format trace output before viewing. For example, to format all trace files in the current directory use the following command: 
dspmqtrc *.TRC
For detailed information about the control command, dspmqtrc, see dspmqtrc.


Selective component tracing on IBM MQ for UNIX and Linux systems

Use the -t and -x options to control the amount of trace detail to record. By default, all trace points are enabled. Specify the points we do not want to trace using the -x option. If, for example, we want to trace, for queue manager QM1, only output data associated with using Transport Layer Security (TLS) channel security, use: 
strmqtrc -m QM1 -t ssl
For detailed information about the trace command, see strmqtrc.


Selective component tracing on IBM MQ for AIX

Use the environment variable MQS_TRACE_OPTIONS to activate the high detail and parameter tracing functions individually.

Because MQS_TRACE_OPTIONS enables tracing to be active without high detail and parameter tracing functions, we can use it to reduce the effect on performance and trace size when we are trying to reproduce a problem with tracing enabled.

Only set the environment variable MQS_TRACE_OPTIONS if you have been instructed to do so by your service personnel.

Typically MQS_TRACE_OPTIONS must be set in the process that starts the queue manager, and before the queue manager is started, or it is not recognized. Set MQS_TRACE_OPTIONS before tracing starts. If it is set after tracing starts it is not recognized.


Selective process tracing on IBM MQ for UNIX and Linux systems

Use the -p option of the strmqtrc command control to restrict trace generation to specified named processes. For example, to trace all threads that result from any running process called amqxxx, use the following command: 
strmqtrc -p amqxxx
For detailed information about the trace command, see strmqtrc.

Parent topic: Use trace


Related concepts


Related reference