Chapter 38. Monitoring JanusGraph

38.1. Metrics in JanusGraph

JanusGraph supports Metrics. JanusGraph can measure the following:

  • The number of transactions begun, committed, and rolled back
  • The number of attempts and failures of each storage backend operation type
  • The response time distribution of each storage backend operation type

38.1.1. Configuring Metrics Collection

To enable Metrics collection, set the following in JanusGraph’s properties file:

# Required to enable Metrics in JanusGraph
metrics.enabled = true

This setting makes JanusGraph record measurements at runtime using Metrics classes like Timer, Counter, Histogram, etc. To access these measurements, one or more Metrics reporters must be configured as described in the section Section 38.2, “Configuring Metrics Reporting”.

38.1.1.1. Customizing the Default Metric Names

JanusGraph prefixes all metric names with "org.janusgraph" by default. This prefix can be set through the metrics.prefix configuration property. For example, to shorten the default "org.janusgraph" prefix to just "janusgraph":

# Optional
metrics.prefix = janusgraph

38.1.1.2. Transaction-Specific Metrics Names

Each JanusGraph transaction may optionally specify its own Metrics name prefix, overriding both the default Metrics name prefix and the metrics.prefix configuration property. For example, the prefix could be changed to the name of the frontend application that opened the JanusGraph transaction. Note that Metrics maintains a ConcurrentHashMap of metric names and their associated objects in memory, so it’s probably a good idea to keep the number of distinct metric prefixes small.

To do this, call TransactionBuilder.setMetricsPrefix(String):

JanusGraph graph = ...;
TransactionBuilder tbuilder = graph.buildTransaction();
JanusGraphTransaction tx = tbuilder.groupName("foobar").start();

38.1.1.3. Separating Metrics by Backend Store

JanusGraph combines the Metrics for its various internal storage backend handles by default. All Metrics for storage backend interactions follow the pattern "<prefix>.stores.<opname>", regardless of whether they come from the ID store, edge store, etc. When metrics.merge-basic-metrics = false is set in JanusGraph’s properties file, the "stores" string in metric names is replaced by "idStore", "edgeStore", "vertexIndexStore", or "edgeIndexStore".

38.2. Configuring Metrics Reporting

JanusGraph supports the following Metrics reporters:

Each reporter type is independent of and can coexist with the others. For example, it’s possible to configure Ganglia, JMX, and Slf4j Metrics reporters to operate simultaneously. Just set all their respective configuration keys in janusgraph.properties (and enable metrics as directed above).

38.2.1. Console Reporter

Table 38.1. Metrics Console Reporter Configuration Options

Config KeyRequired?ValueDefault

metrics.console.interval

yes

Milliseconds to wait between dumping metrics to the console

null


Example janusgraph.properties snippet that prints metrics to the console once a minute:

metrics.enabled = true
# Required; specify logging interval in milliseconds
metrics.console.interval = 60000

38.2.2. CSV File Reporter

Table 38.2. Metrics CSV Reporter Configuration Options

Config KeyRequired?ValueDefault

metrics.csv.interval

yes

Milliseconds to wait between writing CSV lines

null

metrics.csv.directory

yes

Directory in which CSV files are written (will be created if it does not exist)

null


Example janusgraph.properties snippet that writes CSV files once a minute to the directory ./foo/bar/ (relative to the process’s working directory):

metrics.enabled = true
# Required; specify logging interval in milliseconds
metrics.csv.interval = 60000
metrics.csv.directory = foo/bar

38.2.3. Ganglia Reporter

[Note]Note

Configuration of Ganglia requires an additional library that is not packaged with JanusGraph due to its LGPL licensing that conflicts with the JanusGraph’s Apache 2.0 License. To run with Ganglia monitoring, download the org.acplt:oncrpc jar from here and copy it to the JanusGraph /lib directory before starting the server.

Table 38.3. Metrics Ganglia Reporter Configuration Options

Config KeyRequired?ValueDefault

metrics.ganglia.hostname

yes

Unicast host or multicast group to which our Metrics are sent

null

metrics.ganglia.interval

yes

Milliseconds to wait between sending datagrams

null

metrics.ganglia.port

no

UDP port to which we send Metrics datagrams

8649

metrics.ganglia.addressing-mode

no

Must be "unicast" or "multicast"

unicast

metrics.ganglia.ttl

no

Multicast datagram TTL; ignore for unicast

1

metrics.ganglia.protocol-31

no

Boolean; true to use Ganglia protocol 3.1, false to use 3.0

true

metrics.ganglia.uuid

no

Host UUID to report instead of IP:hostname

null

metrics.ganglia.spoof

no

Override IP:hostname reported to Ganglia

null


Example janusgraph.properties snippet that sends unicast UDP datagrams to localhost on the default port once every 30 seconds:

metrics.enabled = true
# Required; IP or hostname string
metrics.ganglia.hostname = 127.0.0.1
# Required; specify logging interval in milliseconds
metrics.ganglia.interval = 30000

Example janusgraph.properties snippet that sends unicast UDP datagrams to a non-default destination port and which also spoofs the IP and hostname reported to Ganglia:

metrics.enabled = true
# Required; IP or hostname string
metrics.ganglia.hostname = 1.2.3.4
# Required; specify logging interval in milliseconds
metrics.ganglia.interval = 60000
# Optional
metrics.ganglia.port = 6789
metrics.ganglia.spoof = 10.0.0.1:zombo.com

38.2.4. Graphite Reporter

Table 38.4. Metrics Graphite Reporter Configuration Options

Config KeyRequired?ValueDefault

metrics.graphite.hostname

yes

IP address or hostname to which Graphite plaintext protocol data are sent

null

metrics.graphite.interval

yes

Milliseconds to wait between pushing data to Graphite

null

metrics.graphite.port

no

Port to which Graphite plaintext protocol reports are sent

2003

metrics.graphite.prefix

no

Arbitrary string prepended to all metric names sent to Graphite

null


Example janusgraph.properties snippet that sends metrics to a Graphite server on 192.168.0.1 every minute:

metrics.enabled = true
# Required; IP or hostname string
metrics.graphite.hostname = 192.168.0.1
# Required; specify logging interval in milliseconds
metrics.graphite.interval = 60000

38.2.5. JMX Reporter

Table 38.5. Metrics JMX Reporter Configuration Options

Config KeyRequired?ValueDefault

metrics.jmx.enabled

yes

Boolean

false

metrics.jmx.domain

no

Metrics will appear in this JMX domain

Metrics’s own default

metrics.jmx.agentid

no

Metrics will be reported with this JMX agent ID

Metrics’s own default


Example janusgraph.properties snippet:

metrics.enabled = true
# Required
metrics.jmx.enabled = true
# Optional; if omitted, then Metrics uses its default values
metrics.jmx.domain = foo
metrics.jmx.agentid = baz

38.2.6. Slf4j Reporter

Table 38.6. Metrics Slf4j Reporter Configuration Options

Config KeyRequired?ValueDefault

metrics.slf4j.interval

yes

Milliseconds to wait between dumping metrics to the logger

null

metrics.slf4j.logger

no

Slf4j logger name to use

"metrics"


Example janusgraph.properties snippet that logs metrics once a minute to the logger named foo:

metrics.enabled = true
# Required; specify logging interval in milliseconds
metrics.slf4j.interval = 60000
# Optional; uses Metrics default when unset
metrics.slf4j.logger = foo

38.2.7. User-Provided/Custom Reporter

In case the Metrics reporter configuration options listed above are insufficient, JanusGraph provides a utility method to access the single MetricRegistry instance which holds all of its measurements.

com.codahale.metrics.MetricRegistry janusgraphRegistry =
    org.janusgraph.util.stats.MetricManager.INSTANCE.getRegistry();

Code that accesses janusgraphRegistry this way can then attach non-standard reporter types or standard reporter types with exotic configurations to janusgraphRegistry. This approach is also useful if the surrounding application already has a framework for Metrics reporter configuration, or if the application needs multiple differently-configured instances of one of JanusGraph’s supported reporter types. For instance, one could use this approach to setup multiple unicast Graphite reporters whereas JanusGraph’s properties configuration is limited to just one Graphite reporter.