One binary. Numbers you can trust.
Stampede is a server, a worker, a CLI and a terminal console in one Go binary. The engine was built and checked against ground truth before anything else was built on it.
Architecture
CLI · console · web UI · CI
All speak the same public REST API, defined first in OpenAPI.
stampede server
Run manager, auth and roles, safety checks, reports, optional AI pipeline. One active replica; others stand by.
stampede worker × N
Generate and measure load only. Connect out over gRPC, so they run behind NAT or in other regions.
The engine
Open and closed models
Fixed arrival rates like real traffic, or a fixed population of users. Arrival times are computed exactly from the plan, so a run starts precisely the planned number of iterations.
Latency from the scheduled time
When a request is late, the wait counts. Reports show latency and service time side by side, so queueing is never hidden.
Lossless histograms
HdrHistogram bucketing at three significant digits, stored sparsely. Workers send histograms, not percentiles; the server merges them exactly.
Every phase timed
DNS, connect, TLS, time to first byte and download for every request; time to first event for streams.
Distributed execution
| Step | What happens |
|---|---|
| Shard | Load split by worker capacity; each worker takes a non-overlapping share of arrivals and of unique test data. |
| Synchronise | Clock offsets measured over several round trips; one start time sent ahead in each worker's own clock. |
| Stream | Histograms and counters every second with sequence numbers; a resend is never counted twice. |
| Survive | Three missed heartbeats mark a worker lost; its data is kept, an idle worker takes over its share from the next interval, and the report marks the gap. |
| Stop | Kill reaches every worker at once; a worker that loses the server stops by itself after 10 seconds. |
In the project's tests: workers with clocks set seconds apart start within 0.4 ms of each other; a kill reaches three workers in under 0.5 ms; 200 workers register and run in one test.
AI journey generation
Build a dependency map from an OpenAPI spec, a HAR file or access logs.
The model writes journeys constrained to the scenario schema.
Compile, variable flow, endpoints exist, no payment or SMS hosts.
Each journey runs once with one user against your target.
Failures go back with redacted evidence, up to three rounds.
You review and save; nothing is saved without you.
Optional and bring-your-own-key: Anthropic, OpenAI, Gemini, Ollama or any OpenAI-compatible server. Never called while load runs.
What works today
Read from the repository's features.yaml, so this list cannot drift from the code.
Measurement
- Latency from the scheduled send time (coordinated omission)Shipped
- Merged HDR-style histograms, never averaged percentilesShipped
- DNS, connect, TLS, wait and download timing per requestShipped
- Generator saturation detection and generator-limited verdictsShipped
- Saturated and lost-worker windows shaded on the report chartsShipped
- Accuracy gate against a calibrated server in CIShipped
- Side-by-side accuracy comparison with k6, published nightlyShipped
- wrk2 in the side-by-side comparison (published as measured)Shipped
Load
- Open (arrival rate) and closed (virtual users) modelsShipped
- Shapes: smoke, baseline, stress, spike, soak, breakpoint, steps, recovery, waveShipped
- Breakpoint search and the knee of the throughput curveShipped
- Network emulation per user: latency, jitter, bandwidth, packet lossShipped
- Auto-abort on sustained errors or latencyShipped
- Replay of recorded traffic from access logs and HAR filesShipped
- Fault injection agent: slow, cut or kill dependencies mid-runShipped
- Test data from CSV, JSON, lists, ranges, generated fake data or a SQL queryShipped
- Large-payload tests with generated bodies up to 64 MBShipped
- JavaScript script steps between requestsShipped
- JSON Schema response checksShipped
Protocols
- HTTP/1.1 and HTTP/2 (TLS and h2c)Shipped
- GraphQL with persisted queriesShipped
- WebSocketShipped
- Server-sent events with time to first eventShipped
- gRPC unary and server streamingShipped
- Browser steps in real headless Chrome, with Web VitalsShipped
- Plugins: MQTT, Kafka, Redis, SQL, UDP, and an SDK to write your ownShipped
Scale
- Distributed workers over gRPC, synchronised start, lossless mergeShipped
- Worker loss marked in reports, dead man's switchShipped
- An idle worker takes over a lost worker's share mid-runShipped
- Server replicas, standby or all activeShipped
- Mutual TLS with a built-in certificate authorityShipped
- Split a run's load across worker regions by percentageShipped
- 10-second and 1-minute metric rollups (TimescaleDB continuous aggregates) and metrics retentionShipped
Workflow
- Read-only web UI for analysis: live runs, reports, scenarios, schedules and settings; every action runs from the CLIShipped
- Journey graph of a scenario's journeys and steps in the web UIShipped
- Live worker health in the web UI: CPU, scheduling lag, saturation, heartbeatShipped
- Pack library in the web UIShipped
- Terminal console: every CLI command, plain language, saved sessions (stampede --continue)Shipped
- HTML, PDF, CSV, JSON, JUnit and Markdown reports; CI exit codesShipped
- Release comparison with confidence intervalsShipped
- Side-by-side run comparison in the web UIShipped
- AI journey generation from specs, recordings, logs or a browser crawl, with dry-run validationShipped
- AI report narratives that cite every figureShipped
- Coverage map and drift detection for saved scenarios, in the CLI and the web UIShipped
- Scheduled runsShipped
- Scheduled drift checks with notifications and AI repair proposals from the CLI, with results in the web UIShipped
- AI generation of gRPC journeys from .proto filesShipped
- Scaffolds for new packs and plugins, checked by a dry run and the conformance suiteShipped
- Packaged GitHub Action (Ivan825/Stampede/action@v1)Shipped
Integrations
- Target metrics from Prometheus charted in the reportShipped
- Slowest requests per step with trace links (Jaeger, Tempo)Shipped
- Notifications: signed webhooks, Slack and DiscordShipped
- Own telemetry: Prometheus metrics, OpenTelemetry traces, Grafana dashboardShipped
Operate
- Docker Compose stack with the ShopLab demo appShipped
- Helm chartShipped
- Kubernetes operator (alpha)Shipped
- Terraform examples for multi-region workersShipped
- Air-gapped install bundleShipped
- Homebrew and Scoop packagesShipped
Safety
- Ownership verification and caps for public targetsShipped
- Requests confined to the target and allowed hostsShipped
- Kill switch in the UI, CLI and APIShipped
- Roles, API tokens, encrypted secrets, audit logShipped
- Per-project role overrides, set with the CLI or the APIShipped
- Organisation and project caps on rate, users and duration, set with the CLI or the API and shown in the web UIShipped
- Optional passing dry run required before load, with each journey's result on the run pageShipped
- Runs calling payment, SMS, email or CAPTCHA services refusedShipped
- Single sign-on with OpenID ConnectShipped
- SSO configuration and server load caps shown read-only to admins in the web UIShipped