Managing GraphDB through the JMX interface

GraphDB offers a number of management and control functions using Java Management Extensions (JMX). GraphDB uses this interface to provide information about its internal state and behaviour, including trend information, as well as operations for intervening in certain database activities.

After initialisation, GraphDB will register a number of JMX MBeans for each repository, each providing a different set of information and functions for specific features. The JMX endpoint is configured using special system properties when starting the Java virtual machine (JVM) in which GraphDB is running. For example, the following command line parameters set the JMX server endpoint to listen on port 8089, without an authentication and a secure socket layer:

-Dcom.sun.management.jmxremote.port=8089
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false

If using GraphDB with Tomcat, then these parameters must be passed to Tomcat's JVM by setting either the JAVA_OPTS or CATALINA_OPTS environment variable, e.g.

set JAVA_OPTS="-Dcom.sun.management.jmxremote.port=8089
    -Dcom.sun.management.jmxremote.authenticate=false
    -Dcom.sun.management.jmxremote.ssl=false"

For some Linux distributions, you can also edit the file /etc/default/tomcat6 and set JAVA_OPTS there.

Once GraphDB is loaded, use any compliant JMX client, e.g. jconsole that is part of the Java development kit, to access the JMX interface on the configured port.

Cache/index statistics

Statistics are kept for the main index data structures and include information such as: cache hits/misses, file reads/writes, etc. This information can be used to fine tune GraphDB-SE's memory configuration and can be useful for 'debugging' certain situations, such as understanding why load performance changes over time or with particular data sets.

For each index, there will be a CollectionStatistics MBean published, which shows the cache and file I/O values updated in real-time:

The following information is displayed for each MBean/index:

The following operations are available:

Ideally, the system should be configured to keep the number of cache misses to a minimum. If the ratio of hits to misses is low, then consider increasing the memory available to the index (if other factors permit this).

Page swaps tend to occur much more often during large scale data loading. Page discards occur more frequently during query evaluation.

Query monitoring and termination

Information about executing queries (or more accurately query result iterators) is also available. These statistics are provided through a SailIterationMonitor MBean, with one for each repository instance. Each bean instance is named after the storage directory of the repository it relates to.

The SailIterationMonitor Mbean has a single attribute TrackRecords, which is an array of objects with the following attributes:

The collection of these objects grows for each executing/executed query, however older objects in the CLOSED state expire and are removed from the collection as the query result iterators are garbage collected.

There is a single operation available with this MBean:

This operation allows an administrator to request that a query terminates early. The operation is called requestStop and requires the trackId of the query that is to be stopped. If this operation is invoked on a running query, the isRequestedToStop flag is set to true and the next call to hasNext() will return false.

Terminating a transaction

It is possible to contrive situations where committing an update transaction can take an excessive amount of time, e.g. if committing a 'chain' of many thousands of statements using some transitive property - the inferencer will attempt to materialise all possible combinations leading to hundreds of millions of inferred statements. In such a situation, it is possible to force a commit operation to abort and rollback to the state the database had before the commit was attempted.

The following MBean is used:

This MBean has no attributes and only a single operation: