Monitor client performance

Client-side performance monitoring helps you detect regressions, troubleshoot timeouts and connection issues, and correlate application behavior with cluster health. Typical signals include operation volume, error and retry rates, latency distributions, and connection pool usage, aggregated by cluster, node, or namespace when your observability stack supports those dimensions.

The Aerospike Developer SDK for Java and Python does not embed a built-in metrics collector or periodic metrics log like the classic Aerospike clients. Instead, you instrument your application around SDK calls and export measurements to the tools your team already uses (for example Prometheus, OpenTelemetry, Datadog, or structured logs). The sections below show common metric categories, example instrumentation patterns, and integration approaches. For complementary request-level detail during development, see Configure logging.

Available metrics

Standard metrics

Metric	Type	Description
aerospike.operations.total	Counter	Total operations executed
aerospike.operations.errors	Counter	Failed operations
aerospike.latency.read	Histogram	Read operation latency
aerospike.latency.write	Histogram	Write operation latency
aerospike.connections.active	Gauge	Current open connections
aerospike.connections.pool	Gauge	Connections in pool

Extended metrics

Metric	Type	Description
aerospike.batch.size	Histogram	Batch operation sizes
aerospike.retries	Counter	Operation retry count
aerospike.timeouts	Counter	Timeout events
aerospike.cluster.nodes	Gauge	Nodes in cluster

Enable metrics programmatically

Java

import com.aerospike.client.sdk.Cluster;
import com.aerospike.client.sdk.ClusterDefinition;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import io.micrometer.prometheus.PrometheusConfig;
import io.micrometer.prometheus.PrometheusMeterRegistry;

// Application-owned registry (not provided by the Aerospike JAR)
MeterRegistry registry = new PrometheusMeterRegistry(PrometheusConfig.DEFAULT);

try (Cluster cluster = new ClusterDefinition("localhost", 3000).connect()) {
    Timer.Sample sample = Timer.start(registry);
    try {
        // session.query(...).execute();  etc.
    } finally {
        sample.stop(registry.timer("aerospike.sdk.requests"));
    }
}

📖 API reference: ClusterDefinition(String,int) | ClusterDefinition.connect() | Cluster.close() | ChainableQueryBuilder.execute()

Python

import time

from aerospike_sdk import Behavior, Client, DataSet

async def main():
    async with Client("localhost:3000") as client:
        session = client.create_session(Behavior.DEFAULT)
        users = DataSet.of("test", "users")

        start = time.perf_counter()
        stream = await session.query(users.id("user-1")).execute()
        await stream.first()
        stream.close()
        duration_ms = (time.perf_counter() - start) * 1000
        print(f"aerospike.read.latency_ms={duration_ms:.2f}")

📖 API reference: Client | Client.create_session() | DataSet.of() | DataSet.id() | Behavior.DEFAULT | Session.query() | RecordStream.first() | RecordStream.close() | QueryBuilder.execute()

Prometheus integration

from prometheus_client import CollectorRegistry, generate_latest
from prometheus_client import Counter, Histogram

from aerospike_sdk import Behavior, Client, DataSet

registry = CollectorRegistry()
reads_total = Counter("aerospike_reads_total", "Read operations", registry=registry)
read_latency = Histogram("aerospike_read_latency_ms", "Read latency ms", registry=registry)

async def main():
    async with Client("localhost:3000") as client:
        session = client.create_session(Behavior.DEFAULT)
        users = DataSet.of("test", "users")
        with read_latency.time():
            stream = await session.query(users.id("user-1")).execute()
            await stream.first()
            stream.close()
            reads_total.inc()

# Expose metrics endpoint
@app.route('/metrics')
def metrics():
    return generate_latest(registry)

📖 API reference: Client | Client.create_session() | DataSet.of() | DataSet.id() | Behavior.DEFAULT | Session.query() | RecordStream.first() | RecordStream.close() | QueryBuilder.execute()

Access metrics snapshots

Get current metric values programmatically:

Java

// The preview Java client does not expose cluster.getMetrics() / MetricsSnapshot.
// Export Micrometer/Prometheus from your app or scrape logs for connection events.

📖 API reference: com.aerospike.client.sdk

Python

# The Python SDK does not expose cluster.get_metrics().
# Read metrics from your app-level registry (Prometheus/OpenTelemetry/StatsD).
print(f"Total reads: {reads_total._value.get()}")

Metrics log files

Enable periodic metrics logging to files:

Java

// No built-in periodic metrics log in the preview client; use your logging framework
// and rotate files under /var/log/... as needed (see Configure logging).

📖 API reference: com.aerospike.client.sdk

Python

import logging

logger = logging.getLogger("aerospike_app_metrics")
logger.setLevel(logging.INFO)
logger.info("aerospike.read.latency_ms=12.7")

📖 PSDK Guide: Logging

Client identification labels

Add labels to identify metrics by application or environment:

Java

// Apply labels in your metrics backend (Prometheus relabel, Datadog tags, etc.), not on ClusterDefinition.

📖 API reference: com.aerospike.client.sdk

Python

from dataclasses import dataclass

@dataclass(frozen=True)
class MetricTags:
    app: str = "my-service"
    env: str = "production"
    region: str = "us-west-2"

tags = MetricTags()
print(tags)

Integration with monitoring systems

Prometheus + Grafana

1. Export metrics via HTTP endpoint
2. Configure Prometheus to scrape your application
3. Import the Aerospike client dashboard in Grafana

Datadog

Java

import io.micrometer.datadog.DatadogConfig;
import io.micrometer.datadog.DatadogMeterRegistry;
import java.time.Clock;

DatadogMeterRegistry registry = new DatadogMeterRegistry(
    DatadogConfig.DEFAULT, Clock.SYSTEM);
// Register timers/counters around your own Aerospike calls; the SDK does not wire this for you.

📖 API reference: com.aerospike.client.sdk

Python

from datadog import statsd

from aerospike_sdk import Behavior, Client, DataSet

async def main():
    async with Client("localhost:3000") as client:
        session = client.create_session(Behavior.DEFAULT)
        users = DataSet.of("test", "users")
        stream = await session.query(users.id("user-1")).execute()
        row = await stream.first()
        stream.close()
        statsd.increment("aerospike.read.total", tags=["app:my-service"])
        statsd.gauge("aerospike.read.found", 1 if row is not None else 0)

📖 API reference: Client | Client.create_session() | DataSet.of() | DataSet.id() | Behavior.DEFAULT | Session.query() | RecordStream.first() | RecordStream.close() | QueryBuilder.execute()

Performance impact

Metrics collection has minimal overhead:

• Counter/gauge operations: ~100ns
• Histogram recording: ~500ns
• Total impact: <1% CPU overhead

For latency-critical applications, you can disable histograms:

Java

// Configure Micrometer histogram buckets on your own meters; unrelated to the Aerospike JAR.

📖 API reference: com.aerospike.client.sdk

Python

# Configure histogram behavior in your metrics backend, not on ClusterDefinition.
# Example: use a Counter-only approach in your instrumentation path.

Next steps

Configure Logging

Set up client-side logging for debugging.

Logging →

Tune Performance

Optimize client configuration with Behaviors.

Behaviors →