Benchmark tool

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

Build the benchmark tool

Java

# 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

Python

# 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

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

Python

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

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

Python

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

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

Python

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

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

Python

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

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

Python

aerospike-sdk-benchmark \
    --hosts localhost:3000 \
    --namespace test \
    --keys 10000 \
    --value-size 10240 \
    --threads 4 \
    --duration 60

Interpreting latency output

Sample output:

================================================================================
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 →

Enable Metrics

Monitor production performance.

Metrics →