Tracing the IBM MQ resource adapter

The ResourceAdapter object encapsulates the global properties of the IBM MQ resource adapter. To enable trace of the IBM MQ resource adapter, properties need to be defined in the ResourceAdapter object.

The ResourceAdapter object has two sets of properties:

• Properties associated with diagnostic tracing
• Properties associated with the connection pool managed by the resource adapter

The way you define these properties depends on the administration interfaces provided by the application server. Table 1 lists the properties of the ResourceAdapter object that are associated with diagnostic tracing.

Name of property	Type	Default value	Description
traceEnabled	String	false	A flag to enable or disable diagnostic tracing. If the value is false, tracing is turned off.
traceLevel	String	3	The level of detail in a diagnostic trace. The value can be in the range 0, which produces no trace, to 10, which provides the most detail. See Table 2 for a description of each level. If trace is enabled, traceLevel should be set to the value 10, unless otherwise specified by IBM Support.
logWriterEnabled	String	true	A flag to enable or disable the sending of a diagnostic trace to a LogWriter object provided by the application server. If the value is true, the trace is sent to a LogWriter object. If the value is false, any LogWriter object provided by the application server is not used.

Table 2 describes the levels of detail for diagnostic tracing.

Level number	Level of detail
0	No trace.
1	The trace contains error messages.
3	The trace contains error and warning messages.
6	The trace contains error, warning, and information messages.
8	The trace contains error, warning, and information messages, and entry and exit information for methods.
9	The trace contains error, warning, and information messages, entry and exit information for methods, and diagnostic data.
10	The trace contains all trace information.

Note: Any level that is not included in this table is equivalent to the next lowest level. For example, specifying a trace level of 4 is equivalent to specifying a trace level of 3. However, the levels that are not included might be used in future releases of the IBM MQ resource adapter, so it is better to avoid using these levels.

If diagnostic tracing is turned off, error and warning messages are written to the system error stream. If diagnostic tracing is turned on, error messages are written to the system error stream and to the trace destination, but warning messages are written only to the trace destination. However, the trace contains warning messages only if the trace level is 3 or higher. By default, the trace destination is the current working directory, but if the logWriterEnabled property is set, the trace is sent to the application server.

In general, the ResourceAdapter object requires no administration. However, to enable diagnostic tracing on UNIX and Linux systems for example, we can set the following properties:

traceEnabled:    true
traceLevel:      10

These properties have no effect if the resource adapter has not been started, which is the case, for example, when applications using IBM MQ resources are running only in the client container. In this situation, we can set the properties for diagnostic tracing as Java virtual machine (JVM) system properties. We can set the properties by using the -D flag on the java command, as in the following example:

java ... -DtraceEnabled=true -DtraceLevel=10

Hints and tips

You do not need to define all the properties of the ResourceAdapter object. Any properties that remain unspecified take their default values.

In a managed environment, it is better not to mix the two ways of specifying properties. If you do mix them, the JVM system properties take precedence over the properties of the ResourceAdapter object.

When using WebSphere Application Server traditional Version 9.0 with the IBM MQ Version 9.0 resource adapter, as the Java EE Dependency Injection is now a common Java EE paradigm, the standard trace string should be updated to include com.ibm.ws.cdi.jms*=all. This means that the full string is:

*=info:jmsApi=all:Messaging=all:com.ibm.mq.*=all:JMSApi=all:com.ibm.ws.cdi.jms*=all

For more information about using trace with WebSphere Application Server traditional, see the technote Enable Java Message Service (JMS) trace for WebSphere Application Server. Parent topic: Use trace