Updated Branches: refs/heads/master 56739bd09 -> 40810dee0
[KARAF-2511] Review and update the developer commands page of the developers guide Project: http://git-wip-us.apache.org/repos/asf/karaf/repo Commit: http://git-wip-us.apache.org/repos/asf/karaf/commit/b8d6e0ec Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/b8d6e0ec Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/b8d6e0ec Branch: refs/heads/master Commit: b8d6e0ec0d35d8af36dc2088704f5cd055c3a440 Parents: 56739bd Author: Jean-Baptiste Onofré <[email protected]> Authored: Mon Dec 23 19:00:42 2013 +0100 Committer: Jean-Baptiste Onofré <[email protected]> Committed: Mon Dec 23 19:00:42 2013 +0100 ---------------------------------------------------------------------- .../developers-guide/developer-commands.conf | 267 ++++++++++++------- 1 file changed, 172 insertions(+), 95 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/karaf/blob/b8d6e0ec/manual/src/main/webapp/developers-guide/developer-commands.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/developers-guide/developer-commands.conf b/manual/src/main/webapp/developers-guide/developer-commands.conf index 6e161da..14ae266 100644 --- a/manual/src/main/webapp/developers-guide/developer-commands.conf +++ b/manual/src/main/webapp/developers-guide/developer-commands.conf @@ -1,106 +1,175 @@ h1. Developer commands -Karaf provides a set of commands specific for developer use. +As you can see in the users guide, Apache Karaf is an enterprise ready OSGi container. -They allow for getting detailed information about the Karaf instances and the applications running in them. +It's also a container designed to simplify the life for developers and administrators to get details about the +running container. -h2. Diagnostic dump command +h2. Dump -Karaf provides a {{dev:create-dump}} command which creates a dump file containing diagnostic information. The dumps -could be packaged in a zip archive (default) or directly into a given directory. +If you encounter issues like performance degradations, weird behaviour, it could be helpful to have a kind of snapshot +about the current activity of the container. + +The {{dev:dump-create}} command creates a dump file containing: + +* the {{bundles.txt}} file contains the list of all OSGi bundles, with id, symbolic name, version, current status +* the {{environment.txt}} file contains details about Apache Karaf, OSGi framework, Operating System, JVM, system + properties, threads count, classes loaded +* the {{features.txt}} file contains the list of Apache Karaf features repositories, features with version, current + status, and bundles provided. +* the {{threads.txt}} file contains a thread dump, with all threads, waiting status, etc. +* the {{log}} folder contains the {{data/log}} folder, with all log files. + +By default, the {{dev:dump-create}} command creates a zip file in the {{KARAF_BASE}} folder, with the timestamp of the +dump creation: {code} -karaf@root> dev:create-dump +karaf@root()> dev:dump-create Diagnostic dump created. {code} -The previous command generates a zip archive in the KARAF_HOME (by default the name is the generation timestamp). +We can see the file generated in the {{KARAF_BASE}} folder: -The following dumps are available in the zip archive: -* {{features.txt}} provides an overview of the feature repositoroes, the installed features and bundles -* {{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. +{code} +$ cd /opt/apache-karaf-3.0.0 +$ ls -lh *.zip +-rw-r--r-- 1 user group 11K Dec 23 16:08 2013-12-23_160858.zip +{code} +You can specify the file name of the zip archive: -These dumps are very helpful when you would like to take a snapshot of a current Karaf running instance. +{code} +karaf@root()> dev:dump-create mydump.zip +Diagnostic dump created. +{code} +Instead of a zip archive, you can create the dump (exploded) in a directory using the {{-d}} ({{--directory}}) option: + +{code} +karaf@root()> dev:dump-create -d /tmp/mydump +Diagnostic dump created. +{code} + +h2. Diagnostic + +It's not always easy for the developers to understand why a bundle is not active. + +It could be because the Activator failed, the Blueprint container start failed, etc. + +The {{bundle:diag}} command gives you details about a bundle is not active: + +{code} +karaf@root()> bundle:diag +Apache ServiceMix :: Bundles :: avro-ipc (81) +--------------------------------------------- +Status: Installed +Unsatisfied Requirements: +[81.0] osgi.wiring.package; (&(osgi.wiring.package=javax.servlet)(version>=2.5.0)(!(version>=3.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=javax.servlet.http)(version>=2.5.0)(!(version>=3.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro)(version>=1.7.0)(!(version>=2.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.data)(version>=1.7.0)(!(version>=2.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.file)(version>=1.7.0)(!(version>=2.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.generic)(version>=1.7.0)(!(version>=2.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.io)(version>=1.7.0)(!(version>=2.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.reflect)(version>=1.7.0)(!(version>=2.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.specific)(version>=1.7.0)(!(version>=2.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.util)(version>=1.7.0)(!(version>=2.0.0))) +[81.0] osgi.wiring.package; (osgi.wiring.package=org.apache.velocity) +[81.0] osgi.wiring.package; (osgi.wiring.package=org.apache.velocity.app) +[81.0] osgi.wiring.package; (osgi.wiring.package=org.apache.velocity.context) +[81.0] osgi.wiring.package; (osgi.wiring.package=org.apache.velocity.exception) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.bootstrap)(version>=3.4.0)(!(version>=4.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.buffer)(version>=3.4.0)(!(version>=4.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.channel)(version>=3.4.0)(!(version>=4.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.channel.group)(version>=3.4.0)(!(version>=4.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.channel.socket.nio)(version>=3.4.0)(!(version>=4.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.handler.codec.frame)(version>=3.4.0)(!(version>=4.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.handler.codec.oneone)(version>=3.4.0)(!(version>=4.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.handler.execution)(version>=3.4.0)(!(version>=4.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.jetty)(version>=6.1.0)(!(version>=7.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.jetty.bio)(version>=6.1.0)(!(version>=7.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.jetty.nio)(version>=6.1.0)(!(version>=7.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.jetty.servlet)(version>=6.1.0)(!(version>=7.0.0))) +[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.resource)(version>=6.1.0)(!(version>=7.0.0))) +{code} h2. Dynamic import The {{bundle:dynamic-import}} command allows you to enable or disable the dynamic import of a given bundle: {code} -karaf@root> bundle:dynamic-import 41 -Enabling dynamic imports on bundle org.apache.karaf.shell.config [41] +karaf@root()> bundle:dynamic-import 77 +Enabling dynamic imports on bundle org.apache.karaf.config.core [77] {code} -h2. OSGi framework +The purpose of dynamic import is to allow a bundle to be wired up to packages that may not be knwon about in advance. +When a class is requested, if it cannot be solved via the bundle's existing imports, the dynamic import allows other +bundles to be considered for a wiring import to be added. -The {{system:framework}} command allows to display the current OSGi framework in use, and enable / disable debugging inside the OSGi framework. +The {{bundle:dynamic-import}} command allows or doesn't allow this behaviour. -{code} -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 +h2. OSGi framework -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 +The {{system:framework}} command allows to display the current OSGi framework in use, and enable/disable debugging inside the OSGi framework. -Restart Karaf now to disable Felix debug logging +{code} +karaf@root()> system:framework +Current OSGi framework is felix +karaf@root()> system:framework -debug +Enabling debug for OSGi framework (felix) +karaf@root()> system:framework -nodebug +Disabling debug for OSGi framework (felix) {code} -h2. Print stack trace +h2. Stack traces printout -The {{shell:stack-traces-print}} command prints the full stack trace in the console when the execution of a command +The {{shell:stack-traces-print}} command prints the full stack trace 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: +You can enable or disable this behaviour by passing true (to enable) or false (to disable) on the command on the fly: {code} -karaf@root> shell:stack-traces-print -karaf@root> bundles:start -Error executing command bundles:start: argument ids is required -CommandException: Argument ids is required - at DefaultActionPreparator.prepare(DefaultActionPreparator.java:284) - at AbstractCommand.execute(AbstractCommand.java:34) +karaf@root()> stack-traces-print +Printing of stacktraces set to true +karaf@root()> bundle:start +java.lang.RuntimeException: Access to system bundle 0 denied. You can override with -f + at org.apache.karaf.bundle.command.BundlesCommand.assertNoSystemBundles(BundlesCommand.java:57) + at org.apache.karaf.bundle.command.BundlesCommand.doExecute(BundlesCommand.java:48) + at org.apache.karaf.bundle.command.BundlesCommandWithConfirmation.doExecute(BundlesCommandWithConfirmation.java:41) + at org.apache.karaf.shell.console.AbstractAction.execute(AbstractAction.java:33) + at org.apache.karaf.shell.console.OsgiCommandSupport.execute(OsgiCommandSupport.java:39) + at org.apache.karaf.shell.commands.basic.AbstractCommand.execute(AbstractCommand.java:33) + at sun.reflect.GeneratedMethodAccessor30.invoke(Unknown Source) + at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) + at java.lang.reflect.Method.invoke(Method.java:601) + at org.apache.aries.proxy.impl.ProxyHandler$1.invoke(ProxyHandler.java:54) + at org.apache.aries.proxy.impl.ProxyHandler.invoke(ProxyHandler.java:119) + at org.apache.karaf.shell.console.commands.$BlueprintCommand14083304.execute(Unknown Source) + at sun.reflect.GeneratedMethodAccessor30.invoke(Unknown Source) + at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) + at java.lang.reflect.Method.invoke(Method.java:601) + at org.apache.aries.proxy.impl.ProxyHandler$1.invoke(ProxyHandler.java:54) + at org.apache.aries.proxy.impl.ProxyHandler.invoke(ProxyHandler.java:119) + at org.apache.karaf.shell.console.commands.$BlueprintCommand14083304.execute(Unknown Source) 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.Closure.executeCmd(Closure.java:477) + at org.apache.felix.gogo.runtime.Closure.executeStatement(Closure.java:403) 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> shell:stack-traces-print false -karaf@root> bundles:start -Error executing command bundles:start: argument ids is required -{code} - -h2. Karaf restart - -The {{system:shutdown}} -r command allows you to restart the running Karaf instance: - -{code} -karaf@root> system:shutdown -r -karaf@root> - __ __ ____ - / //_/____ __________ _/ __/ - / ,< / __ `/ ___/ __ `/ /_ - / /| |/ /_/ / / / /_/ / __/ - /_/ |_|\__,_/_/ \__,_/_/ - - Apache Karaf (2.99.99-SNAPSHOT) - -Hit '<tab>' for a list of available commands -and '[cmd] --help' for help on a specific command. -Hit '<ctrl-d>' or 'system:shutdown' to shutdown Karaf. - -karaf@root> + at org.apache.felix.gogo.runtime.CommandSessionImpl.execute(CommandSessionImpl.java:89) + at org.apache.karaf.shell.console.impl.jline.ConsoleImpl$DelegateSession.execute(ConsoleImpl.java:497) + at org.apache.karaf.shell.console.impl.jline.ConsoleImpl.run(ConsoleImpl.java:198) + at java.lang.Thread.run(Thread.java:722) + at org.apache.karaf.shell.console.impl.jline.ConsoleFactoryService$3.doRun(ConsoleFactoryService.java:118) + at org.apache.karaf.shell.console.impl.jline.ConsoleFactoryService$3$1.run(ConsoleFactoryService.java:109) + at java.security.AccessController.doPrivileged(Native Method) + at org.apache.karaf.jaas.modules.JaasHelper.doAs(JaasHelper.java:47) + at org.apache.karaf.shell.console.impl.jline.ConsoleFactoryService$3.run(ConsoleFactoryService.java:107) +karaf@root()> stack-traces-print false +Printing of stacktraces set to false +karaf@root()> bundle:start +Error executing command: Access to system bundle 0 denied. You can override with -f {code} h2. Bundle tree @@ -109,42 +178,50 @@ The {{bundle:tree-show}} command shows the bundle dependency tree based on the w ID. {code} -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] +karaf@root()> bundle:tree-show 40 +Bundle org.ops4j.pax.url.wrap [40] is currently ACTIVE + +org.ops4j.pax.url.wrap [40] ++- org.ops4j.base.util.property [14] ++- org.ops4j.pax.url.commons [49] +| +- org.ops4j.base.util.property [14] +| +- org.ops4j.pax.logging.pax-logging-api [23] +| +- org.ops4j.pax.swissbox.property [31] +| | +- org.ops4j.base.util.property [14] +| | +- org.ops4j.base.lang [41] +| +- org.apache.felix.configadmin [43] +| | +- org.ops4j.pax.logging.pax-logging-api [23] +| +- org.ops4j.base.lang [41] ++- org.ops4j.pax.logging.pax-logging-api [23] ++- org.ops4j.pax.swissbox.bnd [25] +| +- biz.aQute.bndlib [30] +| | +- org.apache.servicemix.bundles.junit [36] +| +- org.ops4j.pax.logging.pax-logging-api [23] +| +- org.ops4j.base.lang [41] ++- org.apache.felix.configadmin [43] ++- org.ops4j.base.net [29] +| +- org.ops4j.base.monitors [37] +| +- org.ops4j.base.lang [41] ++- org.ops4j.base.lang [41] {code} -h2. Watching and updating bundle +h2. Watch + +The {{bundle:watch}} command enables watching the local Maven repository for updates on bundles. +If the bundle file changes on the Maven repository, Apache Karaf will automatically update the bundle. -The {{bundle:watch}} watches the local maven repository and updates changed bundles. It's especially helpful in development mode. +The {{bundle:watch}} allows you to configure a set of URLs to monitore. All bundles bundles whose location matches the +given URL will be automatically updated. It avoids needing to manually update the bundles or even copy the bundle to the +system folder. -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. It avoids needing to manually update the bundles or even copy the bundle to the system folder. +{warning} +Only Maven based URLs and Maven SNAPSHOTs will actually be updated automatically. +{warning} -Note that only Maven based URLs and Maven SNAPSHOTs will actually be updated automatically, so if you do: +The following command: {code} karaf@root> dev:watch * {code} -it will actually monitor all bundles that have a location matching mvn:* that have '-SNAPSHOT' in their URL. +will monitore all bundles that have a location matching mvn:* and having '-SNAPSHOT' in their URL.
