Metrics

The Aerospike Java client implements the standard client-side metrics system. For a comprehensive overview of the available metrics please see the Client Metrics documentation.

This page focuses on the Java-specific details for configuring and accessing these metrics.

Configuring Metrics Collection

The Java client collects a standard set of essential metrics by default. You can enable more detailed “extended” metrics, which include latency histograms and transaction-level details.

The Java client offers two ways to enable extended metrics: via Dynamic Client Configuration or programmatically. The preferred method is using Dynamic Client Configuration, as it allows operators to enable detailed metrics for diagnostics without requiring an application restart or code change.

Using Dynamic Client Configuration (preferred)

Metrics can be enabled and configured dynamically if your application is set up for Dynamic Client Configuration. This allows operators to manage metrics collection without code changes or application restarts. See the Dynamic Client Configuration Quickstart for details on how to get started.

Note

You can update the metrics policy dynamically using Dynamic Client Configuration. However, be aware that changes to the metrics configuration (such as enabling/disabling extended metrics, changing labels, or adjusting reporting intervals) may affect your ability to compare new metrics data with previously collected metrics. For consistent analysis, ensure that configuration changes are tracked and considered when interpreting historical trends.

Programmatic configuration

You can also enable extended metrics directly in your application code using a MetricsPolicy.

To enable extended metrics programmatically, create a MetricsPolicy and pass it to the client:

// Define a policy to enable extended metrics
MetricsPolicy mp = new MetricsPolicy();
mp.reportDir = "/var/log/metrics";
mp.interval = 60;  // Write a snapshot every 60 seconds.

// Enable extended metrics collection
client.enableMetrics(mp);

You can disable the collection of extended metrics at any time:

// Disable extended metrics collection
client.disableMetrics();

Accessing metrics

There are two primary ways to access metrics from the Java client:

1. On-demand snapshot: you can get a snapshot of the currently collected metrics at any time using getClusterStats():

   ClusterStats cs = client.getClusterStats();
   System.out.println(cs);

   If extended metrics are enabled, the ClusterStats object is enriched with the additional detailed statistics. Standard metrics available via this method include threadsInUse and recoverQueueSize.

2. Metrics log file: when a MetricsPolicy with a reportDir is active, the client will periodically write a snapshot of the collected metrics to a log file. The format of this log is described in the main Client Metrics documentation.

Setting client identification labels

You can add labels to your client instance to distinguish its metrics from those of other applications. These labels are configured on the ClientPolicy and apply to all metrics generated by that client.

// Example: Set an App ID and custom labels for all metrics from this client
ClientPolicy policy = new ClientPolicy();
policy.appId = "recommendation-engine";
policy.labels.put("owner", "data-science-team");

AerospikeClient client = new AerospikeClient(policy, new Host("..."));

MetricsPolicy configuration

The MetricsPolicy object has the following fields to control how metrics are collected and reported:

• listener: Handles metrics notification events. The default implementation writes to a file, but this can be overridden to send metrics to other systems like OpenTelemetry.
• reportDir: Directory for the metrics log files.
• reportSizeLimit: A soft limit for the log file size in bytes. When this limit is exceeded, a new file is created. A value of 0 means the file size is unbounded.
• interval: The number of cluster tend iterations (which occur every second by default) between writing metrics snapshots to the log.
• latencyColumns: The number of buckets to use in latency histograms.
• latencyShift: A power-of-2 multiplier that defines the range of each latency bucket.

You can update metrics policy dynamically. However, be aware that changes to the ‘configuration’ could compromise your ability to compare new data with previously collected metrics.