JMX Monitoring Plugin

The JMX monitoring plugin exposes query metrics via the JMX API.

Note

The JMX monitoring plugin is an enterprise feature.

Table of Contents

Enable the Enterprise License

You can enable the Enterprise License via the CrateDB configuration file.

Enable Collecting Stats

You can enable Collecting Stats via the CrateDB configuration file.

Alternatively, run this query:

cr> SET GLOBAL "stats.enabled" = TRUE;

Enable the JMX API

To monitor CrateDB using the JMX API, you must set the following system properties before you start CrateDB:

com.sun.management.jmxremote
com.sun.management.jmxremote.port=<JMX_PORT>
com.sun.management.jmxremote.ssl=false
com.sun.management.jmxremote.authenticate=false

Here, <JMX_PORT> sets the port number of your JMX server. JMX SSL and authentication are currently not supported.

More information about the JMX monitoring properties can be found in the JMX documentation.

You can set the Java system properties with the -D option:

sh$ ./bin/crate -Dcom.sun.management.jmxremote \
...             -Dcom.sun.management.jmxremote.port=7979 \
...             -Dcom.sun.management.jmxremote.ssl=false \
...             -Dcom.sun.management.jmxremote.authenticate=false

However, the recommended way to set system properties is via the CRATE_JAVA_OPTS environment variable, like so:

sh$ export CRATE_JAVA_OPTS="$CRATE_JAVA_OPTS \
      -Dcom.sun.management.jmxremote \
      -Dcom.sun.management.jmxremote.port=7979 \
      -Dcom.sun.management.jmxremote.ssl=false \
      -Dcom.sun.management.jmxremote.authenticate=false"
sh$ ./bin/crate

If you’re using the CrateDB Debian or RPM packages, you can set this environment variable via the /etc/default/crate configuration file.

Using Docker

To enable JMX monitoring when running CrateDB in a Docker container you have to set the following additional Java system properties:

-Djava.rmi.server.hostname=<RMI_PORT>
-Dcom.sun.management.jmxremote.rmi.port=<RMI_HOSTNAME>

Here, <RMI_HOSTNAME> is the IP address or hostname of the Docker host and <RMI_PORT> is the statically assigned port of the RMI server. For convenience, <RMI_PORT> can be set to the same port the JMX server listens on.

The <RMI_HOSTNAME> and <RMI_PORT> can be used by JMX clients (e.g. JConsole or VisualVM) to connect to the JMX server.

Here’s an example Docker command:

sh> docker run -d -e CRATE_JAVA_OPTS='\
      -Dcom.sun.management.jmxremote
      -Dcom.sun.management.jmxremote.port=7979 \
      -Dcom.sun.management.jmxremote.ssl=false \
      -Dcom.sun.management.jmxremote.authenticate=false \
      -Dcom.sun.management.jmxremote.rmi.port=<RMI_HOSTNAME> \
      -Djava.rmi.server.hostname=7979' \
      -p 7979:7979 crate \
      crate -Cnetwork.host=_site_

Here, again, <RMI_HOSTNAME> is the IP address or hostname of the Docker host.

JMX Beans

QueryStats MBean

The QueryStats JMX MBean exposes query frequency and average duration in milliseconds for SELECT, UPDATE, DELETE, and INSERT queries.

Metrics can be accessed using the JMX MBean object name io.crate.monitoring:type=QueryStats and the following attributes:

Frequency:

  • SelectQueryFrequency
  • InsertQueryFrequency
  • UpdateQueryFrequency
  • DeleteQueryFrequency
  • OverallQueryFrequency

Average duration:

  • SelectQueryAverageDuration
  • InsertQueryAverageDuration
  • UpdateQueryAverageDuration
  • DeleteQueryAverageDuration
  • OverallQueryAverageDuration