Java Management Extensions (JMX)
eXist-db provides access to various management interfaces via Java Management Extensions (JMX). 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. eXist also provides a command-line client for quick access to server statistics and other information.
Right now, eXist only exposes a limited set of read-only services. Most of them are useful for debugging purposes only.
To enable the platform server within the host virtual machine, pass the following Java system properties:
-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=1099 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false
These options makes the server publicly accessible. Please check the Oracle JMX documentation for details.
The extension can now be activated by passing a
-jmx command-line parameter to the eXist start scripts
startup.sh etc.). This parameter must be followed by the port number through which the
JMX/RMI connections are enabled. For instance:
bin/startup.sh -j 1099 bin\server.bat -jmx 1099
Use a JMX-compliant management console to access the management interfaces. For example, call JConsole, which is included with the JDK:
Clicking on the MBeans tab should show some eXist-specific MBeans below the standard Java MBeans (in the tree component to the left).
eXist includes a simple command-line JMX client which provides quick access to some important server statistics.
java -jar start.jar org.exist.management.client.JMXClient <params>
This accepts the following command-line parameters:
-a, --address <argument>
RMI address of the server.
displays server statistics on cache and memory usage.
display general info about the db instance.
print help on command line options and exit.
-i, --instance <argument>
the ID of the database instance to connect to
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).
display info on free and total memory. Can be combined with other parameters.
-p, --port <argument>
RMI port of the server
Retrieves the most recent sanity/consistency check report
-w, --wait <argument>
while displaying server statistics: keep retrieving statistics, but wait the specified number of seconds between calls.
The following command should print some statistics about cache usage within eXist:
java -jar start.jar org.exist.management.client.JMXClient -c -w 2000
eXist also provides a servlet which connects to the JMX interface and returns a status report for the database as XML. By default, this servlet listens on:
For example, to get a report on current memory usage and running instances, use the following URL:
This returns something like:
The different JMX objects in eXist are organized into categories. One or more categories can be passed to the servlet in parameter
c. The following categories are recognized:
current memory consumption of the Java virtual machine
general information about the db instance, active db broker objects etc.
current hard disk usage of the database files
system information: eXist version ...
statistics on eXist's internal caches
information on collection and resource locks currently being held by operations
feedback from the latest sanity check or ping request (see below)
dumps all known JMX objects in eXist's namespace
This 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 an 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.
To run a "ping", call the servlet with parameter
operation=ping. The operation accepts an optional timeout parameter,
For example, the following URL starts a ping with a timeout of 2 seconds:
If the ping returns within the specified timeout, the servlet returns the attributes of the SanityReport JMX bean, which will include an
If the ping takes longer than the timeout, you'll instead find an element
<jmx:error> in the returned XML. In this
case, additional information on running queries, memory consumption and database locks will be provided: