Trace information in the Java codebase

The trace mechanism provided and used by WebSphere MQ Everyplace has the following features:

Generating trace information

Tracing in the Java codebase is performed using the com.ibm.mqe.MQeTrace class. All calls to com.ibm.mqe.MQeTrace.trace() methods pass the following information:

Classes shipped in WebSphere MQ Everyplace generate lots of trace information using these methods, such that the trace point numbers are all negative. We recommend that programs using this trace mechanism use positive numbers, or zero.

Several bit-fields are reserved for user applications, for example, the MQeTrace.GROUP_MASK_USER_DEFINED bits-fields. For convenience, MQeTrace.GROUP_USER_DEFINED_1 maps to one such bit, for example:

	MQeTrace.trace(this, (short) 1, MQeTrace.GROUP_ERROR | 
									MQeTrace.GROUP_USER_DEFINED_1, thingToLog );
 

This statement implements a logical AND operation on the GROUP_ERROR and GROUP_USER_DEFINED_1, maintaining the run-time filter with the MQeTrace class. If the result is non-zero, then the corresponding method on the MQeTraceHandler interface class is called, if a handler has been set.

There are several variants of the MQeTrace.trace() method, including methods that trace different numbers of parameters with the trace point.

Capturing trace information

WebSphere MQ Everyplace does not automatically capture the trace information provided by the MQeTrace.trace() methods. The solution programmer must capture the trace messages. We strongly recommend that your solution includes a mechanism to allow the capture of WebSphere MQ Everyplace trace events, as this output may be requested by the IBM service teams when investigating any problems reported.

To capture WebSphere MQ Everyplace trace information, you need to ensure that

The required trace handler must implement the MQeTraceHandler interface. WebSphere MQ Everyplace ships with several trace handlers, used for different purposes:

MQeTraceToReadable
This renders trace information to a printstream in a readable format.

MQeTraceToBinaryFile
This collects trace information into a file, or sequence of files.

MQeTraceFromBinaryFile
You can use this to render this binary information file format into readable text.

MQeTraceToBinaryMidp
Collects binary trace information when running inside a MIDP java environment.
 	// Allocate a trace instance, so our handler 
	//isn't garbage collected when its' on.
       	 myMQeTrace = new MQeTrace();		
			
        	// Allocate a trace handler
        	// This one puts trace output to stdout by default.
        	MQeTraceHandler handler = (MQeTraceHandler) 
											new com.ibm.mqe.trace.MQeTraceToReadable();
			
        	// Set this handler as the one MQe uses.
        	MQeTrace.setHandler(handler);
		
        	// Set the filter so we collect those 
			//pieces of trace we are interrested in.
        	// In this case, collect all the default trace information.
       	MQeTrace.setFilter(MQeTrace.GROUP_MASK_DEFAULT);
 
	  	...
 
	  	// To end trace set the filter to zero and the handler to null
	  	MQeTrace.setFilter(0);
        	MQeTrace.setHandler(null);	
 

This example shows the creation of a trace handler, MQeTraceToReadable in this case, and setting of the filter to capture the default trace informaton. This can result in lots of information being captured. You can use a more restrictive filter to capture only a subset of the data. For example, collecting errors, warnings, and user-coded trace points might be more appropriate:

MQeTrace.GROUP_ERROR | MQeTrace.GROUP_WARNING | MQeTrace.GROUP_MASK_USER_DEFINED

Notes:

  1. The IBM Service team may ask you to use the MQeTrace.GROUP_MASK_ALL value when diagnosing a problem.

  2. When using the MQeTraceToBinaryMidp tracehandler, you require an additional step to recover the trace. The MIDP tracehandler either stores the trace in a record store or in memory. Once trace has finished, call sendDataToUrl() to recover this binary data. By default, this sends the data to a servlet. For more information, refer to the examples.trace.MQeTraceServlet section of the WebSphere MQ Everyplace Java Programming Reference.

Writing your own trace handler

Solution providers may wish to write their own trace handlers, to

The trace handlers in the product populate a series of MQeTracePointGroup objects with a collection of MQeTracePoint objects. The groups are added to the MQeTraceRenderer, and the MQeTraceRenderer is used to map from the trace point number passed on the MQeTrace.trace() methods, to a readable string.

The separation of the readable string from the trace point number allows the code to collect just the number, and separate the information collection stage from the stage that renders to readable strings.

Where possible, the trace handlers supplied also gather stack trace information when a java.lang.throwable is passed as a parameter to the MQeTrace.trace() method.

You can implement the trace handler interface, and intercept trace information from your application and the WebSphere MQ Everyplace system classes. For examples of this, refer to the following classes in the WebSphere MQ Everyplace Java Programming Reference:

You can add trace points to existing trace point groups, or to your own trace point groups. You can add these to the base MQeTraceRenderer, and use them in conjunction with the existing trace handlers. For an example of this, please refer to the MQeTrace class section of the WebSphere MQ Everyplace Java Programming Reference.

Trace points generated from WebSphere MQ Everyplace

All of the WebSphere MQ Everyplace trace points use negative trace point numbers. They are provided to facilitate problem diagnosis for the IBM Service team, when investigating a reported problem on the Websphere MQ Everyplace product.

Each trace point may change its meaning, value, and order in respect of other trace points between versions of the WebSphere MQ Everyplace classes. A trace point used in one version of WebSphere MQ Everyplace might never be issued in another. For this reason, we strongly recommend that solutions do not use a trace point as a trigger for application logic.

When rendering trace point information to a readable format, maintain a consistent version between all of the WebSphere MQ Everyplace classes. Failure to do so might result in misleading information being written to the trace output.



© IBM Corporation 2002. All Rights Reserved