Creating subscriptions to application activity trace

You can create subscriptions to specific topics to collect application activity trace data on the IBM® MQ Appliance.

When a subscription is created against specific system topic strings, appropriate activity trace PCF data messages are automatically published to that subscription. For detailed information on subscribing to topics, see Publish/subscribe messaging in the IBM MQ documentation.

The topic strings have the format: 
$SYS/MQ/INFO/QMGR/qmgr_name/ActivityTrace/resource_type/resource_identifier
Where:
  • qmgr_name specifies the queue manager that the traced application is connected to. qmgr_name is the name of the queue manager with all trailing blank characters removed and any forward slash (/) characters replaced by an ampersand (&) character.
  • resource_type specifies the type of resource data is being collected for, and is one of the following strings:
    • ApplName to specify an application. The request subscribes to all IBM MQ connections that have an application name that matches the one specified by the resource_identifier.
    • ChannelName to specify an IBM MQ channel.
    • ConnectionId to specify an IBM MQ connection.
  • resource_identifier identifies the actual resource. The format depends on the resource type:
    • For a resource type of ApplName, the resource_identifier is the trailing part (the value that follows the last / or \) of the application name as seen by the queue manager, with any trailing blank characters removed. The value matches the ApplName value from the API exit context structure (MQAXC). The ApplName of a connection is returned as the APPLTAG value when you use the MQSC command DISPLAY CONN.
    • For a resource type of ChannelName, the resource_identifier is the name of the channel to be traced. If the channel name identifies an SVRCONN channel, all application activity for connected clients is traced. If the channel name identifies a queue manager to queue manager channel, the incoming and outgoing messages are traced. The resource_identifier is the channel name with all trailing blank characters removed and any / characters replaced by an & character.
    • For a resource type of ConnectionId, the resource_identifier is the unique connection identifier that is assigned to each connection. The connection identifier in the topic string is the full 24-byte value written as a hexadecimal string. This value is the concatenation of the EXTCONN followed by the CONN values that are returned from the MQSC command DISPLAY CONN.
    You can use wildcards in a resource_identifier to match multiple resource identities in a single subscription. The wildcard can either be in the default topic style ('#' or '+') or in the character style ('*' or '?'). When you use the topic style wildcard, it cannot be combined with part of a resource name, it can be used only to match all possible applications, channels, or connections. The use of any wildcards increases the level of trace data that is generated, which can affect performance.

To subscribe to these topic strings, you must have subscribe authorization. System topics do not inherit authorizations from the root of the queue manager topic tree. A user must be granted access to an administered topic object at or deeper than the $SYS/MQ point in the topic tree. You can subscribe if you have access to the SYSTEM.ADMIN.TOPIC, although this grants access to all $SYS/MQ topic strings, not just the activity trace. To control access more specifically, new administered topic objects can be defined for deeper points in the tree, either for all activity trace or, for example, for a specific application name or channel name.

Examples

The following example shows a topic string for an application that is named amqsput running on a Windows system: 
$SYS/MQ/INFO/QMGR/QMGR1/ActivityTrace/ApplName/amqsputc.exe
The following example shows a topic string for a channel: 
$SYS/MQ/INFO/QMGR/QMGR1/ActivityTrace/ChannelName/SYSTEM.DEF.SVRCONN
The following example shows a topic string for a connection: 
$SYS/MQ/INFO/QMGR/QMGR1/ActivityTrace/ConnectionId/414D5143514D475231202020202020206B576B5420000701
The following example shows a topic string that creates a subscription to trace data for all channels on queue manager QMGR1: 
$SYS/MQ/INFO/QMGR/QMGR1/ActivityTrace/ChannelName/#
The following example shows a topic string that creates a subscription to trace data for applications with names that start with amqs (note that to use the * wildcard, the subscription must be created using the character wildcard model): 
$SYS/MQ/INFO/QMGR/QMGR1/ActivityTrace/ApplName/amqs*