Use amqsact to view trace messages

We can use the amqsact program with IBM MQ Version 9.0 to generate and view trace messages.

The amqsact program is an IBM MQ sample. To use this sample, we must use the client-connected executable file, amqsactc. The executable file is located in the samples directory:

  • On Linux and UNIX platforms, MQ_INSTALLATION_PATH/samp/bin64
  • On Windows platforms, MQ_INSTALLATION_PATH\tools\c\Samples\Bin64

We can use amqsact in two ways:

    Display mode
    Format and display activity trace data messages that are being delivered to SYSTEM.ADMIN.TRACE.ACTIVITY.QUEUE.

    Dynamic mode
    Create a subscription to a set of resources and display the generated activity trace by running amqsact.


Display mode

By default, amqsact in display mode processes messages on SYSTEM.ADMIN.TRACE.ACTIVITY.QUEUE. We can override this behavior by specifying a queue name or topic string. Activity trace must be enabled by using one of the methods that are described in Collecting application activity trace information. We can control the trace period that is displayed and specify whether the activity trace messages are removed or retained after display. In display mode, amqsact takes the following arguments:

    -m queue_manager_name
    Required. Specify the queue manager that trace messages are collected for.

    -q queue_name
    Display only trace messages that are related to the named queue.

    -t topic_string
    Display only trace messages that are related to the named topic.

    -b
    Specify that trace messages are retained after display.

    -v
    Display trace messages in verbose mode.

    -d depth
    The number of messages to display.

    -w timeout
    Specify a timeout. If no trace messages appear in that period, amqsact exits.

    -s start_time
    Use this argument with the -e argument to specify a time period. Trace messages from the specified time period are displayed.

    -e end_time
    Use this argument with the -s argument to specify a time period. Trace messages from the specified time period are displayed.

For example, the following command displays activity trace messages that are held on SYSTEM.ADMIN.TRACE.ACTIVITY.QUEUE, and deletes the messages after display: 

amqsact -m QMGR1
The following command displays activity trace messages on the specified queue, SUB.QUEUE, and deletes the messages after display. Messages continue to be displayed until a period of 30 seconds with no new messages elapses. This command can, for example, be used with a subscription to an activity trace system topic string. 
amqact -m QMGR1 -q SUB.QUEUE.1 -w 30
The following command displays in verbose format any activity trace data that is currently held on the SYSTEM.ADMIN.TRACE.ACTIVITY.QUEUE that occurred in the 20-minute period specified. Messages will remain on the queue after display. 
amqsact -m QMGR1 -b -v -s 2014-12-31 23.50.00 -e 2015-01-01 00.10.00


Dynamic mode

You enable dynamic mode by specifying an application name, a channel name, or a connection identifier as an argument to amqsact. We can use wildcard characters in the name. In dynamic mode, activity trace data is enabled at the start of the sample by use of a non-durable subscription to a system topic. Collecting activity trace data stops when amqsact stops. We must specify a timeout for amqsact in dynamic mode. We can run multiple copies of amqsact concurrently, and each instance receives a copy of any activity trace data. In dynamic mode, amqsact takes the following arguments:

    -m queue_manager_name
    Required. Specify the queue manager that trace messages are collected for.

    -w timeout
    Required. Specify a timeout. If no trace messages appear in that period, amqsact exits.

    -a application_name
    Specify an application to collect messages for.

    -c channel_name
    Specify a channel to collect messages for.

    -i connection_id
    Specify a connection to collect messages for.

    -v
    Display trace messages in verbose mode.

For example, the following command generates and displays activity trace messages for any connections that are made by applications that are named amqsget.exe. After 30 seconds of inactivity, the amqsact program ends, and no new activity trace data is generated. 

amqsactc -m QMGR1 -w 30 -a amqsget.exe
The following command generates and displays activity trace messages for any connections that are made by applications that start with the text amqs. After 30 seconds of inactivity, the amqsact program ends, and no new activity trace data is generated. 
amqsactc -m QMGR1 -w 30 -a amqs*
The following command generates and displays activity trace messages for any activity on the QMGR1.TO.QMGR2 channel. After 10 seconds of inactivity, the amqsact program ends, and no new activity trace data is generated. 
amqsactc -m QMGR1 -w 10 -c QMGR1.TO.QMGR2
The following command generates and displays activity trace messages for any activity on any channels. After 10 seconds of inactivity, the amqsact program ends, and no new activity trace data is generated. 
amqsactc -m QMGR1 -w 10 -c #
The following command generates and displays verbose activity trace messages for any activity on the existing IBM MQ connection that has a CONN of "6B576B5420000701", and an EXTCONN of "414D5143514D47523120202020202020". After a minute of inactivity, the amqsact program ends, and no new activity trace data is generated. 
amqsactc -m QMGR1 -w 60 -i 414D5143514D475231202020202020206B576B5420000701 -v
Parent topic: Subscribing to application activity trace information