Configuring activity trace behavior using mqat.ini

The activity trace behavior is configured using a configuration file called mqat.ini. This file follows the same stanza key and parameter-value pair format as the mqs.ini and qm.ini files.

About this task

Linux UNIX 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 Version 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.

The syntax rules for the format of the file are:

Text beginning with a hash or semi-colon is considered to be a comment which 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.

Stanza keys

Two stanza key types are allowed in the configuration file: the AllActivityTrace stanza, and the ApplicationTrace stanza

AllActivityTrace stanza

The AllActivityTrace stanza defines settings for the activity trace that is applied to all IBM WebSphere MQ connections unless overridden.

Individual values in the AllActivityTrace stanza can be overridden by more specific information in an ApplicationTrace 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

ApplicationTrace stanza

The ApplicationTrace stanza defines settings which can be applied to a specific name, type or both of IBM WebSphere MQ connection.

This stanza includes ApplName and ApplClass values which are used according to the matching rules defined in Connection Matching Rules to determine whether the stanza applies to a particular connection.

Parameter/Value Pairs

The following table lists the parameter/value pairs which may be used in the activity trace configuration file.

Table 1. Parameter/value pairs that can be used in the activity trace configuration file
Name	Stanza Type	Values (default in bold type)	Description
Trace	ApplicationTrace	ON / OFF	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.
ActivityInterval	AllActivityTrace ApplicationTrace	0-99999999 (0=off)	Time interval in seconds between trace messages. Activity trace does not use a timer thread, so the trace message will not be written at the exact instant that the time elapses - rather it will be written when the first MQI operation is executed after the time interval has elapsed. If this value is 0 then the trace message is written when the connection disconnects (or when the activity count is reached).
ActivityCount	AllActivityTrace ApplicationTrace	0-99999999 (0=off)	Number of MQI or XA operations between trace messages. If this value is 0 then the trace message is written when the connection disconnects (or when the activity interval has elapsed).
TraceLevel	AllActivityTrace ApplicationTrace	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	AllActivityTrace ApplicationTrace	0- 104 857 600 (100Mb)	Amount of message data traced in bytes for MQGET, MQPUT, MQPUT1, and Callback operations
ApplName	ApplicationTrace	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 distributed platforms, 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 are. If the ApplName value is set to a single wildcard character () then the ApplName value matches all applications.
ApplClass	ApplicationTrace	USER / MCA / INTERNAL / ALL	The class of application. See the following table for an explanation of how the AppType values correspond to IBM WebSphere 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 2. 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)
INTERNAL	MQXACT_EXTERNAL	MQXE_COMMAND_SERVER MQXE_MQSC	'runmqsc' and command server
INTERNAL	MQXACT_INTERNAL	(Any value)	"trusted" and internal applications and processes; for example, amqzdmaa
ALL	(Any value)	(Any value)	All user and internal 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

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 WebSphere 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 connections ApplName. 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 stanzas ApplName value does not match the connection ApplName then the stanza is ignored for this connection.
If more than one stanza matches the connections ApplName and ApplClass, then the stanza with the most specific ApplName is used. The most specific ApplName is defined as the one which uses the most characters to match the connections ApplName. 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, then the values from the last matching will be used and all other stanzas will be ignored.

Application Activity Trace File Example

The following example shows how the configuration data is specified in the Activity Trace ini file. This example is shipped as a sample called mqat.ini in the C samples directory (the same directory as the amqsact.c file)

AllActivityTrace:
  ActivityInterval=0                    # Time interval between trace messages 
                                        #   Values: 0-99999999 (0=off)
                                        #   Default: 0
  ActivityCount=0                       # 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=0                    # Amount of message data traced 
                                        #   Values: 0-100000000
                                        #   Default: 0

ApplicationTrace:
  ApplClass=USER                         # Application type 
                                        #   Values:  (USER | MCA | INTERNAL | ALL)
                                        #   Default: USER
  ApplName=AppName*                     # Application name (may be wildcarded)
                                        #   (matched to app name without path)
                                        #   Default: *
  Trace=OFF                             # Activity trace switch for application 
                                        #   Values:  ( ON | OFF )
                                        #   Default: OFF
ActivityInterval=0                      # Time interval between trace messages 
                                        #   Values: 0-99999999 (0=off)
                                        #   Default: 0
  ActivityCount=0                       # 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=0                    # Amount of message data traced 
                                        #   Values: 0-100000000
                                        #   Default: 0

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.