Metrics¶

Quick overview¶

• advanced.metrics in the configuration. All disabled by default, can be selected individually.

• some metrics are per node, others global to the session, or both.

• unlike driver 3, JMX is not provided out of the box. You need to add the dependency manually.

The driver exposes measurements of its internal behavior through a choice of three popular metrics frameworks: Dropwizard Metrics, Micrometer Metrics or MicroProfile Metrics. Application developers can select a metrics framework, which metrics are enabled, and export them to a monitoring tool.

Structure¶

There are two categories of metrics:

• session-level: the measured data is global to a Session instance. For example, connected-nodes measures the number of nodes to which we have connections.

• node-level: the data is specific to a node (and therefore there is one metric instance per node). For example, pool.open-connections measures the number of connections open to this particular node.

Metric names are path-like, dot-separated strings. The driver prefixes them with the name of the session (see session-name in the configuration), and in the case of node-level metrics, nodes followed by a textual representation of the node’s address. For example:

s0.connected-nodes => 2
s0.nodes.127_0_0_1:9042.pool.open-connections => 2
s0.nodes.127_0_0_2:9042.pool.open-connections => 1

Configuration¶

By default, all metrics are disabled. You can turn them on individually in the configuration, by adding their name to these lists:

datastax-java-driver.advanced.metrics {
  session.enabled = [ connected-nodes, cql-requests ]
  node.enabled = [ pool.open-connections, pool.in-flight ]
}

To find out which metrics are available, see the reference configuration. It contains a commented-out line for each metric, with detailed explanations on its intended usage.

If you specify a metric that doesn’t exist, it will be ignored and a warning will be logged.

The metrics section may also contain additional configuration for some specific metrics; again, see the reference configuration for more details.

datastax-java-driver.advanced.metrics {
  factory.class = MicrometerMetricsFactory
}

datastax-java-driver.advanced.metrics {
  factory.class = MicroProfileMetricsFactory
}

<dependency>
  <groupId>com.datastax.oss</groupId>
  <artifactId>java-driver-metrics-micrometer</artifactId>
  <version>${driver.version}</version>
</dependency>

<dependency>
  <groupId>com.datastax.oss</groupId>
  <artifactId>java-driver-metrics-microprofile</artifactId>
  <version>${driver.version}</version>
</dependency>

CqlSessionBuilder builder = CqlSession.builder();
builder.withMetricRegistry(myRegistryObject);
CqlSession session = builder.build();

Dropwizard:   com.codahale.metrics.MetricRegistry
Micrometer:   io.micrometer.core.instrument.MeterRegistry
MicroProfile: org.eclipse.microprofile.metrics.MetricRegistry

Export¶

The Dropwizard MetricRegistry is exposed via session.getMetrics().getRegistry(). You can retrieve it and configure a Reporter to send the metrics to a monitoring tool.

NOTE: At this time, session.getMetrics() is not available when using Micrometer or MicroProfile metrics. If you wish to use either of those metrics frameworks, it is recommended to provide a Registry implementation to the driver as described in the Metric Registry section, and follow best practices for exporting that registry to your desired reporting framework.

<dependency>
  <groupId>io.dropwizard.metrics</groupId>
  <artifactId>metrics-jmx</artifactId>
  <version>4.0.2</version>
</dependency>

MetricRegistry registry = session.getMetrics()
    .orElseThrow(() -> new IllegalStateException("Metrics are disabled"))
    .getRegistry();

JmxReporter reporter =
    JmxReporter.forRegistry(registry)
        .inDomain("com.datastax.oss.driver")
        .build();
reporter.start();

import com.codahale.metrics.jmx.JmxReporter;
import com.codahale.metrics.jmx.ObjectNameFactory;
import com.google.common.base.Splitter;
import com.google.common.base.Strings;
import javax.management.MalformedObjectNameException;
import javax.management.ObjectName;

ObjectNameFactory objectNameFactory = (type, domain, name) -> {
  StringBuilder objectName = new StringBuilder(domain).append(':');
  List<String> nameParts = Splitter.on('.').splitToList(name);
  int i = 0;
  for (String namePart : nameParts) {
    boolean isLast = (i == nameParts.size() - 1);
    String key =
        isLast ? "name" : Strings.padStart(Integer.toString(i), 2, '0');
    objectName.append(key).append('=').append(namePart);
    if (!isLast) {
      objectName.append(',');
    }
    i += 1;
  }
  try {
    return new ObjectName(objectName.toString());
  } catch (MalformedObjectNameException e) {
    throw new RuntimeException(e);
  }
};

JmxReporter reporter =
    JmxReporter.forRegistry(registry)
        .inDomain("com.datastax.oss.driver")
        .createsObjectNamesWith(objectNameFactory)
        .build();
reporter.start();