Troubleshooting Notes and Sametime

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 post is intended to be a practical top-down overview for administrators investigating problems with deployed Notes and Sametime applications.

Tracing is debug information written to the platform’s log file. For performance reasons, tracing is not enabled by default; it is normally enabled after a problem has been encountered. ┬á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 Notes and Sametime applications use JSR47 logging. Because such tracing uses JSR47, you can follow a consistent approach to debugging most problems. A simple snippet on JSR47 tracing is below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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.

IBM support may ask you to enable trace for a particular plugin. For example, the request may be stated 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”.

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

Tracing may be also enabled statically – meaning the trace level will persist after the client restarts. Because dynamic tracing ends when the client is restarted, static tracing is helpful when the client is expected to be restarted (such as provisioning or installation problems) or when the problem may not occur for some time. 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.

Application users and administrators can be pro-active in problem solving using the following steps.

  1. 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.
  2. 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.
  3. 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.