A benchmarking toolkit designed for benchmarking Bitcoin Core, using hyperfine as the underlying benchmarking engine.
- Run single or multiple benchmarks defined in YAML configuration files
- Support for parameterized benchmarks with multiple variable combinations
- Configurable benchmark environment variables
- Integration with CI/PR workflows via run ID tracking
- Command wrapping support (e.g.,
tasksetfor CPU pinning) - System performance tuning and monitoring
- Patch management and updating
- Object storage integration for benchmark artifacts
- AssumeUTXO snapshot management
- Store benchmark results in PostgreSQL for analysis
- Rust 1.84.1 or later
- hyperfine >= v1.19.0
- Guix (for building Bitcoin Core)
- PostgreSQL (optional)
- sudo access for database operations
cargo install --path .The project includes an .envrc.example file that shows all required environment variables. If you use direnv, you can copy this to .envrc and modify it. Otherwise, ensure these variables are set in your environment.
Key environment variables:
# Benchkit Database Configuration
export PGHOST=127.0.0.1
export PGPORT=5432
export PGDATABASE=benchmarks
export PGUSER=benchkit
export PGPASSWORD=benchpass
# Guix Build Caching Configuration
export SOURCES_PATH=$HOME/.local/state/guix-builds/depends-sources-cache/
export BASE_CACHE=$HOME/.local/state/guix-builds/depends-base-cache/
export SDK_PATH=$HOME/.local/state/guix-builds/macos-sdks/
# Object Storage (optional)
export KEY_ID=<your_id>
export SECRET_ACCESS_KEY=<your_password>
# Logging
export RUST_LOG=info# Build bitcoind binaries for specified commits
benchkit build# Run all benchmarks from config
benchkit run --out-dir ./out
# Run a specific benchmark
benchkit run --name "benchmark-name" --out-dir ./out# Check current system performance settings
benchkit system check
# Tune system for benchmarking (requires sudo)
benchkit system tune
# Reset system settings to default
benchkit system reset# Download snapshot for specific network
benchkit snapshot download [mainnet|signet]# Test the benchcoin patches apply cleanly to all refs
benchkit patch test
# Fetch latest benchkit patches from github
benchkit patch update# Initialize a Postgres database for benchkit
benchkit db init
# Test database connection
benchkit db test
# Delete database and user (interactive)
benchkit db deletehome_dir: $HOME/.local/state/benchkit
bin_dir: $HOME/.local/state/benchkit/binaries
patch_dir: $HOME/.local/state/benchkit/patches
snapshot_dir: $HOME/.local/state/benchkit/snapshots
database:
host: localhost
port: 5432
database: benchmarks
user: benchkit
password: benchcoinglobal:
hyperfine:
warmup: 1
runs: 5
export_json: results.json
shell: /bin/bash
show_output: false
wrapper: "taskset -c 1-14"
source: $HOME/src/core/bitcoin
commits: ["62bd1960fdf", "e932c6168b5"]
tmp_data_dir: /tmp/benchkit
host: x86_64-linux-gnu
benchmarks:
- name: "assumeutxo signet test sync"
network: signet
connect: 127.0.0.1:39333
hyperfine:
command: "bitcoind -dbcache={dbcache} -stopatheight=160001"
parameter_lists:
- var: dbcache
values: ["450", "32000"]The following scripts can be customized in the scripts/ directory:
setup.sh: Initial setup before benchmarkingprepare.sh: Preparation before each benchmark runconclude.sh: Cleanup after each benchmark runcleanup.sh: Final cleanup after all benchmarks
- If running against a local Bitcoin Core, it's generally easier to configure
the "seed" node with custom
-portand-rpcportsettings, and then connect to it from the benchcoin node using-connect=<host>:<port>.
Contributions are welcome! Please ensure your code:
- Updates documentation as needed
- Follows the project's code style
This project is licensed under the MIT License - see the LICENSE file for details.