Troubleshooting, Debugging, Profiling, and Monitoring

Troubleshooting

Logging

Logging is easy to control through the console, with commands grouped under log shell. To learn about the available logging commands type:

karaf@root> log<tab>

log:display              log:display-exception    log:get                  log:set
karaf@root>

Typical usage is:

  1. Use log:set to dynamically change the global log level

  2. Execute the problematic operation

  3. Use log:display (or log:display-exception to display the log

Worst Case Scenario

If you end up with Karaf in a really bad state (i.e. you can not boot it anymore) or you just want to revert to a clean state quickly, you can safely remove the data directory just in the installation directory. This folder contains transient data and will be recreated if removed when you relaunch Karaf. You may also want to remove the files in the deploy folder to avoid them being automatically installed when Karaf is started the first time.

Debugging

Usually, the easiest way to debug Karaf or any application deployed onto it is to use remote debugging. Remote debugging can be easily activated by using the debug parameter on the command line.

> bin/karaf debug

or on Windows

> bin\karaf.bat debug

Another option is to set the KARAF_DEBUG environment variable to TRUE.

This can be done using the following command on Unix systems:

export KARAF_DEBUG=true

On Windows, use the following command

set KARAF_DEBUG=true

Then, you can launch Karaf using the usual way:

bin/karaf

or

bin\karaf.bat

Last, inside your IDE, connect to the remote application (the default port to connect to is 5005).

This option works fine when it is needed to debug a project deployed on top of Apache Karaf. Nevertheless, you will be blocked if you would like to debug the Karaf server itself.

In this case, you can use debugs option (s as syspend). That will cause the JVM to pause just before running main() until you attach a debugger then it will resume the execution. This way you can set your breakpoints anywhere in the code and you should hit them no matter how early in the startup they are.

bin/karaf debugs

and on Windows,

bin\karaf.bat debugs
Debugging Environment Variables
Variable Description Default

KARAF_DEBUG

Set to TRUE to enable debugging.

EXTRA_JAVA_OPTS

Java options append to JAVA_OPTS

JAVA_DEBUG_OPTS

Java options to enable debuging.

Calculated based on the OS

JAVA_DEBUG_PORT

Port used by the debugger

5005

Profiling

jVisualVM

You have to edit the etc/config.properties configuration file to add the jVisualVM package:

org.osgi.framework.bootdelegation=...,org.netbeans.lib.profiler.server

Run Karaf from the console, and you should now be able to connect using jVisualVM.

YourKit

You need a few steps to be able to profile Karaf using YourKit.

The first one is to edit the etc/config.properties configuration file and add the following property:

org.osgi.framework.bootdelegation=...,com.yourkit.*

Then, set the JAVA_OPTS environment variable:

export JAVA_OPTS='-Xmx512M -agentlib:yjpagent'

or, on Windows

set JAVA_OPTS='-Xmx512M -agentlib:yjpagent'

Run Karaf from the console, and you should now be able to connect using YourKit standalone or from your favorite IDE.

Monitoring

Karaf uses JMX for monitoring and management of all Karaf components.

The JMX connection could be:

  • local using the process id

jconsole connect

  • remote using the rmiRegistryPort property defined in etc/org.apache.karaf.management.cfg file.

Using JMX, you can have a clean overview of the running Karaf instance:

  • A overview with graphics displaying the load in terms of thread, heap/GC, etc:

jconsole overview

  • A thread overview:

jconsole threads

  • A memory heap consumption, including "Perform GC" button:

jconsole memory

  • A complete JVM summary, with all number of threads, etc:

jconsole summary

You can manage Karaf features like you are in the shell. For example, you have access to the Admin service MBean, allowing you to create, rename, destroy, change SSH port, etc. Karaf instances:

jconsole admin

You can also manage Karaf features MBean to list, install, and uninstall Karaf features:

jconsole features