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é <[email protected]> Authored: Fri Dec 20 21:19:48 2013 +0100 Committer: Jean-Baptiste Onofré <[email protected]> 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
