# Benchmark tool

The Developer SDK includes a benchmark tool for measuring performance and identifying bottlenecks in your configuration.

## Build the benchmark tool

-   [Java](#tab-panel-3060)
-   [Python](#tab-panel-3061)

Terminal window

```bash
# Clone the repository

git clone https://github.com/aerospike/aerospike-client-java-fluent.git

cd aerospike-client-java-fluent

# Build the benchmark tool (fat JAR with dependencies)

mvn -pl benchmarks package -DskipTests

# The runnable JAR is benchmarks/target/aerospike-benchmarks-sdk-0.0.1-jar-with-dependencies.jar
```

Terminal window

```bash
# Install from PyPI

pip install aerospike-sdk

# Or clone and install from source

git clone https://github.com/aerospike/aerospike-client-python-sdk.git

cd aerospike-client-python-sdk

pip install -e .
```

## Run default benchmarks

-   [Java](#tab-panel-3062)
-   [Python](#tab-panel-3063)

Terminal window

```bash
java -jar benchmarks/target/aerospike-benchmarks-sdk-0.0.1-jar-with-dependencies.jar \

    --hosts localhost:3000 \

    --namespace test \

    --set benchmark
```

Default configuration:

-   100,000 keys
-   50% reads, 50% writes
-   1 thread
-   100 byte values

Terminal window

```bash
aerospike-sdk-benchmark \

    --hosts localhost:3000 \

    --namespace test \

    --set benchmark
```

Default configuration:

-   100,000 keys
-   50% reads, 50% writes
-   1 thread
-   100 byte values

## CLI options reference

### Connection options

| Option | Description | Default |
| --- | --- | --- |
| `--hosts` | Comma-separated host:port list | `localhost:3000` |
| `--namespace` | Aerospike namespace | `test` |
| `--set` | Aerospike set name | `benchmark` |
| `--user` | Username for authentication | — |
| `--password` | Password for authentication | — |
| `--tls` | Enable TLS | `false` |

### Workload options

| Option | Description | Default |
| --- | --- | --- |
| `--keys` | Number of unique keys | `100000` |
| `--read-pct` | Percentage of reads (0-100) | `50` |
| `--threads` | Number of client threads | `1` |
| `--duration` | Test duration in seconds | `10` |
| `--value-size` | Value size in bytes | `100` |
| `--batch-size` | Batch operation size | `1` (disabled) |

### Behavior options

| Option | Description | Default |
| --- | --- | --- |
| `--behavior` | Behavior preset | `DEFAULT` |
| `--timeout` | Operation timeout (ms) | from Behavior |
| `--retries` | Max retry attempts | from Behavior |

## Example scenarios

### Read-heavy workload (90/10)

Simulates cache or session store patterns:

-   [Java](#tab-panel-3064)
-   [Python](#tab-panel-3065)

Terminal window

```bash
java -jar benchmarks/target/aerospike-benchmarks-sdk-0.0.1-jar-with-dependencies.jar \

    --hosts localhost:3000 \

    --namespace test \

    --keys 1000000 \

    --read-pct 90 \

    --threads 16 \

    --duration 60 \

    --behavior READ_FAST
```

Terminal window

```bash
aerospike-sdk-benchmark \

    --hosts localhost:3000 \

    --namespace test \

    --keys 1000000 \

    --read-pct 90 \

    --threads 16 \

    --duration 60 \

    --behavior READ_FAST
```

### Write-heavy workload (10/90)

Simulates logging or event ingestion:

-   [Java](#tab-panel-3066)
-   [Python](#tab-panel-3067)

Terminal window

```bash
java -jar benchmarks/target/aerospike-benchmarks-sdk-0.0.1-jar-with-dependencies.jar \

    --hosts localhost:3000 \

    --namespace test \

    --keys 1000000 \

    --read-pct 10 \

    --threads 32 \

    --duration 60 \

    --behavior DEFAULT
```

Terminal window

```bash
aerospike-sdk-benchmark \

    --hosts localhost:3000 \

    --namespace test \

    --keys 1000000 \

    --read-pct 10 \

    --threads 32 \

    --duration 60 \

    --behavior DEFAULT
```

### Batch operations

Test batch read/write performance:

-   [Java](#tab-panel-3068)
-   [Python](#tab-panel-3069)

Terminal window

```bash
java -jar benchmarks/target/aerospike-benchmarks-sdk-0.0.1-jar-with-dependencies.jar \

    --hosts localhost:3000 \

    --namespace test \

    --keys 100000 \

    --batch-size 100 \

    --threads 8 \

    --duration 60
```

Terminal window

```bash
aerospike-sdk-benchmark \

    --hosts localhost:3000 \

    --namespace test \

    --keys 100000 \

    --batch-size 100 \

    --threads 8 \

    --duration 60
```

### Large values

Test performance with larger payloads:

-   [Java](#tab-panel-3070)
-   [Python](#tab-panel-3071)

Terminal window

```bash
java -jar benchmarks/target/aerospike-benchmarks-sdk-0.0.1-jar-with-dependencies.jar \

    --hosts localhost:3000 \

    --namespace test \

    --keys 10000 \

    --value-size 10240 \

    --threads 4 \

    --duration 60
```

Terminal window

```bash
aerospike-sdk-benchmark \

    --hosts localhost:3000 \

    --namespace test \

    --keys 10000 \

    --value-size 10240 \

    --threads 4 \

    --duration 60
```

## Interpreting latency output

Sample output:

```plaintext
================================================================================

Benchmark Results (60 seconds)

================================================================================

Operations:     1,245,678

Throughput:     20,761 ops/sec

Latency (microseconds):

                 min       avg       p50       p95       p99      p999       max

  read           45       125       110       245       512      1,245     8,432

  write          52       185       165       385       845      2,156    12,567

Errors:         0 (0.00%)

================================================================================
```

### Key metrics

| Metric | Good Target | Warning Sign |
| --- | --- | --- |
| p50 (median) | <1ms | \>5ms |
| p99 | <5ms | \>20ms |
| p999 | <20ms | \>100ms |
| Error rate | 0% | \>0.1% |

### Interpreting results

-   **High p99/p999**: Indicates occasional slow operations—check GC (Java), network, or server load
-   **High error rate**: Check server logs, connection limits, or timeout settings
-   **Low throughput**: Increase threads, check batch sizes, or verify network bandwidth

## Tuning based on results

### If reads are slow

1.  Use `READ_FAST` behavior
2.  Increase connection pool size
3.  Check server memory configuration

### If writes are slow

1.  Start with `DEFAULT`, then tighten durability-related options only when required
2.  Consider async writes for non-critical data
3.  Check server disk I/O

### If p99 is high but p50 is good

1.  Check for GC pauses (Java: use `-XX:+UseG1GC`)
2.  Look for network micro-bursts
3.  Consider connection pooling settings

### If throughput plateaus

1.  Increase thread count
2.  Use batch operations
3.  Check server-side bottlenecks

## Next steps

Tune Performance

Configure Behaviors for your workload.

[Behaviors →](https://aerospike.com/docs/develop/client/sdk/concepts/behaviors)

Enable Metrics

Monitor production performance.

[Metrics →](https://aerospike.com/docs/develop/client/sdk/usage/metrics)