How well do you know amqsact?

A common question that comes up is “what did my IBM MQ application program do?“

For example, we expected messages to be on this queue, but they are not there.  What happened? Did the messages actually get put to that queue, or was it put to a different queue, or was there an error that was not captured. Since this type of information is application specific, there is no easy way to tell without debugging the application. 

Well, actually there is a way to see the application requests called application activity events.

Application activity events are a trace of all of the MQ calls being done, the parameters passed and the responses from MQ. While application activity events  was introduced back in MQ 7, there were a number of enhancements to the facility since then and this discussion pertains to MQ 8 and higher.

In order to display the data from these events, a new sample program was introduced, amqsact.   This actually provides a number of ways to view the data. 

Summary view – Use this option when you just want to know what calls the application did but don’t care about the details.

(partial sample output)

Tid Date Time Operation CompCode MQRC HObj (ObjName)
001 2020-05-18 10:51:12 MQXF_CONNX MQCC_OK 0000 –
001 2020-05-18 10:51:12 MQXF_OPEN MQCC_OK 0000 2 (Sample. Queue)
001 2020-05-18 10:51:17 MQXF_PUT MQCC_OK 0000 2 (Sample. Queue)
001 2020-05-18 10:51:25 MQXF_PUT MQCC_OK 0000 2 (Sample. Queue)
001 2020-05-18 10:51:27 MQXF_PUT MQCC_FAILED 2053 2 (Sample. Queue)
001 2020-05-18 10:51:27 MQXF_CLOSE MQCC_OK 0000 2 (Sample. Queue)
001 2020-05-18 10:51:27 MQXF_DISC MQCC_OK 0000 –

This example shows the full flow from connect, open, and 3 puts to the queue, where one failed with 2053 (queue full). 

Verbose view – Use this option when you want to see exactly what was passed and returned with each application call. 

(partial sample output)

Operation Id: MQXF_PUT
ApplicationTid: 1
OperationDate: ‘2020-05-18’
OperationTime: ’10:56:27′
High Res Time: 1589817387069740
QMgr Operation Duration: 23
Completion Code: MQCC_FAILED
Reason Code: 2053
Msg length: 16
Object_name: ‘Sample.Queue’
Expiry: -1
Format_name: ‘MQSTR’
Persistence: 2
Msg_id:
00000000: 0000 0000 0000 0000 0000 0000 0000 0000 ‘…………….’
00000010: 0000 0000 0000 0000 ‘…….. ‘
Encoding: 546

This example shows the details with the put to the queue that failed and you can see that much more information is available.

There are 3 different ways of activating application activity events.  The MQ admin can turn on tracking for all applications or select application by updating a control file.   In both of these cases, the activity events are sent to a SYSTEM queue for processing.

But requiring an MQ admin and/or using a SYSTEM queue is not convenient when you want to quickly track an application. In these cases, you can use the subscription option. Using this option, no other configuration of the queue manager is required and the results are passed via a topic.  By running the following command, you can quickly see the application behavior

amqsact -m QM_B -a amqsput.exe -w 300 -v

where the queue manager is QM_B, the program to trace is amqsact.exe, after 300 seconds with no activity it will terminate and the verbose option is used.  You can also subscribe to a channel which is useful when dealing with client applications. 

While this works well, with simple analysis, the more data you get then the longer you need to observe the application, this does not scale.   In these cases, a tool like the free Nastel XRay Express for IBM MQ is a better option to review the results.  For example, this simple screen shot shows the percent of calls being made over time. 

This was just was a quick overview of the features available and we will have additional writeup on this in the future.  In closing, there are a few open Request for Enhancement (RFEs) for the activity events.   We encourage you to vote for these if you find them useful.

The ability to trace by queue name rather than application or channel

http://www.ibm.com/developerworks/rfe/execute?use_case=viewRfe&CR_ID=118098

Distinct options for subscription-based activity traces

http://www.ibm.com/developerworks/rfe/execute?use_case=viewRfe&CR_ID=125162

Application Activity Trace support for z/OS

http://www.ibm.com/developerworks/rfe/execute?use_case=viewRfe&CR_ID=56321