<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: jmx.xml 17858 2012-12-16 10:02:38Z jenspetersen $ --><book><bookinfo><productname>eXist-db – Open Source Native XML Database</productname><title>Java Management Extensions (JMX)</title><date>September 2009</date><orgname>The eXist-db Project</orgname></bookinfo><chapter><title>Java Management Extensions (JMX)</title><section><title>Intro</title><para>eXist-db provides access to various management interfaces via Java Management
                Extensions (JMX). JMX is a standard mechanism available in Java 5 and above. 
                An agent in the Java virtual
                machine exposes agent services as so-called MBeans that belong to different
                components running within the virtual machine. A JMX-compliant management
                application can then connect to the agent through the MBeans and access the available services in a
                standardized way. The standard Java installation includes a simple client, JConsole,
                which will also display the eXist-specific services. However, eXist also provides a
                command-line client for quick access to server statistics and other
                information.</para><para>Right now, eXist only exposes a limited set of read-only services. Most of them
                are only useful for debugging. This will certainly change in the future as we add
                more services. We also plan to provide write access to configuration
                properties.</para></section><section><title>Enabling the JMX agent</title><para>To enable the platform server within the host virtual machine, you need to pass a
                few Java system properties to the <filename>java</filename> executable. The
                properties are:</para><synopsis>-Dcom.sun.management.jmxremote
-Dcom.sun.management.jmxremote.port=1099
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false
</synopsis><note><para>This option makes the server publicly accessible. Please check the Oracle <ulink url="http://docs.oracle.com/javase/1.5.0/docs/guide/management/agent.html">
                    JMX documentation </ulink> for details.</para></note><para>The extension can be activated by passing a command-line parameter to the eXist
                start scripts (<filename>client.sh</filename>, <filename>startup.sh</filename> etc.)</para><variablelist spacing="normal"><varlistentry><term>-j &lt;argument&gt;, --jmx &lt;argument&gt;</term><listitem><para>set port number through which the JMX/RMI connections are
                            enabled.</para></listitem></varlistentry></variablelist><para>Some examples:</para><synopsis>bin/startup.sh -j 1099
bin\server.bat -jmx 1099
</synopsis><note><para>In the Oracle Java SE 6 and 7 platforms, the JMX agent for local monitoring is <ulink url="http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html">enabled</ulink> by default.</para></note></section><section><title>Monitoring and Management</title><section><title>Use JConsole</title><para>Once you restart eXist, you can use a JMX-compliant management console to
                    access the management interfaces. For example, you can call jconsole, which is
                    included with the JDK:</para><synopsis>jconsole localhost:1099</synopsis><para>Clicking on the <menuchoice><guibutton>MBeans</guibutton></menuchoice> tab should show some eXist-specific MBeans below the standard Java
                    MBeans in the tree component to the left.</para></section><section><title>Use JMXClient</title><para>eXist includes a simple command-line JMX client which provides a quick access
                    to some important server statistics. The application accepts the following
                    command-line parameters:</para><synopsis>java -jar start.jar org.exist.management.client.JMXClient &lt;params&gt;</synopsis><variablelist spacing="normal"><varlistentry><term>-a, --address &lt;argument&gt;</term><listitem><para>RMI address of the server.</para></listitem></varlistentry><varlistentry><term>-c, --cache</term><listitem><para>displays server statistics on cache and memory usage.</para></listitem></varlistentry><varlistentry><term>-d, --db</term><listitem><para>display general info about the db instance.</para></listitem></varlistentry><varlistentry><term>-h, --help</term><listitem><para>print help on command line options and exit.</para></listitem></varlistentry><varlistentry><term>-i, --instance &lt;argument&gt;</term><listitem><para>the ID of the database instance to connect to</para></listitem></varlistentry><varlistentry><term>-l, --locks</term><listitem><para>lock manager: display locking information on all threads currently
                                waiting for a lock on a resource or collection. Useful to debug
                                deadlocks. During normal operation, the list will usually be empty
                                (means: no blocked threads).</para></listitem></varlistentry><varlistentry><term>-m, --memory</term><listitem><para>display info on free and total memory. Can be combined with other
                                parameters.</para></listitem></varlistentry><varlistentry><term>-p, --port &lt;argument&gt;</term><listitem><para>RMI port of the server</para></listitem></varlistentry><varlistentry><term>-s, --report</term><listitem><para>Retrieves the most recent sanity/consistency check report</para></listitem></varlistentry><varlistentry><term>-w, --wait &lt;argument&gt;</term><listitem><para> while displaying server statistics: keep retrieving statistics,
                                but wait the specified number of seconds between calls.</para></listitem></varlistentry></variablelist><para>The following command should print some statistics about cache usage within
                    eXist:</para><synopsis>java -jar start.jar org.exist.management.client.JMXClient -c -w 2000</synopsis></section><section><title>JMXServlet</title><para>eXist also provides a servlet which connects to the JMX interface and returns
                    a status report for the database as XML. By default, the servlet listens
                    on</para><synopsis><ulink url="http://localhost:8080/exist/status">http://localhost:8080/exist/status</ulink></synopsis><para>For simplicity, the different JMX objects in eXist are organized into
                    categories. One or more categories can be passed to the servlet in parameter
                        <option>c</option>. The following categories are recognized:</para><variablelist><varlistentry><term>memory</term><listitem><para>current memory consumption of the Java virtual machine</para></listitem></varlistentry><varlistentry><term>instances</term><listitem><para>general information about the db instance, active db broker
                                objects etc.</para></listitem></varlistentry><varlistentry><term>disk</term><listitem><para>current hard disk usage of the database files</para></listitem></varlistentry><varlistentry><term>system</term><listitem><para>system information: eXist version ...</para></listitem></varlistentry><varlistentry><term>caches</term><listitem><para>statistics on eXist's internal caches</para></listitem></varlistentry><varlistentry><term>locking</term><listitem><para>information on collection and resource locks currently being held
                                by operations</para></listitem></varlistentry><varlistentry><term>sanity</term><listitem><para>feedback from the latest sanity check or ping request (see
                                below)</para></listitem></varlistentry><varlistentry><term>all</term><listitem><para>dumps all known JMX objects in eXist's namespace</para></listitem></varlistentry></variablelist><para>For example, to get a report on current memory usage and running instances,
                    use the following URL:</para><synopsis><ulink url="http://localhost:8080/exist/status?c=memory&amp;c=instances">http://localhost:8080/exist/status?c=memory&amp;c=instances</ulink></synopsis><para>This should return an XML document as follows:</para><programlisting language="xml">&lt;jmx:jmx xmlns:jmx="http://exist-db.org/jmx"&gt; 
    &lt;jmx:MemoryImpl name="java.lang:type=Memory"&gt; 
        &lt;jmx:HeapMemoryUsage&gt; 
            &lt;jmx:committed&gt;128647168&lt;/jmx:committed&gt; 
            &lt;jmx:init&gt;134217728&lt;/jmx:init&gt; 
            &lt;jmx:max&gt;1908932608&lt;/jmx:max&gt; 
            &lt;jmx:used&gt;34854528&lt;/jmx:used&gt; 
        &lt;/jmx:HeapMemoryUsage&gt; 
        &lt;jmx:NonHeapMemoryUsage&gt; 
            &lt;jmx:committed&gt;42008576&lt;/jmx:committed&gt; 
            &lt;jmx:init&gt;24313856&lt;/jmx:init&gt; 
            &lt;jmx:max&gt;138412032&lt;/jmx:max&gt; 
            &lt;jmx:used&gt;40648936&lt;/jmx:used&gt; 
        &lt;/jmx:NonHeapMemoryUsage&gt; 
        &lt;jmx:ObjectPendingFinalizationCount&gt;0&lt;/jmx:ObjectPendingFinalizationCount&gt; 
        &lt;jmx:Verbose&gt;false&lt;/jmx:Verbose&gt; 
    &lt;/jmx:MemoryImpl&gt; 
    &lt;jmx:Database name="org.exist.management.exist:type=Database"&gt; 
        &lt;jmx:ReservedMem&gt;671455641&lt;/jmx:ReservedMem&gt; 
        &lt;jmx:ActiveBrokers&gt;0&lt;/jmx:ActiveBrokers&gt; 
        &lt;jmx:InstanceId&gt;exist&lt;/jmx:InstanceId&gt; 
        &lt;jmx:MaxBrokers&gt;2&lt;/jmx:MaxBrokers&gt; 
        &lt;jmx:AvailableBrokers&gt;2&lt;/jmx:AvailableBrokers&gt; 
        &lt;jmx:ActiveBrokersMap/&gt; 
        &lt;jmx:CacheMem&gt;268435456&lt;/jmx:CacheMem&gt;
        &lt;jmx:CollectionCacheMem&gt;25165824&lt;/jmx:CollectionCacheMem&gt; 
    &lt;/jmx:Database&gt; 
&lt;/jmx:jmx&gt;</programlisting><section><title>Testing responsiveness using "ping"</title><para>The servlet also implements a simple "ping" operation. Ping will first try to obtain an internal
                        database broker object. If the db is under very high load or deadlocked, it will run out of broker
                        objects and ping will not be able to obtain one within a certain time. This is thus a good indication
                        that the database has become unresponsive for requests. If a broker object could be obtained, the servlet
                        will run a simple XQuery to test the availability of the XQuery engine.</para><para>To run a "ping", call the servlet with parameter <option>operation=ping</option>.
                    The operation also accepts an optional timeout parameter, <option>t=timeout-in-ms</option>, which defines
                    a timeout in milliseconds. For example, the following URL starts a ping with a timeout of 2 seconds:</para><synopsis><ulink url="http://localhost:8080/exist/status?operation=ping&amp;t=2000">http://localhost:8080/exist/status?operation=ping&amp;t=2000</ulink></synopsis><para>If the ping returns within the specified timeout, the servlet returns the attributes of the SanityReport
                    JMX bean, which will include an element &lt;jmx:Status&gt;PING_OK&lt;/jmx:Status&gt;:</para><programlisting language="xml">&lt;jmx:jmx xmlns:jmx="http://exist-db.org/jmx"&gt; 
    &lt;jmx:SanityReport name="org.exist.management.exist.tasks:type=SanityReport"&gt; 
        &lt;jmx:Status&gt;PING_OK&lt;/jmx:Status&gt; 
        &lt;jmx:LastCheckEnd/&gt; 
        &lt;jmx:LastCheckStart/&gt; 
        &lt;jmx:ActualCheckStart/&gt; 
        &lt;jmx:LastActionInfo&gt;Ping&lt;/jmx:LastActionInfo&gt; 
        &lt;jmx:PingTime&gt;39&lt;/jmx:PingTime&gt; 
        &lt;jmx:Errors/&gt; 
    &lt;/jmx:SanityReport&gt; 
    &lt;/jmx:jmx&gt;</programlisting><para>If the ping takes longer than the timeout, you'll instead find an element  &lt;jmx:error&gt; in the returned XML. 
                    In this case, additional information on running queries, memory consumption and database locks will be provided:</para><programlisting language="xml">&lt;jmx:jmx xmlns:jmx="http://exist-db.org/jmx"&gt; 
    &lt;jmx:error&gt;no response on ping after 2000ms&lt;/jmx:error&gt; 
    &lt;jmx:SanityReport name="org.exist.management.exist.tasks:type=SanityReport"&gt; 
        &lt;jmx:Status&gt;PING_WAIT&lt;/jmx:Status&gt; 
        &lt;jmx:LastCheckEnd/&gt; 
        &lt;jmx:LastCheckStart/&gt; 
        &lt;jmx:ActualCheckStart/&gt; 
        &lt;jmx:LastActionInfo&gt;Ping&lt;/jmx:LastActionInfo&gt; 
        &lt;jmx:PingTime&gt;-1&lt;/jmx:PingTime&gt; 
        &lt;jmx:Errors/&gt; 
    &lt;/jmx:SanityReport&gt;
    ...
&lt;/jmx:jmx&gt;</programlisting></section></section></section></chapter></book>