Skip to main content
This quickstart guide will help you run your first load test with Chainbench. You’ll learn how to test individual RPC methods and use pre-configured profiles.
You’ll need a blockchain RPC endpoint URL to test. You can use a public endpoint or provision one from Chainstack.

​
Your first benchmark

1

Choose your testing approach

Chainbench offers two ways to run load tests:
  • Single method testing - Test a specific RPC method like eth_blockNumber
  • Profile-based testing - Use pre-configured profiles with multiple weighted methods
For this quickstart, we’ll start with a single method test.
2

Run your first test

Test the eth_blockNumber method with a quick 1-minute load test:
chainbench start eth_blockNumber \
  --users 50 \
  --workers 2 \
  --test-time 1m \
  --target https://your-node-url \
  --headless \
  --autoquit
This command:
  • Tests the eth_blockNumber method
  • Simulates 50 concurrent users
  • Uses 2 worker processes
  • Runs for 1 minute
  • Operates in headless mode (no web UI)
  • Automatically quits when finished
Replace https://your-node-url with your actual blockchain node endpoint URL.
3

Review the results

After the test completes, results are saved to the ./results directory:
results/
└── eth_blockNumber/
    └── 2024-03-04_10-30-15/
        ├── stats.csv           # Request/response statistics
        ├── stats_history.csv   # Time-series metrics
        ├── failures.csv        # Failed requests
        └── exceptions.csv      # Exception details
Key metrics include:
  • Request rates (requests per second)
  • Response times (min, max, median, 95th percentile)
  • Failure rates and error types
  • Time-series data for visualization
4

Try web UI mode (optional)

For real-time monitoring, run without the --headless flag:
chainbench start eth_blockNumber \
  --users 50 \
  --workers 2 \
  --target https://your-node-url
Open your browser to http://localhost:8089 and you’ll see the Locust web interface where you can:
  • Start/stop tests manually
  • Adjust user count in real-time
  • View live charts and statistics
  • Download results in various formats

​
Understanding test parameters

​
Essential Parameters

​
--target
string
required
The blockchain node RPC endpoint URL to test.Example: https://ethereum-mainnet-rpc.allthatnode.com
​
--users
integer
default:"100"
Number of concurrent simulated users making requests.
​
--workers
integer
default:"8"
Number of worker processes to distribute the load.
​
--test-time
string
default:"5m"
Duration of the test. Accepts formats like 30s, 5m, 1h, 12h.

​
Mode Flags

​
--headless
boolean
Run without the web UI for automated/remote testing.
​
--autoquit
boolean
Automatically exit when the test completes (useful with --headless).

​
Exploring profiles

Instead of testing single methods, use pre-configured profiles that test multiple methods with realistic weights: 
chainbench start --profile ethereum.general \
  --users 100 \
  --workers 4 \
  --test-time 1m \
  --target https://eth-node-url \
  --headless \
  --autoquit

​
Testing single methods

List all available RPC methods: 
chainbench list methods
Test any specific method: 
chainbench start eth_getBalance \
  --users 25 \
  --test-time 30s \
  --target https://your-node-url \
  --headless \
  --autoquit

​
Common use cases

​
Testing nodes with limited history

For nodes running in snap sync or other modes with limited block history: 
chainbench start --profile ethereum.general \
  --users 50 \
  --test-time 1h \
  --target https://node-url \
  --headless \
  --autoquit \
  --use-latest-blocks \
  --size S
The --use-latest-blocks flag ensures test data uses only recent blocks that the node has available.

​
Batch request testing

Test how your node handles batch JSON-RPC requests: 
chainbench start --profile evm.light \
  --users 50 \
  --test-time 5m \
  --target https://node-url \
  --headless \
  --autoquit \
  --batch \
  --batch-size 10

​
Discovering supported methods

Before testing, discover which methods your endpoint supports: 
chainbench discover https://your-node-url --clients geth,erigon

​
Running on a remote server

For long-running tests on remote servers, use nohup: 
nohup chainbench start --profile ethereum.general \
  --users 100 \
  --workers 4 \
  --test-time 12h \
  --target https://node-url \
  --headless \
  --autoquit &
Results will be saved to the results directory even if you disconnect.

​
Test data sizes

Chainbench generates test data by fetching real blockchain data. The --size flag controls how many blocks are used:
SizeBlocksUse Case
XS10Quick tests, development
S100Default, general testing
M1,000Extended testing
L10,000Long-running tests
XL100,000Comprehensive stress tests
Example with custom size: 
chainbench start eth_blockNumber \
  --users 50 \
  --test-time 5m \
  --target https://node-url \
  --headless \
  --autoquit \
  --size XS

​
Next steps

Core concepts

Learn about profiles, test data, and load patterns

Running tests

Detailed guide on running and configuring tests

Command reference

Complete reference for all commands and options

Custom profiles

Create custom profiles for your specific needs

Build docs developers (and LLMs) love

Get started for freeTalk to us