Developer's Guide

Developer commands

Karaf provides a set of commands specific for developer use.

They allow for getting detailed detailed information about the Karaf instance and the applications running in them.

Diagnostic dump command

Karaf provides a dev:create-dump command which creates a dump files containing diagnostic information. The dumps can be
packaged in a zip archive (default) or directly into a given directory.

karaf@root> dev:create-dump
Diagnostic dump created.

The previous command generates a zip archive in the KARAF_HOME (by default the name is the generation timestamp).

The following dumps are available in the zip archive:

features.txt provides an overview of the features. It means:
- the repository list
- the feature list including bundles URL
bundles.txt provides an overview of the installed bundles, with the ID and the state of each bundle.
threads.txt provides a complete threads dump. It describe all threads running in Karaf and their current state (blocked,
waiting, etc) with the associated class hierarchy.

These dumps are very helpful when you would like to take a snapshot of a current Karaf running instance.

Dynamic import

The dev:dynamic-import command allows you to enable or disable the dynamic import of a given bundle:

karaf@root> dev:dynamic-import 41
Enabling dynamic imports on bundle org.apache.karaf.shell.config [41]

OSGi framework

The dev:framework command shows you the current OSGi framework in use, and enables debugging of the underlying OSGi framework.

karaf@root> dev:framework
Current OSGi framework is Felix
karaf@root> dev:framework -debug
Enabling debug for OSGi framework (Felix)
- set felix.log.level=4 in etc/config.properties

Restart Karaf now to enable Felix debug logging
karaf@root> dev:framework -nodebug
Disabling debug for OSGi framework (Felix)
- removed felix.log.level from etc/config.properties

Restart Karaf now to disable Felix debug logging

Print stack trace

The dev:print-stack-traces command prints the full stack trace in the console when the execution of a command
throws an exception.

You can enable or disable this behavior by passing true (to enable) or false (to disable) on the command on the fly:

karaf@root> dev:print-stack-traces
karaf@root> osgi:start
Error executing command osgi:start: argument ids is required
org.apache.felix.gogo.commands.CommandException: Argument ids is required
        at org.apache.felix.gogo.commands.basic.DefaultActionPreparator.prepare(DefaultActionPreparator.java:284)
        at org.apache.felix.gogo.commands.basic.AbstractCommand.execute(AbstractCommand.java:34)
        at org.apache.felix.gogo.runtime.CommandProxy.execute(CommandProxy.java:78)
        at org.apache.felix.gogo.runtime.Closure.executeCmd(Closure.java:474)
        at org.apache.felix.gogo.runtime.Closure.executeStatement(Closure.java:400)
        at org.apache.felix.gogo.runtime.Pipe.run(Pipe.java:108)
        at org.apache.felix.gogo.runtime.Closure.execute(Closure.java:183)
        at org.apache.felix.gogo.runtime.Closure.execute(Closure.java:120)
        at org.apache.felix.gogo.runtime.CommandSessionImpl.execute(CommandSessionImpl.java:79)
        at org.apache.karaf.shell.console.jline.Console.run(Console.java:180)
        at java.lang.Thread.run(Thread.java:619)
karaf@root> dev:print-stack-traces false
karaf@root> osgi:start
Error executing command osgi:start: argument ids is required

Karaf restart

The dev:restart command allows you to restart the running Karaf instance:

karaf@root> dev:restart
karaf@root>
        __ __                  ____
       / //_/____ __________ _/ __/
      / ,<  / __ `/ ___/ __ `/ /_
     / /| |/ /_/ / /  / /_/ / __/
    /_/ |_|\__,_/_/   \__,_/_/

  Apache Karaf (2.1.99-SNAPSHOT)

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit '<ctrl-d>' or 'osgi:shutdown' to shutdown Karaf.

karaf@root>

Bundle tree

The dev:show-tree command shows the bundle dependency tree based on the wiring information of a given single bundle ID.

karaf@root> dev:show-tree 40
Bundle org.apache.karaf.diagnostic.command [40] is currently ACTIVE

org.apache.karaf.diagnostic.command [40]
+- org.apache.aries.blueprint [10]
|  +- org.apache.aries.util [8]
|  +- org.apache.felix.configadmin [5]
|  +- org.apache.aries.proxy [7]
|  |  +- org.apache.aries.util [8]
|  |  +- org.apache.servicemix.bundles.asm [9]
|  |  +- org.ops4j.pax.logging.pax-logging-api [3]
|  +- org.ops4j.pax.logging.pax-logging-api [3]
+- org.apache.karaf.shell.console [22]
|  +- org.apache.aries.blueprint [10]
|  +- org.ops4j.pax.logging.pax-logging-api [3]
|  +- org.apache.karaf.jaas.modules [13]
|     +- org.apache.aries.blueprint [10]
|     +- org.apache.felix.configadmin [5]
|     +- org.apache.karaf.jaas.config [29]
|     |  +- org.apache.aries.blueprint [10]
|     |  +- org.ops4j.pax.logging.pax-logging-api [3]
|     +- org.ops4j.pax.logging.pax-logging-api [3]
+- org.apache.karaf.diagnostic.core [23]

Watching and updating bundle

The dev:watch watches and updates bundles. It's especially helpful in development mode.

It allows you to configure a set of URLs that will be monitored. All bundles whose location matches the given URL will be
automatically updated. This avoids needing to manually update the bundles or even copy the bundles to the system folder.

Note that only Maven based URLs and Maven SNAPSHOTs will actually be updated automatically, so if you do:

karaf@root> dev:watch *

it will actually monitor all bundles that have a location matching mvn:* that have '-SNAPSHOT' in their URL.