|
| 1 | +# loadgen |
| 2 | + |
| 3 | +Standalone load generator for ev-node stress testing. Talks to a [spamoor-daemon](https://github.com/ethpandaops/spamoor) sidecar via HTTP API. |
| 4 | + |
| 5 | +## Architecture |
| 6 | + |
| 7 | +```text |
| 8 | +ev-loadgen (this binary) --> spamoor-daemon --> ev-reth RPC |
| 9 | + | | |
| 10 | + reads matrix JSON manages wallets, |
| 11 | + creates/polls spammers signs & sends txs |
| 12 | +``` |
| 13 | + |
| 14 | +- **spamoor-daemon** needs: a funded private key + ev-reth RPC URL |
| 15 | +- **ev-loadgen** needs: spamoor-daemon API URL + matrix JSON files |
| 16 | + |
| 17 | +## Modes |
| 18 | + |
| 19 | +### Daemon mode (`start`) |
| 20 | + |
| 21 | +Runs a continuous scheduler with regular and burst workloads. Designed for long-running deployments. |
| 22 | + |
| 23 | +```sh |
| 24 | +ev-loadgen start --spamoor-url=http://localhost:8080 |
| 25 | +``` |
| 26 | + |
| 27 | +Regular workloads fire immediately at startup, then repeat at `--interval`. Per-run tx count = `tx-per-day / (24h / interval)`, overriding each matrix entry's `BENCH_COUNT_PER_SPAMMER`. |
| 28 | + |
| 29 | +Bursts are randomly spaced throughout a rolling 24h window. Set `--burst-per-day=0` (the default) to disable bursts entirely. |
| 30 | + |
| 31 | +#### start flags |
| 32 | + |
| 33 | +| Flag | Env | Default | Description | |
| 34 | +|------|-----|---------|-------------| |
| 35 | +| `--tx-per-day` | `BENCH_TX_PER_DAY` | `1000000` | sustained txs/day | |
| 36 | +| `--interval` | `BENCH_INTERVAL` | `1h` | regular workload frequency | |
| 37 | +| `--burst-tx-count` | `BENCH_BURST_TX_COUNT` | `500000` | txs per burst | |
| 38 | +| `--burst-per-day` | `BENCH_BURST_PER_DAY` | `0` | bursts per day, randomly spaced (0 = disabled) | |
| 39 | +| `--regular-matrix` | `BENCH_REGULAR_MATRIX` | `/home/ev/baseline.json` | path to regular matrix JSON | |
| 40 | +| `--burst-matrix` | `BENCH_BURST_MATRIX` | `/home/ev/burst.json` | path to burst matrix JSON | |
| 41 | + |
| 42 | +### CLI mode (one-shot commands) |
| 43 | + |
| 44 | +#### `run` — execute a matrix file |
| 45 | + |
| 46 | +Runs all entries from a matrix JSON file with probability filtering and sync waiting, then exits. |
| 47 | + |
| 48 | +```sh |
| 49 | +ev-loadgen run matrices/baseline.json --spamoor-url=http://localhost:8080 |
| 50 | +``` |
| 51 | + |
| 52 | +#### `burst` — trigger a single burst |
| 53 | + |
| 54 | +Fires one burst workload immediately and exits. |
| 55 | + |
| 56 | +```sh |
| 57 | +ev-loadgen burst --spamoor-url=http://localhost:8080 |
| 58 | +``` |
| 59 | + |
| 60 | +| Flag | Env | Default | Description | |
| 61 | +|------|-----|---------|-------------| |
| 62 | +| `--tx-count` | `BENCH_BURST_TX_COUNT` | `500000` | total transactions for the burst | |
| 63 | +| `--burst-matrix` | `BENCH_BURST_MATRIX` | `/home/ev/burst.json` | path to burst matrix JSON | |
| 64 | + |
| 65 | +### Global flag |
| 66 | + |
| 67 | +`--spamoor-url` (or `BENCH_SPAMOOR_URL` env, default `http://spamoor-daemon:8080`) |
| 68 | + |
| 69 | +## Quick Start |
| 70 | + |
| 71 | +### 1. Start spamoor-daemon |
| 72 | + |
| 73 | +```sh |
| 74 | +docker run -d --name spamoor -p 8080:8080 \ |
| 75 | + ethpandaops/spamoor:latest /app/spamoor-daemon \ |
| 76 | + --privkey=<funded-private-key> \ |
| 77 | + --rpchost=http://<ev-reth-host>:8545 \ |
| 78 | + --port=8080 --startup-delay=0 |
| 79 | +``` |
| 80 | + |
| 81 | +### 2. Run loadgen |
| 82 | + |
| 83 | +```sh |
| 84 | +# build |
| 85 | +cd apps/loadgen && go build -o ev-loadgen . |
| 86 | + |
| 87 | +# one-shot matrix run |
| 88 | +./ev-loadgen run matrices/baseline.json --spamoor-url=http://localhost:8080 |
| 89 | + |
| 90 | +# continuous daemon (~1M tx/day, no bursts) |
| 91 | +./ev-loadgen start --spamoor-url=http://localhost:8080 |
| 92 | + |
| 93 | +# continuous daemon with bursts |
| 94 | +./ev-loadgen start \ |
| 95 | + --spamoor-url=http://localhost:8080 \ |
| 96 | + --tx-per-day=500000 \ |
| 97 | + --interval=30m \ |
| 98 | + --burst-tx-count=100000 \ |
| 99 | + --burst-per-day=4 |
| 100 | +``` |
| 101 | + |
| 102 | +### Docker Compose |
| 103 | + |
| 104 | +Spins up both spamoor-daemon and loadgen together: |
| 105 | + |
| 106 | +```sh |
| 107 | +export BENCH_PRIVATE_KEY=<funded-private-key> |
| 108 | +export BENCH_ETH_RPC_URL=http://<ev-reth-host>:8545 |
| 109 | +docker compose -f apps/loadgen/docker-compose.yml up |
| 110 | +``` |
| 111 | + |
| 112 | +## Matrix Format |
| 113 | + |
| 114 | +Each entry specifies a spamoor scenario, tx counts, and optional probability: |
| 115 | + |
| 116 | +```json |
| 117 | +{ |
| 118 | + "entries": [ |
| 119 | + { |
| 120 | + "test_name": "EOATransfer", |
| 121 | + "scenario": "eoatx", |
| 122 | + "timeout": "15m", |
| 123 | + "env": { |
| 124 | + "BENCH_NUM_SPAMMERS": "4", |
| 125 | + "BENCH_COUNT_PER_SPAMMER": "10500", |
| 126 | + "BENCH_THROUGHPUT": "200", |
| 127 | + "BENCH_MAX_PENDING": "50000", |
| 128 | + "BENCH_MAX_WALLETS": "200", |
| 129 | + "BENCH_BASE_FEE": "500", |
| 130 | + "BENCH_TIP_FEE": "50" |
| 131 | + } |
| 132 | + } |
| 133 | + ] |
| 134 | +} |
| 135 | +``` |
| 136 | + |
| 137 | +| Field | Description | |
| 138 | +|---|---| |
| 139 | +| `scenario` | spamoor scenario name (`eoatx`, `gasburnertx`, `erc20tx`, `uniswap-swaps`, etc.) | |
| 140 | +| `probability` | 0.0-1.0, chance of running per invocation (omit = always run) | |
| 141 | +| `timeout` | max duration per entry (default `15m`) | |
| 142 | + |
| 143 | +When using `start` or `burst`, `BENCH_COUNT_PER_SPAMMER` is overridden by the computed per-run count. The matrix value is used as-is by `run`. |
| 144 | + |
| 145 | +## Build |
| 146 | + |
| 147 | +```sh |
| 148 | +# binary |
| 149 | +cd apps/loadgen && go build -o ev-loadgen . |
| 150 | + |
| 151 | +# docker image |
| 152 | +docker build -f apps/loadgen/Dockerfile -t ev-loadgen:dev . |
| 153 | + |
| 154 | +# via just |
| 155 | +just build-loadgen |
| 156 | +just docker-build-loadgen |
| 157 | +``` |
0 commit comments