Metrics

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

This page describes how to configure and access these metrics for the Aerospike Java client.

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.

You can enable extended metrics programmatically, or using Dynamic Client Configuration.

Using Dynamic Client Configuration (preferred)

The Aerospike Java client 9.1.0 or later is required for Dynamic Client Configuration.

You can enable and configure metrics dynamically if your application is set up for Dynamic Client Configuration, which allows operators to manage metrics collection without code changes or application restarts. See the Dynamic Client Configuration Quickstart for details about how to get started.

You can update the metrics policy dynamically using Dynamic Client Configuration. However, changes to the metrics configuration such as enabling or 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:

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.
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";

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

MetricsPolicy mp = new MetricsPolicy();
mp.labels =  new HashMap<>();
mp.labels.put("owner", "data-science-team");

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

`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.