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

Principles

As an alternative to the well-known general-purpose tools like jconsole you 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 (see What is installed for IBM MQ classes for JMS and Installation directories for IBM MQ classes for Java .

Finding the process

To control a process, you must establish a JMX connection it. To control a process locally, you 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 you 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.

Enabling 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.

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 your package.

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

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.

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.

Connecting remotely

You 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, you 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 you want to connect to and port_number is the name of the port to be used.

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.