You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by jb...@apache.org on 2013/12/20 21:20:39 UTC
git commit: [KARAF-2511] Review and update the tuning page of the
users guide
Updated Branches:
refs/heads/master 65c064e18 -> 619b59562
[KARAF-2511] Review and update the tuning page of the users guide
Project: http://git-wip-us.apache.org/repos/asf/karaf/repo
Commit: http://git-wip-us.apache.org/repos/asf/karaf/commit/619b5956
Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/619b5956
Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/619b5956
Branch: refs/heads/master
Commit: 619b59562612650b654e4979af4a6edb97bb9659
Parents: 65c064e
Author: Jean-Baptiste Onofré <jb...@apache.org>
Authored: Fri Dec 20 21:19:48 2013 +0100
Committer: Jean-Baptiste Onofré <jb...@apache.org>
Committed: Fri Dec 20 21:19:48 2013 +0100
----------------------------------------------------------------------
manual/src/main/webapp/users-guide/tuning.conf | 147 ++++++++++++++++++-
.../src/main/webapp/users-guide/webconsole.conf | 51 +++++--
2 files changed, 175 insertions(+), 23 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/karaf/blob/619b5956/manual/src/main/webapp/users-guide/tuning.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/users-guide/tuning.conf b/manual/src/main/webapp/users-guide/tuning.conf
index d3a6461..62095cb 100644
--- a/manual/src/main/webapp/users-guide/tuning.conf
+++ b/manual/src/main/webapp/users-guide/tuning.conf
@@ -1,14 +1,145 @@
-h1. System bundle exports
+h1. Tuning
-One important duty of the system bundle is to export some packages of the jre. In Karaf this is configured in etc/jre.properties.
+h2. Garbage Collection
-It contains a property for each supported jre like "jre-1.6=". The value is a comma separated list of all packages the system bundle should export. For most cases the defaults are fine.
+Like any Java applications, Apache Karaf uses a JVM. An important feature of the JVM is the Garbage Collector.
-h2. When to change the exported packages
+Apache Karaf default configuration is sized for small to medium needs and to work on most machine.
-Typically the exported packages have to be tuned if a bundle should replace them. So for example when installing woodstox you may want to remove the export of {{javax.xml.stream}} so the package
-exported by the woodstox bundle is the only one exporting this package.
+That's why this default configuration may appear like "small".
+
+By default, Apache Karaf uses:
+
+* {{-Xms128M}}
+* {{-Xmx512M}}
+* {{-XX:+UnlockDiagnosticVMOptions}}
+* {{-XX:+UnsyncloadClass}}
+
+On Sun/Oracle JVM:
+* the Perm size is the JVM default
+
+On IBM JVM and AIX system:
+* {{-Xverify:none}}
+* {{-Xdump:heap}}
+* {{-Xlp}}
+
+For any container, it's always difficult to predict the usage of the resources and the behaviour of the artifacts deployed.
+
+Generally speaking, a good approach for tuning is to enable {{-verbose:gc}} and use tools like VisualVM to identify the potentials
+memory leaks, and see the possible optimisation of the spaces and GC.
+
+You can find introduction about GC here: [http://www.oracle.com/webfolder/technetwork/tutorials/obe/java/gc01/index.html].
+
+h3. Java 6
+
+If you have enough resources available on the machine, a good configuration may be:
+
+* {{-server}}
+* {{-Xmx1024M}}
+* {{-XX:MaxPermSize=640M}}
+* {{-XX:+UseConcMarkSweepGC}}
+* {{-XX:+UseParNewGC}}
+* {{-XX:+CMSClassUnloadingEnabled}}
+
+It will give more resources to Apache Karaf, and avoid some perm space saturation if you do a lot of bundles refresh.
+
+See [http://www.oracle.com/technetwork/java/javase/gc-tuning-6-140523.html] for details about Java 6 tuning.
+
+h3. Java 7
+
+Java 7 introduces a new GC algorithm: the GC1.
+
+Depending of the use cases (and usage of the heap), the new GC1 algorithm can give good performance improvements:
+
+* {{-XX:+UseG1GC}}
+* {{-XX:-UseAdaptiveSizePolicy}}
+
+See [http://docs.oracle.com/javase/7/docs/technotes/guides/vm/G1.html] for details about Java 7 GC1 tuning.
+
+You can find a good article about Java 7 tuning here: [http://java-is-the-new-c.blogspot.de/2013/07/tuning-and-benchmarking-java-7s-garbage.html].
+
+h2. Threads
+
+In high loaded system, the number of threads can be very large.
+
+h3. WebContainer
+
+If you use the Apache Karaf WebContainer, the Jetty connectors create threads to handle the incoming HTTP requests.
+
+The {{etc/jetty.xml}} configuration file allows you to tune the Jetty connector.
+
+For instance, the following connector configuration:
+
+{code}
+ <Call name="addConnector">
+ <Arg>
+ <New class="org.eclipse.jetty.server.nio.SelectChannelConnector">
+ <Set name="host">
+ <Property name="jetty.host" />
+ </Set>
+ <Set name="port">
+ <Property name="jetty.port" default="8181" />
+ </Set>
+ <Set name="maxIdleTime">300000</Set>
+ <Set name="Acceptors">2</Set>
+ <Set name="statsOn">false</Set>
+ <Set name="confidentialPort">8443</Set>
+ <Set name="lowResourcesConnections">20000</Set>
+ <Set name="lowResourcesMaxIdleTime">5000</Set>
+ </New>
+ </Arg>
+ </Call>
+{code}
+
+defines the following properties:
+
+* {{maxIdleTime}} is the maximum inactivity time for a connection.
+* {{lowResourcesConnections}} defines the number of connections. If the current number of connections is greater than
+ this value, the status is "low on resources". In that case, a new connection timeout is applied: the {{lowResourceMaxIdleTime}}.
+* {{Acceptors}} defines the number of threads for incoming connections.
+
+h3. Apache Camel
+
+For instance, if you use Apache Camel inside Apache Karaf, Camel components can create a lot of threads.
+
+Apache Camel use the notion of {{threadPoolProfile}} to control the threads creation.
+
+For instance, the following Camel configuration defines a pool creation strategy:
+
+{code}
+<threadPoolProfile id="defaultThreadPoolProfile" defaultProfile="true"
+ poolSize="10" maxPoolSize="20" maxQueueSize="1000"
+ rejectedPolicy="CallerRuns"/>
+{code}
+
+See the [Apache Camel website|http://camel.apache.org] for details.
+
+h3. Apache CXF
+
+Apache CXF uses workqueues to handle server request/response.
+
+You may see a {{etc/org.apache.cxf.workqueues-default.cfg}} configuration file. It's the default configuration applied
+to all workqueues (a workqueue can be associated to a specific endpoint).
+
+On a workqueue, you can define the following properties about the threads:
+
+* {{org.apache.cxf.workqueue.default.highWaterMark}} defines the maximum number of threads.
+* {{org.apache.cxf.workqueue.default.lowWaterMark}} defines the minimum number of threads.
+* {{org.apache.cxf.workqueue.default.initialSize}} defines the initial number of threads.
+
+See the [Apache CXF website|http://cxf.apache.org] for details.
+
+h2. System packages
+
+The {{etc/jre.properties}} defines the packages directly provided by the JVM.
+
+Most of the time, the default configuration in Apache Karaf is fine and works in most of the use cases.
+
+However, some times, you may want to not use the packages provided by the JVM, but the same packages provided by a bundle.
+
+For instance, the JAXB version provided by the JVM is "old", and you want to use new JAXB bundles.
+
+In that case, you have to comment the packages in {{etc/jre.properties}} to avoid to be provided by the JVM and use the
+ones from the bundles.
-h2. Changes needed for CXF and Camel
-In Karaf versions before 2.3.x we shipped a special version of the jre.properties named jre.properties.cxf that should be copied to jre.properties when using Camel or CXF. From Karaf 2.3 on this is not necessary anymore.
http://git-wip-us.apache.org/repos/asf/karaf/blob/619b5956/manual/src/main/webapp/users-guide/webconsole.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/users-guide/webconsole.conf b/manual/src/main/webapp/users-guide/webconsole.conf
index 7ec8bf6..a97d3bc 100644
--- a/manual/src/main/webapp/users-guide/webconsole.conf
+++ b/manual/src/main/webapp/users-guide/webconsole.conf
@@ -1,27 +1,48 @@
-h1. Web console
+h1. WebConsole
-The Karaf web console provides a graphical overview of the runtime.
-You can use it to:
-* install and uninstall features
-* start, stop, install bundles
-* create child instances
-* configure Karaf
-* view logging informations
+Apache Karaf provides an optional WebConsole.
-h2. Installing the web console
+This WebConsole provides a graphical web GUI to see and manage your Apache Karaf container.
-The web console is not installed by default. To install it, run the following command from the Karaf prompt:
+You can use the WebConsole to:
+
+* manage Apache Karaf features
+* manage OSGi bundles
+* manage the instances
+* manage the confgurations
+* manage the log service
+
+The WebConsole is extensible via a plugins system. Some applications can add new pages to the WebConsole.
+For instance, Apache Karaf Cellar provides additional pages to administrate cluster groups, nodes, etc.
+
+h2. Installation
+
+To enable the Apache Karaf WebConsole, you just have to install the {{webconsole}} feature:
{code}
-root@karaf> feature:install webconsole
+karaf@root()> feature:install webconsole
{code}
-For changing the web console port number see the [HTTPService config| http].
+The {{webconsole}} feature automatically installs the {{http}} feature (see the [WebContainer section|webcontainer] for details).
+
+h2. Access
-h2. Accessing the web console
+The Apache Karaf WebConsole uses the WebContainer port number (see the [WebContainer section|webcontainer] for details)
+with the {{/system/console}} context.
-To access the console for an instance of Karaf running locally, enter the following address in your web browser:
+By default, the Apache Karaf WebContainer port number is {{8181}}.
+
+It means that the Apache Karaf WebConsole is accessible on the following URL:
[http://localhost:8181/system/console]
-Log in with the username {{karaf}} and the password {{karaf}}. If you have changed the default user or password, use the one you have configured.
+As the Apache Karaf WebConsole uses the security framework, an username and password will be prompted.
+
+You have to enter an username/password from the {{karaf}} realm. By default, you can use {{karaf}}/{{karaf}}.
+
+See the [Security section|security] for details.
+
+{warning}
+Only users with the {{admin}} role are allowed to logon on the Apache Karaf WebConsole.
+Right now, the WebConsole doesn't use RBAC system as we have for console commands, or MBeans.
+{warning}
\ No newline at end of file