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.
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 metricsMetricsPolicy mp = new MetricsPolicy();mp.reportDir = "/var/log/metrics";mp.interval = 60; // Write a snapshot every 60 seconds.
// Enable extended metrics collectionclient.enableMetrics(mp);
You can disable the collection of extended metrics at any time:
// Disable extended metrics collectionclient.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 includethreadsInUse
andrecoverQueueSize
. -
Metrics log file: when a
MetricsPolicy
with areportDir
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 clientClientPolicy 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 of0
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.