Configuring activity trace behavior using mqat.ini

Activity trace behavior is configured using a configuration file called mqat.ini. This file is used to define the level and frequency of reporting activity trace data. The file also provides a way to define rules to enable and disable activity trace based on the name of an application.

About this task

[UNIX] [Linux] On UNIX and Linux® systems, mqat.ini is located in the queue manager data directory, which is the same location as the qm.ini file.

[Windows] On Windows systems, mqat.ini is located in the queue manager data directory C:\Program Files\IBM\WebSphere MQ\qmgrs\queue_manager_name. Users running applications to be traced need permission to read this file.

Note: Queue managers migrated from IBM® WebSphere® MQ 7.1 or earlier will have the mqat.ini file missing. In such cases, the mqat.ini file needs to be created manually and 660 permissions need to be set on the file.

When the mqat.ini file is modified, newly created IBM MQ connections will be processed according to the modified version. Existing connections will continue to use the previous version unless the queue manager parameters are altered, for example following an ALTER QMGR command.

This file follows the same stanza key and parameter-value pair format as the mqs.ini and qm.ini files.

The file consists of a single stanza, AllActivityTrace, to configure the level and frequency of reporting activity trace data by default for all activity trace.

The file can also contain multiple ApplicationTrace stanzas. Each one of these, defines a rule for the trace behavior for one or more connections, based on matching the application name of the connections to the rule.

AllActivityTrace stanza

A single AllActivityTrace stanza defines settings for the activity trace that is applied to all IBM MQ connections, unless overridden.

Individual values in the AllActivityTrace stanza can be overridden by more specific information in an ApplicationTrace stanza stanza.

If more than one AllActivityTrace stanza is specified then the values in the last stanza is used. Parameters missing from the chosen AllActivityTrace take default values. Parameters and values from previous AllActivityTrace stanzas are ignored.

The following parameters can be specified under the AllActivityTrace stanza:

Table 1. Parameter/value pairs that can be used in the activity trace configuration file
Name	Values (default in bold type)	Description
ActivityInterval	0-99999999 ( 1 )	Approximate time interval in seconds between trace messages. All activity performed by a connection in that interval will be written in a single message. If this value is 0, the trace message is written when the connection disconnects (or when the activity count is reached).
ActivityCount	0-99999999 ( 100 )	Number of MQI or XA operations between trace messages. If this value is 0, the trace message is written when the connection disconnects (or when the activity interval has elapsed).
TraceLevel	LOW / MEDIUM / HIGH	Amount of parameter detail traced for each operation. The description of individual operations details which parameters are included for each trace level.
TraceMessageData	0 - 104 857 600 ( maximum 100 MB)	Amount of message data traced in bytes for MQGET, MQPUT, MQPUT1, and Callback operations
StopOnGetTraceMsg	ON / OFF	Using activity trace, to trace applications that are also processing activity trace messages, is not advisable due to possible looping occurring.
SubscriptionDelivery	BATCHED / IMMEDIATE	Determines whether the ActivityInterval and ActivityCount parameters are to be used when one or more activity trace subscriptions are present. Setting this parameter to IMMEDIATE results in the ActivityInterval and ActivityCount values being overridden with effective values of 1 when the trace data has a matching subscription. Each activity trace record is not batched with other records from the same connection and instead delivered to the subscription immediately with no delay.

ApplicationTrace stanza

An ApplicationTrace stanza contains a rule which defines which IBM MQ connections will be traced or not trace based on the application name. Optionally, the default behaviour defined under the Allsettings which override the global trace level and frequency settings.

This stanza can include ApplName, ApplFunction and ApplClass parameters which are used according to the matching rules defined in Connection Matching Rules to determine whether the stanza applies to a particular connection or not.

The stanza must include the Trace parameter to determine if this rule turns activity trace on or off for matching connections.

An off rule can be used to explicitly disable trace for more specific application names and to override the ACTVTRC setting of the queue manager or activity trace connection options.

The following parameters can be specified under the ApplicationTrace stanza:

Table 2. Parameter/value pairs that can be used in the application trace configuration file
Name	Values (default in bold type)	Description
Trace	ON / OFF (Required parameter - no default value)	Activity trace switch. This switch can be used in the application-specific stanza to determine whether activity trace is active for the scope of the current application stanza. Note that this value overrides ACTVTRC and ACTVCONO settings for the queue manager.
ApplName	Character string (Required parameter - no default)	This value is used to determine which applications the ApplicationTrace stanza applies to. It is matched to the ApplName value from the API exit context structure (which is equivalent to the MQMD.PutApplName). The content of the ApplName value varies according to the application environment. For platforms other than z/OS®, only the filename portion of the MQAXC.ApplName is matched to the value in the stanza. Characters to the left of the rightmost path separator are ignored when the comparison is made. For z/OS applications, the entire MQAXC.ApplName is matched to the value in the stanza. A single wildcard character () can be used at the end of the ApplName value to match any number of characters after that point. If the ApplName value is set to a single wildcard character () then the ApplName value matches all applications.
ApplFunction	Character string (default value * )	This value is used to qualify which application programs the ApplicationTrace stanza and ApplName value applies to. The stanza is optional, but is only valid for IBM i queue managers. A single wildcard character () can be used at the end of the ApplName value to match any number of characters. For example, an ApplicationTrace* stanza specifying ApplName = `*` and ApplFunction = `AMQSPUT0` applies to all invocations of the AMQSPUT0 program from any job.
ApplClass	USER / MCA / ALL	The class of application. See the following table for an explanation of how the AppType values correspond to IBM MQ connections.

The following table shows how the AppClass values correspond to the APICallerType and APIEnvironment fields in the connection API exit context structure.

Table 3. Appclass values and how they correspond to the APICallerType and APIEnvironment fields
APPLCLASS	API Caller Type:	API Environment:	Description
USER	MQXACT_EXTERNAL	MQXE_OTHER	Only user applications are traced
MCA	(Any value)	MQXE_MCA MQXE_MCA_CLNTCONN MQXE_MCA_SVRCONN	Clients and channels (amqrmppa)
ALL	(Any value)	(Any value)	All connections are traced

Attention: You must use an APPLCLASS of MCA for client user applications, as a class of USER does not match these.

For example, to trace the amqsputc sample application, you could use the following code:

ApplicationTrace:
ApplClass=MCA                           # Application type
                                        #   Values:  (USER | MCA | INTERNAL | ALL)
                                        #   Default: USER
ApplName=amqsputc                       # Application name (may be wildcarded)
                                        #   (matched to app name without path)
                                        #   Default: *
Trace=ON                                # Activity trace switch for application
                                        #   Values:  ( ON | OFF )
                                        #   Default: OFF
ActivityInterval=30                     # Time interval between trace messages
                                        #   Values: 0-99999999 (0=off)
                                        #   Default: 0
ActivityCount=1                         # Number of operations between trace msgs
                                        #   Values: 0-99999999  (0=off)
                                        #   Default: 0
TraceLevel=MEDIUM                       # Amount of data traced for each operation
                                        #   Values: LOW | MEDIUM | HIGH
                                        #   Default: MEDIUM
TraceMessageData=1000                   # Amount of message data traced
                                        #   Values: 0-100000000
                                        #   Default: 0

The default mqat.ini generated when a queue manager is created, contains a single rule to explicitly disable activity trace for the supplied activity trace sample, amqsact.

Connection Matching Rules

The queue manager applies the following rules to determine which stanzas settings to use for a connection.

A value specified in the AllActivityTrace stanza is used for the connection unless the value also occurs in an ApplicationTrace stanza and the stanza fulfills the matching criteria for the connection described in points 2, 3, and 4.
The ApplClass is matched against the type of the IBM MQ connection. If the ApplClass does not match the connection type then the stanza is ignored for this connection.
The ApplName value in the stanza is matched against the file name portion of the ApplName field from the API exit context structure (MQAXC) for the connection.
The file name portion is derived from the characters to the right of the final path separator (/ or \) character. If the stanza ApplName includes a wildcard (*) then only the characters to the left of the wildcard are compared with the equivalent number of characters from the ApplName of the connection.

For example, if a stanza value of "FRE*" is specified then only the first three characters are used in the comparison, so "path/FREEDOM" and "path\FREDDY" match, but "path/FRIEND" does not. If the ApplName value of the stanza does not match the connection ApplName, the stanza is ignored for this connection.
If more than one stanza matches the ApplName and ApplClass of the connection, then the stanza with the most specific ApplName is used.
The most specific ApplName is defined as the one that uses the most characters to match the ApplName of the connection.

For example, if the ini file contains a stanza with ApplName = "FRE*" and another stanza with ApplName = "FREE*" then the stanza with ApplName = "FREE*" is chosen as the best match for a connection with ApplName = "path/FREEDOM" because it matches four characters (whereas ApplName = "FRE*" matches only three).
If after applying the rules in points 2, 3, and 4, there is more than one stanza that matches the connections ApplName and ApplClass of the connection, the values from the last matching will be used and all other stanzas will be ignored.

Overriding default settings for each rule

Optionally, the global trace level and frequency settings under the AllActivityTrace stanza can be overridden for those connections matching an ApplicationTrace stanza.

The following parameters can be set under an ApplicationTrace stanza. If they are not set, the value is inherited from the AllActivityTrace stanza settings:

ActivityInterval
ActivityCount
TraceLevel
TraceMessageData
StopOnTraceMsg

mqat.ini syntax

The syntax rules for the format of the mqat.ini file are:

Text beginning with a hash or semicolon is considered to be a comment that extends to the end of the line.
The first significant (non-comment) line must be a stanza key.
A stanza key consists of the name of the stanza followed by a colon.
A parameter-value pair consists of the name of a parameter followed by an equals sign and then the value.
Only a single parameter-value pair can appear on a line. (A parameter-value must not wrap onto another line).
Leading and trailing whitespace is ignored. There is no limit on the amount of white space between stanza names, parameter names and values, or parameter/value pairs. Line breaks are significant and not ignored
The maximum length for any line is 2048 characters
The stanza keys, parameter names, and constant parameter values are not case-sensitive, but the variable parameter values (ApplName and DebugPath) are case-sensitive.

Application Activity Trace File Example

The following example shows how the configuration data is specified in the Activity Trace ini file.


AllActivityTrace:
ActivityInterval=1
ActivityCount=100
TraceLevel=MEDIUM
TraceMessageData=0
StopOnGetTraceMsg=ON

ApplicationTrace:
ApplName=amqs*
Trace=ON
TraceLevel=HIGH
TraceMessageData=1000

ApplicationTrace:
ApplName=amqsact*
Trace=OFF

The above AllActivityTrace stanza defines how activity trace will perform by default when enabled, either through ApplicationTrace rules or through the queue manager ACTVTRC attribute or programmatically enabled by an application.

The first ApplicationTrace stanza defines a rule that will result in any MQI activity by an application whose name starts with "amqs" being traced. Trace generated for these applications will be of high detail and include up to 1000 bytes of message data. The activity interval and count parameters will be inherited

The second ApplicationTrace stanza defines a rule that turns trace off for applications with names starting "amqsact" (the activity trace sample). This rule will override the earlier 'on' rule for the amqsact application, resulting in no trace for that application.

An example is also shipped as a sample called mqat.ini in the C samples directory (the same directory as the amqsact.c file). This file can be copied to the queue manager data directory, for queue managers that have been migrated from an earlier release of IBM MQ.

What to do next

Enabling application activity trace can affect performance. The overhead can be reduced by tuning the ActivityCount and the ActivityInterval settings. See Tuning the performance impact of application activity trace.