ShowTable of Contents
Overview
Often IBM support will request trace data to further investigate a problem. What is this data, how is it enabled, and how can it be used to pro-actively solve problems before contacting IBM? The
Expeditor Wiki contains detailed information related to enabling and collecting trace. For information regarding trace (log) files available and their usage, see the article
IBM Lotus Expeditor Logs-What are they good for. This article is designed to be a practical top-down overview for administrators investigating problems within deployed Expeditor applications.
What is Tracing
Tracing is additional debug information written to the platform's log files. For performance reasons, tracing is not enabled by default; it is normally enabled after a problem has been encountered. To view trace files refer to the article
Viewing the trace file.
Trace messages are added during the development of an application in anticipation of problems encountered in the field. Such messages may include configuration settings, runtime values, or output of problems encountered during the operation of an application. Most Expeditor applications use
JSR47 logging. Because tracing is normally done using JSR47, you can follow a consistent approach to debugging most Expeditor problems. A simple snippet on JSR47 tracing is below.
private final String clazz = ViewPart.class.getName(); // this Class' name
private Logger logger = Logger.getLogger(clazz); // the logger for this Class
private void foo() {
logger.entering(clazz, "foo");
try {
SECRET.charAt(1); // java.lang.StringIndexOutOfBoundsException
logger.log(Level.FINE, "The secret is " + SECRET);
} catch (java.lang.StringIndexOutOfBoundsException e) {
logger.log(Level.SEVERE,
"foo()'s SECRET did not have a character at index 1", e);
}
logger.exiting(clazz, "foo");
}
Tracing has varying levels that control the amount of data written to the trace files. In order of information, they are: CONFIG, FINE, FINER and FINEST. In the above example, the message "The secret is" will be written to the trace file if we enable trace at the FINE level. For practical reasons, it's generally accepted to simply start with the FINEST level to ensure no relevant messages are accidentally omitted.
Enabling Trace
As indicated IBM support may ask you to enable trace for a particular plugin. For example, the request may appear as "Please enable trace for com.ibm.rcp.accounts at the FINEST level". Or support may refer to the specification "com.ibm.rcp.accounts FINEST". In such a situation, what do you do?
There are two ways to enable trace, and both have their advantages and disadvantages. Once tracing has been enabled and the problem reproduced, see
IBM Lotus Expeditor Support Collecting ISA Data to easily submit trace data to support.
Dynamic Trace
The preferred manner is using dynamic tracing. Support often prefers dynamic tracing because it can be enabled just prior to reproducing a problem. By enabling trace only when needed, the amount of unnecessary information is omitted. Enabling dynamic trace can be found in the wiki article
Dynamically adjusting the log level. Additional details on using the OSGI console can also be found in
An Overview of the OSGI Console. Using the previous request from support, enabling trace in this manner can be done with the below command.
setlogrlev com.ibm.rcp.accounts FINEST
To enable trace for multiple packages, simply issue the setlogrlev command with the package and level on multiple lines (use enter at the end of each command).
Static Trace
Tracing may be also enabled statically - meaning the trace level will persist after the platform restarts. Because dynamic tracing ends when the platform is restarted, static tracing is helpful when the platform is expected to be restarted (such as provisioning or installation problems) or when the problem may not occur for some time. See the article
Configuring platform logging and tracing for details on enabling static trace. Again using support's request, update the rcpinstall.properties file with the following.
com.ibm.rcp.accounts.level=FINEST
For multiple packages, add the trace specifications on separate lines. A restart must occur after the rcpinstall.properties has been updated.
Pro-actively Enabling Trace
Application users and administrators can be pro-active in problem solving using the following steps.
- Identify a problem has occurred. This can be done either when an application dialog appears with an error message or the application simply fails to respond appropriately.
- Consult the trace file. Use the Viewing the trace file article to review the log file. Identify any suspicious entries and enable trace in the relevant area. Suspicious entries may include any message severity with WARNING or SEVERE. A stack trace (seen in the message below) is a good indication of abnormal behavior.
- Enable tracing. Below is a snippet of a WARNING message. The code encountering a "problem" is within the com.ibm.collaboration.realtime.community.internal package. Enabling trace for com.ibm.collaboration.realtime.community.internal at the FINEST level is a good start, but it is too narrow in scope. This would obtain information only for the com.ibm.collaboration.realtime.community.internal package and the problem may exist "higher" in the stack. As a general rule of thumb, expand the scope by removing one or two packages. For example, instead of com.ibm.collaboration.realtime.community.internal, use com.ibm.collaboration.realtime or com.ibm.collaboration.realtime.community. But be careful, not to go too high such as com.ibm.collaboration or com.ibm.rcp or you may receive too much logging, which is difficult to review.
Time | Severity | Message | Subsystem | Source Class.Method | Thread Id |
| 27T15:09:27.915-05:00 | WARNING | CLFRB5013W: Exception notifying listener [com.ibm.collaboration.realtime.people.internal.livenames.widgets.LiveNameResolverImpl$CommunityAdapter] of event [com.ibm.collaboration.realtime.im.community.CommunityLoginEvent]
java.lang.ArrayStoreException
at java.util.ArrayList.toArray(Unknown Source)
at com.ibm.collaboration.realtime.people.internal.livenames.widgets.LiveNameResolverJob.addCommunities(Unknown Source)
at com.ibm.collaboration.realtime.people.internal.livenames.widgets.LiveNameResolverJobMgr.consolidateExistingLiveNameResolverJob(Unknown Source)
at ...
com.lotus.sametime.awareness.AwarenessComp.processSTEvent(Unknown Source)
at com.lotus.sametime.core.comparch.STCompPart$1.processSTEvent(Unknown Source)
at com.lotus.sametime.core.comparch.MessageDispatcher.dispatch(Unknown Source)
at com.lotus.sametime.core.comparch.MessageDispatcher.flush(Unknown Source)
at com.lotus.sametime.core.comparch.MessageDispatchingThread.run(Unknown Source)
at java.lang.Thread.run(Unknown Source)
| com.ibm.collaboration.realtime.community.internal | com.ibm.collaboration.realtime.community.internal.CommunityImpl .notifyListeners | 16 |
Common Trace Specifications
Often troubleshooting is a combination of trace specifications. Below are trace specifications for general areas of the product. Assume the FINEST level to be used if not otherwise specified.
Browser
com.ibm.rcp.browser
com.ibm.rcp.ui.browser
com.ibm.rcp.ui.internal.browser
com.ibm.rcp.dombrowser
Composite Applications
com.ibm.rcp.portal
com.ibm.rcp.composite
com.ibm.rcp.ca
com.ibm.portal.app
Installation (Plugins and Features)
com.ibm.rcp.provisioning
com.ibm.rcp.installhandler
Portlets and Web Applications
com.ibm.pvc.webcontainer
com.ibm.pvc.webhttpservice
com.ibm.pvc.servlet
com.ibm.rcp.portlet
com.ibm.rcp.portletcontainer
com.ibm.rcp.portletviewer
com.ibm.rcp.webcontainer
Security and Authentication
com.ibm.rcp.accounts
com.ibm.rcp.security
Web Services
org.apache.commons
com.ibm.rcp.ws
com.ibm.pvcws