chainbench start

Overview

The start command initiates a load test on your specified blockchain endpoint. You can test individual RPC methods or use pre-configured profiles that combine multiple methods with realistic weight distributions. By default, results are saved to ./results/{profile_or_method_name}/{YYYY-mm-dd_HH-MM-SS}.

Basic Usage

Test a Single Method
Test with a Profile
Web UI Mode

chainbench start eth_blockNumber \
  --users 50 \
  --workers 2 \
  --test-time 12h \
  --target https://node-url \
  --headless \
  --autoquit

Tests the eth_blockNumber method with 50 concurrent users over 12 hours.

chainbench start \
  --profile bsc.general \
  --users 50 \
  --workers 2 \
  --test-time 12h \
  --target https://node-url \
  --headless \
  --autoquit

Runs a general BSC profile with multiple weighted methods.

chainbench start \
  --profile bsc.general \
  --workers 1 \
  --target https://node-url

Starts a web server on port 8089 for interactive testing. Target is required for test data initialization.

Arguments

method

string

Specify a single RPC method to test (e.g., eth_blockNumber, eth_getBalance). When provided, profile options are ignored.Use chainbench list methods to see all available methods.

Core Options

--target

string

required

The blockchain node endpoint URL to test.

--target https://eth-mainnet.example.com

Required for test data initialization. In Web UI mode, you can change the target later, but test data must be compatible with the same chain type.

-u, --users

integer

default:"100"

Target number of concurrent simulated users.

--users 50

-r, --spawn-rate

integer

default:"10"

Number of users spawned per second during ramp-up.

--spawn-rate 5

-w, --workers

integer

default:"8"

Number of worker processes to distribute the load.

--workers 4

-t, --test-time

string

default:"5m"

Duration of the test. Supports time units: s (seconds), m (minutes), h (hours).

--test-time 30m
--test-time 2h
--test-time 300s

Profile Options

-p, --profile

string

Name of the profile to run. Available profiles can be listed with chainbench list profiles.

--profile ethereum.general
--profile evm.light

Supports one level of nesting using dot notation (e.g., bsc.general → profile/bsc/general.py).

-d, --profile-dir

path

Custom directory containing profiles. Supports up to one level of subdirectories.

--profile-dir /path/to/custom/profiles

--profile-path

path

Full path to a specific profile locustfile. Overrides --profile and --profile-dir.

--profile-path /path/to/my-custom-profile.py

Load Pattern Options

-s, --shape

string

Shape of the load pattern. Available shapes: step, spike, or custom shapes.

--shape step
--shape spike

Default is ramp-up: load increases linearly at spawn-rate until target users is reached.Use chainbench list shapes to see all available shapes.

Test Data Options

--size

string

Size of test data to generate. Larger sizes result in longer generation time.

Size	Blocks
XS	10
S	100
M	1,000
L	10,000
XL	100,000

--size M

--use-latest-blocks

flag

Use the latest blocks for test data and run a background process to keep data updated.Recommended for nodes with limited history (e.g., sync modes that only keep the last 128 blocks).

--use-latest-blocks --size S

--ref-url

string

Reference node URL for retrieving test data before the test starts. If not specified, target URL is used.

--ref-url https://reference-node.example.com

--start-block

integer

Starting block number for custom block range. Must be used with --end-block.

--start-block 18000000 --end-block 18000100

Ignored if --use-latest-blocks is set.

--end-block

integer

Ending block number for custom block range. Must be greater than --start-block.

Execution Mode Options

--headless

flag

Run in headless mode without the web UI.

--headless

Useful for automated testing and remote server execution.

--autoquit

flag

Automatically quit after the test finishes.

--autoquit

Recommended for automated testing pipelines.

-H, --host

string

default:"127.0.0.1"

Host address for the Locust master.

--host 0.0.0.0

-P, --port

string

default:"5557"

Port for the Locust master.

--port 8089

Batch Request Options

--batch

flag

Send requests in batches for JSON-RPC methods.

--batch --batch-size 20

--batch-size

integer

default:"10"

Number of requests per batch. Only used when --batch is set.

--batch-size 15

Method Filtering Options

--debug-trace-methods

flag

Enable execution of tasks tagged with debug or trace.

--debug-trace-methods

By default, debug and trace methods are excluded.

-E, --exclude-tags

string

Exclude tasks with specific tags. Can be specified multiple times.

-E slow -E experimental

Monitoring Options

-m, --monitor

choice

Add monitors to collect additional metrics during the test. Can be specified multiple times.Available monitors:

sync-lag-monitor - Track node synchronization lag

-m sync-lag-monitor

Monitors currently only work in headless mode.

--notify

string

Send notifications when the test starts and finishes using ntfy.sh.

--notify my-test-topic

Notifications will be sent to https://ntfy.sh/my-test-topic.

Results Options

--results-dir

path

default:"results"

Directory where test results are saved.

--results-dir /path/to/results

--run-id

string

Custom identifier for the test run.

--run-id prod-stress-test-001

Database Export Options

--timescale

flag

Export test data to PostgreSQL with TimescaleDB extension.Requires all PG connection parameters.

--timescale \
  --pg-host localhost \
  --pg-port 5432 \
  --pg-username postgres \
  --pg-password secret

--pg-host

string

Hostname of PostgreSQL instance with TimescaleDB.

--pg-port

integer

default:"5432"

Port of PostgreSQL instance.

--pg-username

string

default:"postgres"

PostgreSQL username.

--pg-password

string

PostgreSQL password.

Logging Options

--log-level

string

default:"INFO"

Logging level for test output.

--log-level DEBUG

Common Scenarios

Quick Development Test

chainbench start eth_blockNumber \
  --users 5 \
  --workers 1 \
  --test-time 30s \
  --target https://node-url \
  --headless \
  --autoquit

Production Stress Test

chainbench start \
  --profile ethereum.general \
  --users 100 \
  --workers 8 \
  --test-time 6h \
  --target https://node-url \
  --headless \
  --autoquit \
  --size L \
  -m sync-lag-monitor

Limited History Node Test

chainbench start \
  --profile evm.light \
  --users 50 \
  --workers 4 \
  --test-time 1h \
  --target https://node-url \
  --headless \
  --autoquit \
  --use-latest-blocks \
  --size S

Batch Request Test

chainbench start eth_getBlockByNumber \
  --users 20 \
  --workers 2 \
  --test-time 15m \
  --target https://node-url \
  --headless \
  --autoquit \
  --batch \
  --batch-size 25

Remote Server Test with nohup

nohup chainbench start \
  --profile bsc.general \
  --workers 4 \
  --users 100 \
  --test-time 24h \
  --target https://node-url \
  --headless \
  --autoquit \
  --notify bsc-test-alerts &

Example Output

$ chainbench start eth_blockNumber --users 10 --workers 1 --test-time 1m \
    --target https://eth-node.example.com --headless --autoquit

Testing target endpoint: https://eth-node.example.com
Testing method: eth_blockNumber
Results will be saved to /home/user/results/eth_blockNumber/2026-03-04_10-30-15
Starting master in headless mode
Starting worker 1

Running test in headless mode

[2026-03-04 10:30:16,123] INFO/locust.main: Starting Locust 2.x.x
[2026-03-04 10:30:16,456] INFO/locust.main: Run time limit set to 60 seconds
[2026-03-04 10:31:16,789] INFO/locust.main: Time limit reached. Stopping Locust.

Quitting...

chainbench list - View all available methods, profiles, and shapes
chainbench discover - Discover available methods on an endpoint

Commands

Configuration

Overview

Basic Usage

Arguments

Core Options

Profile Options

Load Pattern Options

Test Data Options

Execution Mode Options

Batch Request Options

Method Filtering Options

Monitoring Options

Results Options

Database Export Options

Logging Options

Common Scenarios

Quick Development Test

Production Stress Test

Limited History Node Test

Batch Request Test

Remote Server Test with nohup

Example Output

Build docs developers (and LLMs) love

Commands

Configuration

​Overview

​Basic Usage

​Arguments

​Core Options

​Profile Options

​Load Pattern Options

​Test Data Options

​Execution Mode Options

​Batch Request Options

​Method Filtering Options

​Monitoring Options

​Results Options

​Database Export Options

​Logging Options

​Common Scenarios

​Quick Development Test

​Production Stress Test

​Limited History Node Test

​Batch Request Test

​Remote Server Test with nohup

​Example Output

​Related Commands

Build docs developers (and LLMs) love

Overview

Basic Usage

Arguments

Core Options

Profile Options

Load Pattern Options

Test Data Options

Execution Mode Options

Batch Request Options

Method Filtering Options

Monitoring Options

Results Options

Database Export Options

Logging Options

Common Scenarios

Quick Development Test

Production Stress Test

Limited History Node Test

Batch Request Test

Remote Server Test with nohup

Example Output

Related Commands