Using the OSGI Console in IBM Notes and Sametime

The OSGI console can assist with development investigation and troubleshooting runtime errors.  It’s worth becoming familiar with a few basic commands.

When using the Expeditor or Sametime client, append -console to the client shortcut. If you are using Notes, append -RPARAMS -console. For example, here is the Notes shortcut C:\notes\notes.exe -RPARAMS -console.  After starting the client, the OSGI console will display in a separate window.  Eclipse developers may already be familiar with the OSGI console.  It’s often used during development, and the same commands listed below are applicable to Eclipse.

Notes, Sametime, or Expeditor OSGI Console
Notes, Sametime, or Expeditor OSGI Console
Eclipse OSGI Console
Eclipse OSGI Console

Commands can be input to the platform by typing the command next to the osgi> prompt. If you do not see the prompt simply press enter. For a complete list of commands available, type ? and then press enter.

If the client experiences a platform hang or crash, the following commands provide useful data to locate the cause.

  • dump heap generates a JVM heap dump which is useful when analyzing heap memory usage or memory leaks.
  • dump threads generates a javacore which can be used to analyze the stack trace of various threads; it’s recommended to run dump threads several times and compare threads over time.

See IBM Thread and Monitor Dump Analyzer for Java for analyzing output from the dump commands. The location of dump output can be redirected by editing the rcpinstall.properties file.

env.set.IBM_JAVACOREDIR=${rcp.data}/logs
env.set.IBM_COREDIR=${rcp.data}/logs
env.set.IBM_HEAPDUMPDIR=${rcp.data}/logs

When trying to isolate why a particular feature may be failing, it’s useful to start by understanding the bundle’s state.  Is it installed, is it started, or has it failed to start? The OSGI console accepts either the bundle’s symbolic name or the bundle ID.

  • ss or short status list matching bundles and their state.
  • start starts a bundle.
  • stop stops the bundle.
  • diag determines if the bundle has unresolved dependencies which could lead to runtime problems or an inability to use the bundle.
  • bundle displays a verbose set of information related to exported packages, dependencies, etc.

To enable trace output or limit the amount use the following command.

  • setlogrlev dynamically adjusts log output provide the logger ID (normally the bundle’s symbolic name) and a level (FINEST, FINER, FINE, INFO, WARNING, CONFIG).

Here are a few examples of the above commands.

setlogrlev com.ibm.rcp.ui.launcher FINEST
ss com.ibm.rcp.sync
ss sync
start com.ibm.rcp.syncui.schedule
start 606
diag com.ibm.rcp.syncui.schedule
bundle com.ibm.rcp.syncui.schedule