strmqtrc (Start trace)

Start trace at a specified level of detail, or report the level of tracing in effect.

Purpose

You can use the strmqtrc command to enable tracing. You can specify the tracing that you want:
  • You can trace one or more queue managers.
  • You can trace one or more processes. The processes can be either part of the product or customer applications that use the IBM® MQ API.
  • You can trace specific threads within customer applications, either by thread number or by operating system thread number.
  • You can trace events. These events can be either the entry or exit from internal functions or the occurrence of a first failure data capture (FDC).
  • You can choose from different levels of trace detail.
Trace files are written to the appliance URI mqtrace:///, You can retrieve them by using the copy command (see copy), or by using the IBM MQ Appliance web UI (see Managing files by using the IBM MQ Appliance web UI)

Syntax

Read syntax diagramSkip visual syntax diagram strmqtrc  -m QMgrName -e  -t TraceType -t TraceLevel -x TraceType -l MaxSize -d 0 -1 NumOfBytes -i PidTids -p Apps -s  -b StartTrigger -c StopTrigger -w

Parameters

-m QMgrName
Specifies the name of the queue manager to trace.
You can use an asterisk (*) as a wildcard to replace zero or more characters. You can use a question mark (?) as a wildcard to replace any single character.
-e
Specifies that any process that belongs to any component of any queue manager traces its early processing.
You can use this flag to trace the creation or startup of a queue manager.
You cannot use the -e flag with the -m flag, -i flag, the -p flag, the -c flag, or the -b flag.
The default is not to perform early tracing.
-t TraceType -t TraceLevel
Specifies the points to trace and the amount of trace detail to record.
To specify multiple points to trace, specify multiple -t TraceType -t TraceLevel parameters in sequence.
Each TraceType can be one of the following values for the points to trace:
all
Output data for every trace point in the system. This parameter activates tracing at default detail level.
api
Output data for trace points that are associated with the MQI and major queue manager components.
commentary
Output data for trace points that are associated with comments in the components.
comms
Output data for trace points that are associated with data flowing over communications networks.
csdata
Output data for trace points that are associated with internal data buffers in common services.
csflows
Output data for trace points that are associated with processing flow in common services.
Explorer
Output data for trace points associated with the IBM MQ Explorer.
Java
Output data for trace points associated with applications using the IBM MQ classes for Java™ API.
lqmdata
Output data for trace points that are associated with internal data buffers in the local queue manager.
lqmflows
Output data for trace points that are associated with processing flow in the local queue manager.
otherdata
Output data for trace points that are associated with internal data buffers in other components.
otherflows
Output data for trace points that are associated with processing flow in other components.
parms
Activate tracing at default-detail level for flow processing trace points.
remotedata
Output data for trace points that are associated with internal data buffers in the communications component
remoteflows
Output data for trace points that are associated with processing flow in the communications component.
servicedata
Output data for trace points that are associated with internal data buffers in the service component.
serviceflows
Output data for trace points that are associated with processing flow in the service component.
soap
Output data for trace points associated with IBM MQ Transport for SOAP.
spldata
Output data for trace points that are associated with buffers and control blocks that use a security policy (AMS) operation.
splflows
Output data for trace points that are associated with entry and exit data for functions that use a security policy (AMS) operation.
ssl
Output data that is associated with using GSKit to enable Secure Sockets Layer (SSL) channel security.
versiondata
Output data for trace points that are associated with the version that is running.
The default value is all.
Each TraceLevel can be one of the following values:
detail
Activate tracing at high-detail level for flow processing trace points.
parms
Activate tracing at default-detail level for flow processing trace points.
The default value is parms.
-x TraceType
Specifies the points to exclude from trace.
You can specify the same values for TraceType as listed for the -t parameter. The default value is all.
To specify multiple points to exclude from trace, specify multiple -x TraceType parameters in sequence.
-l MaxSize
Specifies the maximum size of a trace file in megabytes (MB).
The maximum value for MaxSize is 2048.
-d 0
Specifies that no user data is traced.
-d -1
Specifies that all user data is traced.
-d NumOfBytes
Specifies the number of bytes of data to trace.
For a communication trace, trace the specified number of bytes of data, including the transmission segment header (TSH).
For an MQPUT or MQGET call, trace the specified number of bytes of message data that is held in the message buffer.
Values in the range 1 - 15 are not allowed.
-i PidTids
Specifies the process identifier (PID) and thread identifier (TID) to which the trace generation is restricted.
You cannot use the -i flag with the -e flag.
This parameter must be only used under the guidance of IBM Service personnel.
-p Apps
Specifies the named processes to which the trace generation is restricted.
Specify Apps as a comma-separated list, with each name in the list specified exactly as the program name would be displayed in the "Program Name" FDC header. You can use an asterisk (*) as a wildcard to match zero or more characters. You can use a question mark (?) to match a single character.
You cannot use the -p flag with the -e flag.
-s
Specifies that the tracing options that are currently in effect are reported.
You must use this parameter on its own with no other parameters.
-b Start_Trigger
Specifies the FDC probe IDs for which tracing must be turned on.
Start_Trigger takes one of the following values:
FDC=comma-separated list of FDC probe IDs
Turns tracing on when any FDCs with the specified FDC probe IDs are generated.
You can use an asterisk (*) as a wildcard to match zero or more characters. You can use a question mark (?) to match a single character.
You cannot use the -b flag with the -e flag.
This parameter must be used only under the guidance of IBM Service personnel.
-c Stop_Trigger
Specifies the FDC probe IDs for which tracing must be turned off, or interval in seconds after which tracing must be turned off.
Stop_Trigger takes one of the following values:
FDC=comma-separated list of FDC probe IDs
Turns tracing off when any FDCs with the specified FDC probe IDs are generated.
You can use an asterisk (*) as a wildcard to match zero or more characters. You can use a question mark (?) to match a single character.
interval=n
Where n is an unsigned integer in the range 1 - 32,000,000.
Turns tracing off n seconds after it starts or, if it tracing is already enabled, turns tracing off n seconds after this instance of the command is entered.
This parameter must be used only under the guidance of IBM Service personnel.
-w
Allow any application to trigger trace.

Usage notes

  • This command must be run from the IBM MQ administration mode. If the system is in the IBM MQ administration mode the prompt includes mqa(mqcli)#. To enter the IBM MQ administration mode, enter mqcli on the command line. To exit the IBM MQ administration mode, enter exit on the command line.
  • Each combination of parameters on an individual invocation of the command are interpreted as having a logical AND between them. You can start the command multiple times, regardless of whether tracing is already enabled. If tracing is already enabled, the trace options that are in effect are modified to those options specified on the most recent invocation of the command.
  • Multiple invocations of the command, without an intervening enqmqtrc command, are interpreted as having a logical OR between them. The maximum number of concurrent strmqtrc commands that can be in effect at one time is 16.
  • When a trace file reaches the specified maximum, it is renamed to AMQppppp.qq.TRS and a new AMQppppp.qq.TRC file is started. If a previous copy of an AMQppppp.qq.TRS file exists, it is deleted.
  • For more information about this command in IBM MQ, see strmqtrc in the IBM MQ documentation.

Examples

  • The following command enables tracing of processing flow from common services and the local queue manager for a queue manager called exampleQM. Trace data is generated at the default level of detail. 
    strmqtrc -m exampleQM -t csflows -t lqmflows -t parms
  • The following command disables tracing of SSL activity on a queue manager called exampleQM. Other trace data is generated at the parms level of detail. 
    strmqtrc -m exampleQM -x ssl -t parms
  • The following command enables high-detail tracing of the processing flow for all components: 
    strmqtrc -t all -t detail
  • The following command enables tracing when FDC KN34650 occurs, and stops tracing when FDC KN346080 occurs. In both cases the FDC must occur on a process that is using queue manager exampleQM: 
    strmqtrc -m exampleQM -b FDC=KN346050 -c FDC=KN346080
The next examples use the -p and -m flags to show how a combination of parameters on an individual invocation of the command are interpreted as having a logical AND between them. The examples also show how multiple invocations of the command, without an intervening mq enqmqtrc command, are interpreted as having a logical OR between them:
  1. The following command enables tracing for all threads that result from any executing process that is called amqxxx.exe: 
    strmqtrc -p amqxxx.exe
    • If you start the following command after the command in step 1, without an intervening endmqtrc command, then tracing is limited to all threads that result from any running process that is called amqxxx.exe and that are using queue manager exampleQM2: 
      strmqtrc -p amqxxx.exe -m exampleQM2
    • If you start the following command after the command in step 1, without an intervening endmqtrc command, then tracing is limited to all processes and threads that result from running amqxxx.exe or that are using queue manager exampleQM2: 
      strmqtrc -m exampleQM2

Related commands