svn commit: r1070509 - in /karaf/branches/karaf-2.2.x/manual/src/main/webapp/developers-guide: developer-commands.conf index.conf

[jb...@apache.org]

Author: jbonofre
Date: Mon Feb 14 14:41:32 2011
New Revision: 1070509

URL: http://svn.apache.org/viewvc?rev=1070509&view=rev
Log:
[KARAF-435] Add diagnostic and developer commands documentation.

Added:
    karaf/branches/karaf-2.2.x/manual/src/main/webapp/developers-guide/developer-commands.conf
Modified:
    karaf/branches/karaf-2.2.x/manual/src/main/webapp/developers-guide/index.conf

Added: karaf/branches/karaf-2.2.x/manual/src/main/webapp/developers-guide/developer-commands.conf
URL: http://svn.apache.org/viewvc/karaf/branches/karaf-2.2.x/manual/src/main/webapp/developers-guide/developer-commands.conf?rev=1070509&view=auto
==============================================================================
--- karaf/branches/karaf-2.2.x/manual/src/main/webapp/developers-guide/developer-commands.conf (added)
+++ karaf/branches/karaf-2.2.x/manual/src/main/webapp/developers-guide/developer-commands.conf Mon Feb 14 14:41:32 2011
@@ -0,0 +1,153 @@
+
+
+h1. Developer commands
+
+Karaf provides a set of commands dedicated to the developer.
+
+It allows you to get detailed information about the Karaf instance and the applications running into.
+
+h2. Diagnostic dump command
+
+Karaf provides a {{dev:create-dump}} command which creates dump containing diagnostic information. The dumps could be
+packaged in a zip archive or directly into a given directory.
+
+{code}
+karaf@root> dev:create-dump
+Diagnostic dump created.
+{code}
+
+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.
+
+h2. Dynamic import
+
+The {{dev:dynamic-import}} command allows you to enable or disable the dynamic import of a given bundle:
+
+{code}
+karaf@root> dev:dynamic-import 41
+Enabling dynamic imports on bundle org.apache.karaf.shell.config [41]
+{code}
+
+h2. OSGi framework
+
+The {{dev:framework}} command shows you the current OSGi framework in use, and enable debug on the OSGi framework.
+
+{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
+
+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
+{code}
+
+h2. 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:
+
+{code}
+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
+{code}
+
+h2. Karaf restart
+
+The {{dev:restart}} command allows you to restart the running Karaf instance:
+
+{code}
+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>
+{code}
+
+h2. Bundle tree
+
+The {{dev:show-tree}} command show the tree of bundles based on the wiring information. You give the bundle ID and the
+command will display a tree of bundles used with the bundle 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]
+{code}
+
+h2. Watch and update bundle
+
+The {{dev:watch}} watches and updates bundle. It's especially helpful in development mode.
+
+It allows you to configure a set of URLs that will be monitored. All bundles location matching the given URL will be
+automatically updated. It avoids to manually update the bundles or even copy the bundle to the system folder.
+
+Note that only maven based URLs and maven SNAPSHOTs will actually be updated automtically, so if you do:
+
+{code}
+karaf@root> dev:watch *
+{code}
+
+it will actually monitor all bundles that have a location matching mvn:* that have '-SNAPSHOT' in their URL.

Modified: karaf/branches/karaf-2.2.x/manual/src/main/webapp/developers-guide/index.conf
URL: http://svn.apache.org/viewvc/karaf/branches/karaf-2.2.x/manual/src/main/webapp/developers-guide/index.conf?rev=1070509&r1=1070508&r2=1070509&view=diff
==============================================================================
--- karaf/branches/karaf-2.2.x/manual/src/main/webapp/developers-guide/index.conf (original)
+++ karaf/branches/karaf-2.2.x/manual/src/main/webapp/developers-guide/index.conf Mon Feb 14 14:41:32 2011
@@ -6,6 +6,7 @@ h1. Developers Guide
 * [Security Framework|security-framework]
 * [Using the features-maven-plugin|features-maven-plugin]
 * [Troubleshooting, Debugging, Profiling, and Monitoring|debugging]
+* [Developer Commands|developer-commands]
 * [Programmatically connect to the console|connect-console]
 * [Writing integration tests|writing-tests]
 * [Creating bundles|creating-bundles]