Control trace in a running process by using IBM MQ classes for Java and IBM MQ classes for JMS

The IBM MQ classes for Java and IBM MQ classes for JMS register a Standard MBean that allows suitable Java Management Extensions (JMX) tools to control certain aspects of trace behavior for a client process.


Principles

As an alternative to the well-known general-purpose tools like jconsole we can use a command-line tool in the form of an executable JAR file to access these facilities.

The JAR file is called com.ibm.mq.traceControl.jar and is stored in the java/lib subdirectory of the IBM MQ installation. For more details see What is installed for IBM MQ classes for JMS and Installation directories for IBM MQ classes for Java .

Note: Depending on configuration, JMX tools can be used either locally (on the same system as the process) or remotely. The local case is discussed initially.


Finding the process

To control a process, we must establish a JMX connection it. To control a process locally, we must specify its identifier.

To display a summary of running Java processes with their identifiers, run the executable JAR file with the option -list. This option produces a list of identifiers and descriptions for the processes that are found.


Examining trace status

When you have found the identifier for the relevant process, run the executable JAR file with the options -i identifier -status, where identifier is the identifier of the process we want to change. These options display the status, either enabled or disabled for the process, and the information about where the process is running, the name of the trace file, and a tree that represents the inclusion and exclusion of packages in trace.


Enable and disabling trace

To enable trace for a process, run the executable JAR file with the options -i identifier -enable.

To disable trace for a process, run the executable JAR file with the options -i identifier -disable.

Note: We can choose only one option from the set -status, -enable, and -disable.


Including and excluding packages

To include a package in trace for a process, run the executable JAR file with the options -i identifier -ip package_name, where package_name is the name of our package.

To exclude a package from trace for a process, run the executable JAR file with the options -i identifier -ep package_name.

Note: We can use multiple -ip and -ep options. These options are not checked for consistency.

When you specify a package for exclusion or inclusion, the handling of packages that have matching prefixes is not affected. For example, excluding the package com.ibm.mq.jms from trace would not exclude com.ibm.mq, com.ibm.msq.client.jms, or com.ibm.mq.remote.api, but it would exclude com.ibm.mq.jms.internal. 

C:>java -jar MQ_INSTALLATION_PATH/java/lib/com.ibm.mq.traceControl.jar -list
10008 : 'MQSample'
9004 : ' MQ_INSTALLATION_PATH/java/lib/com.ibm.mq.traceControl.jar -list'

C:>java -jar MQ_INSTALLATION_PATH/java/lib/com.ibm.mq.traceControl.jar -i 10008 -status
Tracing enabled : false
User Directory : C:\Users\IBM_ADMIN\RTCworkspace\sandpit
Trace File Name : mqjms.trc
Package Include/Exclude tree
root - Included

C:>java -jar MQ_INSTALLATION_PATH/java/lib/com.ibm.mq.traceControl.jar -i 10008 -enable
Enabling trace
Tracing enabled : true

C:>java -jar MQ_INSTALLATION_PATH/java/lib/com.ibm.mq.traceControl.jar -i 10008 -status
Tracing enabled : true
User Directory : C:\Users\IBM_ADMIN\RTCworkspace\sandpit
Trace File Name : mqjms_10008.cl0.trc
Package Include/Exclude tree
root - Included

C:>java -jar MQ_INSTALLATION_PATH/java/lib/com.ibm.mq.traceControl.jar -i 10008 -ip com.ibm.mq.jms
Adding 'com.ibm.mq.jms' to the list of packages included in trace


C:>java -jar MQ_INSTALLATION_PATH/java/lib/com.ibm.mq.traceControl.jar -i 10008 -status
Tracing enabled : true
User Directory : C:\Users\IBM_ADMIN\RTCworkspace\sandpit
Trace File Name : mqjms_10008.cl0.trc
Package Include/Exclude tree
root - Included
com - Included
ibm - Included
mq - Included
jms - Included

C:>java -jar MQ_INSTALLATION_PATH/java/lib/com.ibm.mq.traceControl.jar -i 10008 -ip com.acme.banana -ep com.acme.banana.split -ip com.acme.banana.shake
Adding 'com.acme.banana' to the list of packages included in trace
Adding 'com.acme.banana.shake' to the list of packages included in trace
Adding 'com.acme.banana.split' to the list of packages excluded from trace

C:>java -jar MQ_INSTALLATION_PATH/java/lib/com.ibm.mq.traceControl.jar -i 10008 -status
Tracing enabled : true User Directory : C:\Users\IBM_ADMIN\RTCworkspace\sandpit
Trace File Name : mqjms_10008.cl0.trc
Package Include/Exclude tree
root - Included
com - Included
acme - Included
banana - Included
shake - Included
split - Excluded
ibm - Included
mq - Included
jms - Included


The package inclusion-exclusion tree

The tracing mechanism for IBM MQ classes for Java and IBM MQ classes for JMS tracks the inclusion and exclusion of packages by means of a tree structure, starting from a root node. In the tree structure each node represents one element of a package name, identified by the package name element and containing a trace status which can be either Included or Excluded. For example the package com.ibm.mq would be represented by three nodes identified by the strings com, ibm, and mq.

Initially, the tree usually contains entries to include most packages, but the header and pcf packages are excluded as they generate a lot of noise. So the initial tree will look something like this 

root - Included
com - Included
ibm - Included
mq - Included
headers - Excluded
pcf - Excluded

When the trace facility is determining whether to include or exclude a package, it matches leading portions of the package name to the nodes in the tree as far as possible and takes the status of the last matched node. At the initial state of the tree, the packages com.ibm.msg.client and com.ibm.mq.jms would be included, as the last nodes in the tree that matches them (com->ibm and com->ibm->mq respectively) are marked as Included. Conversely, the package com.ibm.headers.internal would be excluded as the last matching node in the tree (com->ibm->mq->headers) is marked as Excluded.

As further changes are made to the tree by using the com.ibm.mq.TraceControl.jar, it is important to remember that inclusion or exclusion only affects a package and child packages. So, given the initial state that is shown previously, specifying -ep com.ibm.mq.jms, would update the tree to look like this: 

root - Included
com - Included
ibm - Included
mq - Included
headers - Excluded
jms - Excluded
pcf - Excluded

This update would exclude packages com.ibm.mq.jms, and com.ibm.mq.jms.internal, without affecting packages outside the com.ibm.mq.jms.* hierarchy.

If -ip com.ibm.mq.jms.admin is specified next, the tree would look like this: 

root - Included
com - Included
ibm - Included
mq - Included
headers - Excluded
jms - Excluded
admin - Included
pcf - Excluded

This update would still exclude packages com.ibm.mq.jms, com.ibm.mq.jms.internal, but now the packages com.ibm.mq.jms.admin, and com.ibm.mq.jms.admin.internal are included in trace.


Connect remotely

We can connect remotely only if the process was started with a JMX agent that is enabled for remote connection, and that uses the -Dcom.sun.management.jmxremote.port=port_number system setting.

After you have started with this system setting, we can run the executable JAR file with the options -h host_name -p port_number in place of the -i identifier option, where host_name is the name of the host we want to connect to and port_number is the name of the port to be used.

Note: We must ensure that you take appropriate steps to minimize security risks by enabling TLS for the connection. See the Oracle documentation on JMX for further details https://www.oracle.com.


Limitations

The following limitations exist:

  • For non-IBM JVMs, the tool must be started with tools.jar added to its class path. The command that is on these platforms is : 
    java -cp MQ_INSTALL_DIR/java/lib/com.ibm.mq.traceControl.jar;JAVA_HOME/lib/tools/jar com.ibm.msg.client.commonservices.trace.TraceController
  • Local attach is controlled by user ID. The tool must be run under the same ID as the process that is to be controlled.

Parent topic: Use trace