Enabling Java Message Service (JMS) trace for WebSphere Application Server

Resolving The Problem

Contents of this document:
Enabling trace at server startup
Enabling trace on a running server
Disabling Trace
Client Trace ( for WAS V6 and V6.1. It is not needed for WAS V7 or later.)

Enabling trace at server startup

This tracing requires a restart of the application server.

Use the administrative console to enable tracing at a server startup.
The diagnostic trace configuration settings for a server process determines the initial trace state for a server process.
The configuration settings are read at server startup and used to configure the trace service.
You can also change many of the trace service properties or settings while the server process is running.

In V8.0 and later, it is recommended to utilize basic logging and not HPEL logging. However, if HPEL logging is enabled, provide the output in text and not binary format.

- Log on to the Administrative Console.

- In the left panel, expand "Troubleshooting". Click on "Logs and Trace".

- Select the application server that is to be traced.

- On the next page click on "Diagnostic Trace".

- Select the "Configuration" tab.

- In V6.0 and V6.1, select the "Enable Log" property (This checkbox is not present in V7.0, V8.0 and later).

- Under the "Trace Output", select the "File" radio button.

- Set the "Maximum File Size" to 100 MB and increase the "Maximum Number of Historical Files" to 10.
This should be sufficient to capture the problem; however, you might need to increase the size of each file, or the number of files, if it is difficult to get a trace.
- Regarding the "Trace Output Format":
- In V6.0 and V6.1, to ensure you capture full data flows select "Advanced".
- In V7.0 and later, it is fine to use the default "Basic (Compatible)".

- Click on the "Change Log Detail Levels" under "Additional Properties" on the right side panel.
- Under the "Configuration" tab, enter the following string into the Trace Specification field:

WebSphere Application Server V9.0 (all on one line):
*=info:jmsApi=all:Messaging=all:com.ibm.mq.*=all:JMSApi=all:com.ibm.ws.cdi.jms*=all

WebSphere Application Server V8.0 and V8.5 (all on one line):
*=info:jmsApi=all:Messaging=all:com.ibm.mq.*=all:JMSApi=all

WebSphere Application Server V7.0 (all on one line):
*=info:JMSApi=all:JMSServer=all:Messaging=all:JMS_WASTraceAdapter=all:com.ibm.mq.*=all:jmsApi=all

WebSphere Application Server V6.0 and 6.1 (all on one line):
*=info:JMSServer=all:Messaging=all:JMS_WASTraceAdapter=all:com.ibm.mq.*=all:jmsApi=all

Notes regarding the trace specification:
- You may also be requested by the Support teams to gather a transaction manager and connection manager trace. If this is required then append the following string to the Trace Specification field:
For Connection Manager trace:
ConnLeakLogic=all:WAS.j2c=all
For Transaction Manager trace:
Transaction=all

- Click OK.
- Click Save to save your configuration (select Synchronize changes with Nodes option).
- Then restart the Application Server.

- Reproduce the issue.

- After the problem has been reproduced, turn off trace using the instructions shown below (section "Disabling Trace").

- Before sending the trace in to IBM support, ensure that the trace files capture the error. For example, you can check what time the problem was reproduced (by looking for an error message in the application server's SystemOut.log file, for example) and ensure that this time is covered by the trace files.

- Run the WebSphere Application Server collector tool to gather the logs and trace to send to IBM support.
WebSphere Application Server Information Center
Network Deployment (All operating systems), Version 8.0 > Troubleshooting and support > Working with troubleshooting tools
[AIX HP-UX Linux Solaris Windows]This topic applies only on the IBM i operating system.
Gathering information with the collector tool (deprecated)

- Related information:
WebSphere Application Server Information Center
Express (Distributed operating systems), Version 8.0 > Troubleshooting and support >
Using HPEL to troubleshoot applications > High Performance Extensible Logging (HPEL)
Basic mode and HPEL mode

Back to top

Enabling trace on a running server

This tracing does NOT require a restart of the application server.

Use the administrative console to enable tracing on a running server.
You can modify the trace service state that determines which components are being actively traced for a running server by using the following procedure.

In V8.0 and later, it is recommended to utilize basic logging and not HPEL logging. However, if HPEL logging is enabled, provide the output in text and not binary format.

- Log on to the Administrative Console.

- In the left panel, expand "Troubleshooting". Click on "Logs and Trace".

- Select the application server that is to be traced.

- On the next page click on "Diagnostic Trace".

- Select the "Runtime" tab. The server should be up and running for this tab to show up.

- Important: Do not select the checkbox "Save runtime changes to configuration as well", because if you do it, then the changes will become permanent.

- In V6.0 and V6.1, select the "Enable Log" property (This checkbox is not present in V7.0 and later).

- Under the "Trace Output", select the "File" radio button.

- Set the "Maximum File Size" to 100 MB and increase the "Maximum Number of Historical Files" to 10.
This should be sufficient to capture the problem; however, you might need to increase the size of each file, or the number of files, if it is difficult to get a trace.
- Regarding the "Trace Output Format":
- In V6.0 and V6.1, to ensure you capture full data flows select "Advanced".
- In V7.0, and later, it is fine to use the default "Basic (Compatible)".

- Click on the "Change Log Detail Levels" under "Additional Properties" on the right side panel.
- Under the "Configuration" tab, enter the following string into the Trace Specification field:

WebSphere Application Server V9.0 (all on one line):
*=info:jmsApi=all:Messaging=all:com.ibm.mq.*=all:JMSApi=all:com.ibm.ws.cdi.jms*=all

WebSphere Application Server V8.0 and V8.5 (all on one line):
*=info:jmsApi=all:Messaging=all:com.ibm.mq.*=all:JMSApi=all

WebSphere Application Server V7.0 (all on one line):
*=info:JMSApi=all:JMSServer=all:Messaging=all:JMS_WASTraceAdapter=all:com.ibm.mq.*=all:jmsApi=all

WebSphere Application Server V6.0 and 6.1 (all on one line):
*=info:JMSServer=all:Messaging=all:JMS_WASTraceAdapter=all:com.ibm.mq.*=all:jmsApi=all

Notes regarding the trace specification:
- You may also be requested by the Support teams to gather a transaction manager and connection manager trace. If this is required then append the following string to the Trace Specification field:
For Connection Manager trace:
ConnLeakLogic=all:WAS.j2c=all
For Transaction Manager trace:
Transaction=all

- Click OK.

- Reproduce the issue.

- After the problem has been reproduced, turn off trace using the instructions shown below (section "Disabling Trace").

- Before sending the trace in to IBM support, ensure that the trace files capture the error. For example, you can check what time the problem was reproduced (by looking for an error message in the application server's SystemOut.log file, for example) and ensure that this time is covered by the trace files.

- Run the WebSphere Application Server collector tool to gather the logs and trace to send to IBM support.
WebSphere Application Server Information Center
Network Deployment (All operating systems), Version 8.0 > Troubleshooting and support > Working with troubleshooting tools
[AIX HP-UX Linux Solaris Windows]This topic applies only on the IBM i operating system.
Gathering information with the collector tool (deprecated)
- Related information
WebSphere Application Server Information Center
Express (Distributed operating systems), Version 8.0 > Troubleshooting and support > Using HPEL to troubleshoot applications > High Performance Extensible Logging (HPEL)
Basic mode and HPEL mode

For z/OS:

Instructions to dynamically start the JMS trace on the z/OS platform.

You can use the MVS Modify (F) command to dynamically start and stop the JMS trace:
Start:
/F <server-name>,TRACEJAVA='*=info:JMSApi=all:JMSServer=all'
/F <server-name>,TRACEJAVA='Messaging=all:JMS_WASTraceAdapter=all'
/F <server-name>,TRACEJAVA='com.ibm.mq.*=all:jmsApi=all'

where <server-name> is substituted with the appropriate server name.
You are limited by the console command line length, and case is important for the TRACEJAVA parms

Stop:
f <serverName>,TRACEINIT

Back to top

Disabling Trace

Once you have captured the trace, the trace should be switched off. To switch tracing off, perform the following steps:

- Log on to the Administrative Console.

- In the left panel, expand "Troubleshooting". Click on "Logs and Trace".

- Select the application server that is to be traced.

- On the next page click on "Diagnostic Trace".

- Click on the "Change Log Detail Levels" under "Additional Properties" on the right side panel.

- Ensure that the Trace Specification field is set to the following:

*=info

- Click OK and then click Save.

- If you are not using the Runtime tracing tab, then restart the application server.

Back to top

JMS Client Trace

NOTE:
- This section is only needed for WAS V6 and V6.1 applications that are experiencing issues related to Message Selectors.
- This section is not needed for WAS V7 or later.

Sometimes it will be necessary to capture the JMS Client trace (which includes Distribution Hub, or disthub, trace) when experiencing issues related to Message Selectors.

++ To enable JMS Client trace, follow these steps:

- Expand the servers entry in the left hand tree view, and click on the Application Servers link.
- Note: The Application Servers panel will now appear, containing a list of application servers. Click on the same application server that you selected previously.
- Expand Java and Process Management (under Server Infrastructure) and click on Process Definition link

The Process Definition panel should now appear. Click on the Java Virtual Machine link. In the Generic JVM arguments field, enter the following:
-DMQJMS_TRACE_LEVEL=base

Note: This will turn on JMS Client tracing (which includes Distribution Hub, or disthub, trace).

- Click OK and save the configuration changes.
- Logoff the administrative console and restart the Application Server for which trace has been enabled.


++ Disabling the JMS Client trace, follow these steps:

- Expand the servers entry in the left hand tree view and click on the Application Servers link.

Note: The Application Servers panel will now appear, containing a list of application servers. Click on the same application server that you selected previously.

- Expand Java and Process Management (under Server Infrastructure) and click on Process Definition link

- The Process Definition panel should now appear. Click on the Java Virtual Machine link. In the Generic JVM arguments field, remove the following entry:
-DMQJMS_TRACE_LEVEL=base

- Click OK, and save the configuration changes.
- Log off the administrative console, and restart the Application Server for which trace has been enabled.

Back to top