Benchmark tool

Applies to

• Aerospike Developer SDK (Java 21+ and Python 3.11+)
• Aerospike Database 6.0 or later unless a section states otherwise

Code examples

Examples assume a connected session from Connect to Aerospike. Each usage guide lists shared imports in a tabbed block near the top of the page; snippet blocks add imports only for types not already shown. The first code block in each section includes dataset setup; later blocks in that section reuse those values. When a page includes a Complete example section, that block is fully self-contained.

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

Prerequisites

• A running Aerospike cluster for benchmark workloads
• The Developer SDK installed

Build the benchmark tool

Java

# Clone the repository
git clone https://github.com/aerospike/aerospike-client-java-sdk.git
cd aerospike-client-java-sdk

# Build the benchmark tool (fat JAR with dependencies)
mvn -pl benchmarks package -DskipTests

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

Python

The Python benchmark tool ships as part of the SDK’s source repository, not as a console script in the aerospike-sdk wheel. Clone the repo, install the SDK, and run the tool as a module from the repo root:

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

# Run from the repo root so benchmarks/ is on PYTHONPATH
python -m benchmarks.benchmark --help

Run default benchmarks

Java

java -jar benchmarks/target/aerospike-benchmarks-sdk-1.0.0-jar-with-dependencies.jar \
    --hosts localhost:3000 \
    --namespace test \
    --set benchmark

Default configuration:

• 100,000 keys
• 50% reads, 50% writes (-w RU,50)
• 1 thread
• Single 8-byte integer bin

Python

python -m benchmarks.benchmark -H localhost:3000 -n test -s benchmark

Default configuration:

• 100,000 keys
• 50% reads, 50% writes (-w RU,50)
• 32 concurrent async tasks

CLI options reference

Both tools use a legacy-style flag set (short flags, with long aliases for the Java tool). The Java and Python option names differ in places — check the table for your language.

Connection options

Java	Python	Description	Default
-h, --hosts	-H, --hosts	Seed host list. TLS uses a host:tlsname:port segment; there’s no separate --tls flag	127.0.0.1
-n, --namespace	-n	Aerospike namespace	test
-s, --set	-s	Aerospike set name	testset
-U, --user	-U	Username for authentication	—
-P, --password	-P	Password for authentication	—
-auth, --authMode	--auth-mode	Auth mode: INTERNAL, EXTERNAL, PKI	INTERNAL

Python reserves -h for --help; use -H for hosts.

Workload options

Java	Python	Description	Default
-w, --workload	-w	Workload spec: I (insert), RU,<pct> (read-update), RR,<pct> (read-replace), RMU/RMI/RMD (read-modify), TXN,r:N,w:N,v:pct	RU,50
-k, --keys	-k	Number of unique keys	100000 (Java), 100000 (Python)
-o, --objectSpec	-o	Bin spec: I (8-byte int), S:<size>, B:<size>, R:<size>:<pct> (Java); I1, S128, B1024 comma-combined (Python)	single integer bin
-b, --bins	—	Number of bins per record (Java only)	1
-z, --threads	-z, --async-tasks	Concurrent client threads (Java) or async tasks (Python)	1 (Java), 32 (Python)
—	--threads	OS threads for Python sync mode (falls back to -z)	—
-t, --transactions	-c	Stop after N transactions/operations	run until duration or forever
--duration, -duration	-d	Run for this many seconds (Java: async mode only)	run until -t/-c or forever
-B, --batchSize	--batch-size	Keys per batch command; 0/1 disables batching	0 (disabled)
-g, --throughput	—	Target transactions per second (Java only)	unlimited

Consistency and retry options (Java only)

Option	Description	Default
-r, --replica	Read replica policy: master, any, sequence, preferRack	sequence
-readModeAP	AP read consistency: one, all	one
-readModeSC	SC read consistency: session, linearize, allow_replica, allow_unavailable	session
-commitLevel	Write commit level: all, master	all
-maxRetries	Max retry attempts	write: 0, read: 2
-sendKey	Send key to server on every operation	false

TLS options (Python only)

Option	Description
--tls-ca-file	CA certificate for TLS connections
--tls-cert-file, --tls-key-file	Client cert/key for mutual TLS

Example scenarios

Read-heavy workload (90/10)

Simulates cache or session store patterns:

Java

java -jar benchmarks/target/aerospike-benchmarks-sdk-1.0.0-jar-with-dependencies.jar \
    --hosts localhost:3000 \
    --namespace test \
    --keys 1000000 \
    -w RU,90 \
    -z 16 \
    --duration 60

Python

python -m benchmarks.benchmark \
    -H localhost:3000 \
    -n test \
    -k 1000000 \
    -w RU,90 \
    -z 16 \
    -d 60

Write-heavy workload (10/90)

Simulates logging or event ingestion:

Java

java -jar benchmarks/target/aerospike-benchmarks-sdk-1.0.0-jar-with-dependencies.jar \
    --hosts localhost:3000 \
    --namespace test \
    --keys 1000000 \
    -w RU,10 \
    -z 32 \
    --duration 60

Python

python -m benchmarks.benchmark \
    -H localhost:3000 \
    -n test \
    -k 1000000 \
    -w RU,10 \
    -z 32 \
    -d 60

Batch operations

Test batch read/write performance (each command touches 100 keys):

Java

java -jar benchmarks/target/aerospike-benchmarks-sdk-1.0.0-jar-with-dependencies.jar \
    --hosts localhost:3000 \
    --namespace test \
    --keys 100000 \
    -B 100 \
    -z 8 \
    --duration 60

Python

python -m benchmarks.benchmark \
    -H localhost:3000 \
    -n test \
    -k 100000 \
    --batch-size 100 \
    -z 8 \
    -d 60

Large values

Test performance with larger payloads (10 KB byte-array bins):

Java

java -jar benchmarks/target/aerospike-benchmarks-sdk-1.0.0-jar-with-dependencies.jar \
    --hosts localhost:3000 \
    --namespace test \
    --keys 10000 \
    -o B:10240 \
    -z 4 \
    --duration 60

Python

python -m benchmarks.benchmark \
    -H localhost:3000 \
    -n test \
    -k 10000 \
    -o B10240 \
    -z 4 \
    -d 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 the READ_FAST behavior preset (Python) or Behavior.DEFAULT.deriveWithChanges(...) with relaxed read consistency (Java)
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 →