strmqtrc

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

Purpose

Use the strmqtrc command to enable tracing.

You must use the strmqtrc command from the installation associated with the queue manager that you are working with. You can find out which installation a queue manager is associated with using the dspmq -o installation command. 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

The syntax of this command is as follows:

Description

The strmqtrc command enables tracing. The command has optional parameters that specify the level of tracing you want:

One or more queue managers
Levels of trace detail
One or more WebSphere® MQ processes. The processes can be either part of the WebSphere MQ product or customer applications that use the WebSphere MQ API
Specific threads within customer applications, either by WebSphere MQ thread number or by operating system thread number
Events. These can be either the entry or exit from internal WebSphere 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 WebSphere MQ as having a logical AND between them. You 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 WebSphere 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® WebSphere MQ client on HP Integrity NonStop Server, you 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, you 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 you include this flag, 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

You cannot use the -e flag with the -m flag, -i flag, the -p flag, the -c flag, or the -b flag. If you try to use the -e flag with the -m flag, the -i flag, the -p flag, the -c flag, or the -b flag, 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, you 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 you 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.

If you supply multiple trace types, each must have its own -t flag. You can include any number of -t 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 flags.

all

Output data for every trace point in the system (the default). The all parameter activates tracing at default detail level.

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 WebSphere 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 WebSphere MQ Explorer.

java

Output data for trace points associated with applications using the WebSphere 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.

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.

soap

Output data for trace points associated with WebSphere MQ Transport for SOAP.

ssl

Output data associated with using GSKit to enable Secure Sockets Layer (SSL) channel security.

versiondata

Output data for trace points associated with the version of WebSphere 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 you can specify are those listed for the -t flag.

You can use the -x flag with tracetype values to exclude those entry points you 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 flag. You can include any number of -x flags, if each has a valid tracetype associated with it.

-l MaxSize

The maximum size of a trace file (AMQppppp.qq.TRC) in megabytes (MB). For example, if you 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 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.

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

-d 0

Trace no user data.

-d -1 or all

Trace all user data.

-d 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. You cannot use the -i flag with the -e flag. If you try to use the -i flag with the -e flag, then an error message is issued.

The precise format of this parameter is PID[.TID]. For example:

Coding -i 12345 traces all threads in PID 12345, whereas
Coding -i 12345.67 traces only thread 67 in PID 12345

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

-p Apps

The named processes to which the trace generation is restricted. Apps is a comma-separated list. You 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. You cannot use the -p flag with the -e flag. If you try to use the -p flag with the -e flag, 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 WebSphere MQ problem diagnostics.

-s

Reports the tracing options that are currently in effect. You 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 WebSphere 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. You can use asterisk (*) and question mark (?) wildcards in the specification of probe IDs. You cannot use the -b flag with the -e flag. If you try to use the -b flag with the -e flag, 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 WebSphere 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 WebSphere MQ problem diagnostics.

Return codes

Return code	Description
AMQ7024	Non-valid arguments supplied to the command.
AMQ7077	You are not authorized to perform the requested operation.
AMQ8304	Nine concurrent traces (the maximum) already running.
58	Inconsistent use of installations detected

Examples

This command enables tracing of processing flow from common services and the local queue manager for a queue manager called QM1 in IBM WebSphere MQ for UNIX systems. Trace data is generated at the default level of detail.

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

This command disables tracing of SSL activity on a queue manager called QM1. Other trace data is generated at the parms level of detail.

strmqtrc -m QM1 -x ssl -t parms

This command enables high-detail tracing of the processing flow for all components:

strmqtrc -t all -t detail

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

The next examples use the -p and -m flags to show the following:

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

This command enables tracing for all threads that result from any executing process 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 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
```

Related commands

Command	Description
dspmqtrc	Display formatted trace output
endmqtrc	End trace