strmqtrc (Start trace)

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

Purpose

Use the strmqtrc command to enable tracing.

dspmq -o installation

This does not apply to a client product (for example, HP Integrity NonStop Server) because there are no queue managers from which to request direct output.

Syntax

Description

• One or more queue managers
• Levels of trace detail
• One or more IBM MQ processes. The processes can be either part of the IBM MQ product or customer applications that use the IBM MQ API
• Specific threads within customer applications, either by IBM MQ thread number or by operating system thread number
• Events. These can be either the entry or exit from internal IBM MQ functions or the occurrence of a first failure data capture (FDC).

Each combination of parameters on an individual invocation of the command are interpreted by IBM MQ as having a logical AND between them. We can start the strmqtrc 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 specified on the most recent invocation of the command. Multiple invocations of the command, without an intervening enqmqtrc command, are interpreted by IBM MQ as having a logical OR between them. The maximum number of concurrent strmqtrc commands that can be in effect at one time is 16.

For the IBM MQ client on HP Integrity NonStop Server, we must direct your trace commands to specific processors. For example, if your client is running on processor 2 and your shell is on processor 1, initiating trace with strmqtrc options does not trace the client. In this case, run -cpu=2 strmqtrc is required.

Optional parameters

-m QMgrName

The name of the queue manager to trace. This parameter applies to server products only.

The following wildcards are allowed: asterisk (*), replacing zero or more characters, and question mark (?), replacing any single character. In command environments such as the UNIX shell, where the asterisk (*) and question mark (?) characters have special meaning, we must either escape the wildcard character or enclose it in quotation marks to prevent the command environment from operating on the wildcard character.

-e

Requests early tracing of all processes, making it possible to trace the creation or startup of a queue manager. If we include this parameter, any process belonging to any component of any queue manager traces its early processing. The default is not to perform early tracing.

Use the following command to trace a client:

strmqtrc -e

We cannot use the -e parameter with the -m parameter, -i parameter, the -p parameter, the -c parameter, or the -b parameter. If you try to use the -e parameter with the -m parameter, the -i parameter, the -p parameter, the -c parameter, or the -b parameter, then an error message is issued.

-t TraceType

The points to trace and the amount of trace detail to record. By default all trace points are enabled and a default-detail trace is generated.

Alternatively, we can supply one or more of the options in the following list. For each Tracetype value you specify, including -t all, specify either -t parms or -t detail to obtain the appropriate level of trace detail. If we do not specify either -t parms or -t detail for any particular trace type, only a default-detail trace is generated for that trace type.

Attention: When using the -t api option, we will see trace of the MQI calls, with all the input and output data blocks dumped in hexadecimal form.

We should be aware that IBM MQ internal programs also make MQI calls, and we will see trace files for those programs. Normally, the program names begin amq or runmq.

We should be aware that amqrmppa programs host many threads, some of which receive MQI calls over the network from client applications. In these threads we will see MQI calls in the -t api traces, but we must remember that the input arguments to those MQI calls traced in the amqrmppa program might not match every detail of the MQI calls made originally by the client.

Therefore, if we need to know, reliably, the input arguments to MQI calls made by the client application, we must use -t api tracing on the client machine directly.

If you supply multiple trace types, each must have its own -t parameter. We can include any number of -t parameters, if each has a valid trace type associated with it.

It is not an error to specify the same trace type on multiple -t parameters.

Value	Description
all	Output data for every trace point in the system (the default). The all parameter activates tracing at default detail level.
amqp	Output data for the AMQP service
api	Output data for trace points associated with the MQI and major queue manager components.
commentary	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.
csflows	Output data for trace points associated with processing flow in common services.
detail	Activate tracing at high-detail level for flow processing trace points.
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 associated with internal data buffers in the local queue manager.
lqmflows	Output data for trace points associated with processing flow in the local queue manager.
mqxr	Output data for the Telemetry (MQXR) service.
otherdata	Output data for trace points associated with internal data buffers in other components.
otherflows	Output data for trace points 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 associated with internal data buffers in the communications component.
remoteflows	Output data for trace points associated with processing flow in the communications component.
servicedata	Output data for trace points associated with internal data buffers in the service component.
serviceflows	Output data for trace points associated with processing flow in the service component.
spldata	Output data for trace points associated with buffers and control blocks that use a security policy (AMS) operation.
splflows	Output data for trace points associated with entry and exit data for functions that use a security policy (AMS) operation.
ssl	Output data associated with using GSKit to enable TLS channel security.
versiondata	Output data for trace points associated with the version of IBM MQ running.

-x TraceType

The points not to trace. By default all trace points are enabled and a default-detail trace is generated. The trace points we can specify are those listed for the -t parameter.

We can use the -x parameter with Tracetype values to exclude those entry points we do not want to record. This is useful in reducing the amount of trace produced.

If you supply multiple trace types, each must have its own -x parameter. You can include any number of -x parameters, if each has a valid Tracetype associated with it.

-l MaxSize

The maximum size of a trace file ( AMQ ppppp. qq.TRC) in megabytes (MB). For example, if we specify a MaxSize of 1, the size of the trace is limited to 1 MB.

When a trace file reaches the specified maximum, it is renamed to AMQ ppppp. qq.TRS and a new AMQ ppppp. qq.TRC file is started. If a previous copy of an AMQ ppppp. qq.TRS file exists, it is deleted.

The highest value that MaxSize can be set to is 2048 MB.

-d

Trace options. The value can be:

0

Trace no user data.

-1 or all

Trace all user data.

NumOfBytes

• 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 held in the message buffer.
• Values in the range 1 through 15 are not allowed.

-i PidTids

Process identifier (PID) and thread identifier (TID) to which the trace generation is restricted. We cannot use the -i parameter with the -e parameter. If you try to use the -i parameter with the -e parameter, then an error message is issued. This parameter must only be used under the guidance of IBM Service personnel.

This parameter is not supported for .NET clients if NMQ_MQ_LIB is set to managed, so that the client uses managed IBM MQ problem diagnostics.

-p Apps

The named processes to which the trace generation is restricted. Apps is a comma-separated list. We must specify each name in the list exactly as the program name would be displayed in the "Program Name" FDC header. Asterisk (*) or question mark (?) wildcards are allowed. We cannot use the -p parameter with the -e parameter. If you try to use the -p parameter with the -e parameter, then an error message is issued.

This parameter is not supported for .NET clients if NMQ_MQ_LIB is set to managed, so that the client uses managed IBM MQ problem diagnostics.

-s

Reports the tracing options that are currently in effect. We must use this parameter on its own with no other parameters.

A limited number of slots are available for storing trace commands. When all slots are in use, then no more trace commands can be accepted unless they replace an existing slot. Slot numbers are not fixed, so if the command in slot number 0 is removed, for example by an endmqtrc command, then all the other slots move up, with slot 1 becoming slot 0, for example. An asterisk (*) in a field means that no value is defined, and is equivalent to the asterisk wildcard.

An example of the output from this command is as follows:

Listing Trace Control Array

Used slots = 2 of 15

EarlyTrace    [OFF]
TimedTrace    [OFF]
TraceUserData [0]
MaxSize       [0]
Trace Type    [1]

Slot position 1

Untriggered
Queue Manager [avocet]
Application   [*]
PID.TID       [*]
TraceOptions  [1f4ffff]
TraceInterval    [0]
Trace Start Time [0]
Trace Stop  Time [0]
Start Trigger [KN346050K]
Start Trigger [KN346080]

Slot position 2

Untriggered
Queue Manager [*]
Application   [*]
PID.TID       [*]
TraceOptions  [1fcffff]
TraceInterval    [0]
Trace Start Time [0]
Trace Stop  Time [0]
Start Trigger [KN346050K]
Start Trigger [KN346080]

This parameter is not supported for .NET clients if NMQ_MQ_LIB is set to managed, so that the client uses managed IBM MQ problem diagnostics.

-b Start_Trigger

FDC probe IDs for which tracing must be turned on. Start_Trigger is a comma-separated list of FDC probe IDs. We can use asterisk (*) and question mark (?) wildcards in the specification of probe IDs. We cannot use the -b parameter with the -e parameter. If you try to use the -b parameter with the -e parameter, then an error message is issued. This parameter must only be used under the guidance of IBM Service personnel.

Start_Trigger	Effect
FDC=comma-separated list of FDC probe IDs.	Turns on tracing when any FDCs with the specified FDC probe IDs are generated.

This parameter is not supported for .NET clients if NMQ_MQ_LIB is set to managed, so that the client uses managed IBM MQ problem diagnostics.

-c Stop_Trigger

FDC probe IDs for which tracing must be turned off, or interval in seconds after which tracing must be turned off. Stop_Trigger is a comma-separated list of FDC probe IDs. You can use asterisk (*) and question mark (?) wildcards in the specification of probe IDs. This parameter should be used only under the guidance of IBM Service personnel.

Stop_Trigger	Effect
FDC=comma-separated list of FDC probe IDs.	Turns tracing off when any FDCs with the specified FDC probe IDs are generated.
interval=n where n is an unsigned integer between 1 and 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 issued.

This parameter is not supported for .NET clients if NMQ_MQ_LIB is set to managed, so that the client uses managed IBM MQ problem diagnostics.

-o

mqm

Enables IBM MQ trace as in previous releases.

This is the default value if no -o option is supplied.

aix

Enables IBM MQ to write AIX system trace, provided AIX system trace is enabled.

As previously, we must use the AIX operating system trace command for any output to actually be produced.

This is a legacy option, and we should use this option only when directed to do so by IBM service personnel.

Return codes

Examples of enabling tracing at different levels of detail

strmqtrc -m QM1 -t csflows -t lqmflows -t parms

strmqtrc -m QM1 -x ssl -t parms

strmqtrc -t all -t detail

Examples of enabling tracing for an FDC

This command enables tracing when FDC KN346050 or FDC KN346080 occur on any process that is using queue manager QM1:

strmqtrc -m QM1 -b FDC=KN346050,KN346080

This 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 QM1:

strmqtrc -m QM1 -b FDC=KN346050 -c FDC=KN346080

Examples of using the -p and -m parameters for individual and multiple invocations of strmqtrc

• How a combination of parameters on an individual invocation of the command are interpreted by IBM MQ as having a logical AND between them.
• How multiple invocations of the command, without an intervening enqmqtrc command, are interpreted by IBM MQ as having a logical OR between them:

1. This command enables tracing for all threads that result from any executing process called amqxxx.exe:

   strmqtrc -p amqxxx.exe
   

2. After running the strmqtrc command as shown in step 1, we can then enter either of the following commands without an intervening endmqtrc command.
   • 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 executing process called amqxxx.exe and that are using queue manager QM2:

     strmqtrc -p amqxxx.exe -m QM2
     

   • 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 executing amqxxx.exe or that are using queue manager QM2:

     strmqtrc -m QM2
     

Example of enabling dynamic tracing of LDAP client library code shipped with IBM MQ

From IBM MQ Version 9.1.0, Fix Pack 4 and IBM MQ Version 9.1.4, it is possible to switch LDAP client trace on and off without also stopping or starting the queue manager.

strmqtrc -m QMNAME -t servicedata

Related commands

Related reference

• Command sets comparison: Other commands