Stampede

module

v1.2.0 Latest Latest Go to latest Published: Oct 7, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/Ivan825/Stampede

Links

Open Source Insights

README ¶

Your launch-day traffic, before launch day.
Describe your users. Stampede becomes a thousand of them.

Stampede is an open-source, self-hosted load testing platform. You describe how your users behave, Stampede checks each journey with a single user, then runs many of them at once and tells you where your product breaks.

Released. Install the latest release with the one-line installer below. This README lists what works today; anything not built yet is marked planned.

Get started

Just the CLI. One binary, no server, no database: write or generate a scenario, run it, get a report.

# Linux and macOS
curl -fsSL https://raw.githubusercontent.com/Ivan825/Stampede/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/Ivan825/Stampede/main/install.ps1 | iex

The installers download the latest release for your OS and CPU (Linux, macOS or Windows; amd64 or arm64), check its SHA-256 checksum and install the single stampede binary. Nothing else is needed. Then:

stampede init --target http://localhost:3000   # detect the product type, install a pack, dry-run its journeys
stampede run stampede/<pack>/journeys/<file>.yaml -e TARGET_URL=http://localhost:3000 -o report.html
stampede                                        # or the interactive console: /init, /run spike, ...

The full stack with the web UI. Server, web UI, two workers and the database, with Docker:

stampede up            # released images of the installed version
stampede setup         # create the organisation and the owner account

Everything is done with the CLI; the web UI on http://localhost:8080 is for analysis: live runs, reports, comparisons, scenarios, schedules and settings, read only, plus the Stop, Kill and Kill all safety controls.

or, from a clone, the same stack plus ShopLab (http://localhost:8090), a demo shop with six real performance problems planted on purpose:

git clone https://github.com/Ivan825/Stampede && cd Stampede
docker compose up -d --build

The quick start takes you from there to a breakpoint, a fix and a comparison in about five minutes.

Everything from the terminal. Every server feature has a command, each with a table or summary and --json for scripts: stampede setup and login, users, tokens, projects, targets, secrets, push and scenarios, start, runs, report, schedules, drift, ai, notify, integrations, caps, settings and audit. Using Stampede from the CLI goes from an empty server to scheduled, monitored runs without the web UI.

No internet access. Each release attaches an offline bundle (images, binary, Helm chart) for networks without internet access; see air-gapped installs.

See it

A plain-language request confirmed as a command, then a live run at 623 requests per second with 1,210 virtual users

_{Ask in plain words, confirm, watch the run live in the console.}

_{stampede run: 1,000 users through four journeys, targets checked, every step timed.}

_{Every run's report in the web UI, with HTML, PDF, CSV, JSON, JUnit and Markdown exports.} A live run in the web UI with worker health showing one saturated worker

A live run in the web UI with worker health showing one saturated worker

_{Live runs with worker health; a saturated worker is called out.} The self-contained HTML report of a baseline run

_{A self-contained HTML report from stampede run -o report.html.} A project overview in the web UI listing recent runs and verdicts

_{Each project's runs and verdicts at a glance.}

Throughput against load with the knee marked
_{Throughput against load: where your system stops keeping up, marked.}

The screenshots are real: the terminal ones are recorded from the CLI running against the demo apps in examples/packlab, the web UI ones from its built-in demo data.

What works today

Describe users, not requests. A scenario is a YAML file of weighted journeys with ${} expressions, extractors (JSONPath, header, cookie, regex, CSS), checks (status, body, JSONPath values, JSON Schema, latency, any expression), think times, branches, loops, conditions, JavaScript script steps, and test data from CSV, JSON, lists, ranges, generated fake data or a SQL query. It is validated against a published JSON Schema, including that every variable is extracted before it is used.

Numbers you can trust. Latency is measured from each request's scheduled send time, so queueing is never hidden. Percentiles come from merged HDR-style histograms, never averages of percentiles. DNS, connect, TLS, wait and download are timed for every request. The load generator watches itself (CPU, scheduling lag, dropped iterations, GC, file descriptors, ephemeral ports, network), on workers and in stampede run alike, and a run it distorted is marked generator-limited instead of failed. Each kind of failure keeps redacted request/response examples (browser steps: a screenshot, console errors and a HAR). Accuracy is checked against a calibrated server in CI (how).

Every test type. Open and closed models; smoke, baseline, stress, spike, soak, breakpoint, steps, recovery and wave shapes on any scenario; targets such as checkout.p95 < 800ms; breakpoint search narrowed by confirmation holds; the knee of the throughput-against-load curve; recovery time after a spike; per-user network emulation (3G, 4G, slow Wi-Fi, or explicit latency, jitter, bandwidth and packet loss); replay of an access log or HAR file at its recorded times; auto-abort when a target falls over (test types).

Fault injection. stampede agent sits next to your database, cache or downstream services and, on a scenario's timeline, slows, throttles, resets or blackholes their connections, pauses or stops containers, or scales deployments down. Every fault is time-limited, audited and reverted when the run ends, and the report shades the fault windows on its charts (fault injection).

Protocols: HTTP/1.1, HTTP/2 (TLS and h2c), REST, GraphQL (with persisted queries), WebSocket, server-sent events with time to first event (for LLM apps), gRPC unary and server streaming via reflection or proto files, and real browser pages in headless Chrome (click, fill, press, assert) with Web Vitals: LCP, CLS, INP, first contentful paint and load time (protocols).

Plugins add step types for other protocols, each running as its own process so a crash cannot take a worker down: stampede plugin install mqtt (or kafka, redis, sql, udp), then steps such as plugin: mqtt.publish. Their settings are checked against the plugin's schema, their timings land in the same per-step histograms, and the target policy applies to the addresses they connect to. A public SDK and conformance suite let you write your own (plugins). The first-party plugins are tested against in-process fakes (Mochi MQTT, kfake, miniredis, SQLite, a UDP echo listener), and a CI job runs the SQL plugin against PostgreSQL and MySQL containers; none has been run against a production cluster here.

Distributed. stampede worker connects out to the server over gRPC. Load is split by capacity with no arrival lost or duplicated, start times are synchronised to within a millisecond, results merge losslessly, a lost worker's share is taken over by an idle worker (or the gap is marked in the report when there is none), and a kill reaches every worker in under a millisecond on a local network. With --worker-mtls (the default in Compose and Helm) every worker gets its own certificate from a CA built into the server, and the join token never crosses the network.

Control plane and UI. stampede server with PostgreSQL/TimescaleDB: REST API (OpenAPI), projects, targets, encrypted secrets, users and roles, single sign-on (OIDC), API tokens, audit log, integrations and notification settings, all managed with the CLI, and a read-only web UI for analysis: live runs and reports with target metrics and trace links, comparisons, scenarios with their journey graph, schedules and settings, and a kill switch that is always on screen.

Reports and CI. Self-contained HTML, PDF, CSV, JSON, JUnit XML and Markdown; exit code 3 when a target fails. stampede compare judges repeated runs of two versions with bootstrap confidence intervals and a measured noise floor, and exits 4 on a regression (comparing, CI). A composite GitHub Action in action/ runs a scenario, writes the job summary, uploads the reports and fails the step on a failed target; CI exercises it both with the latest release and built from the commit.

Scheduled runs. Schedules, managed with stampede schedules or the API (and shown read only in the web UI), start a saved scenario against a target on a cron expression in UTC or any IANA time zone. Each firing gets the same checks as a run started by hand, never overlaps the previous run, and fires at most once however many replicas or restarts are involved (scheduled runs).

Integrations. An observe block charts your own Prometheus queries (CPU, memory, connections) over the run in the report, and every step lists its slowest requests with the W3C trace IDs they carried, as links to Jaeger or Tempo given a link template. On the server, admins configure Prometheus and trace integrations by name, so the server never fetches a URL written in a scenario, and notification channels (signed webhooks, Slack, Discord) hear when a run finishes, misses a target or is killed, with retries, a delivery log and a guard against private destinations. The server traces its API and runs with OpenTelemetry when an OTLP endpoint is set, and a Grafana dashboard covers its own metrics (integrations).

Terminal. stampede alone opens a console that stays open until you leave: every CLI command as /projects list, /compare ... and so on, plus /run spike with a live panel, /run replay access.log, /init <url>, /kill all, or plain language such as "find the breaking point for checkout", always confirmed before it runs. Sessions are saved; stampede --continue picks up the last one (the console).

Product packs. stampede init probes a target (its OpenAPI document, OpenID Connect discovery, home page and headers) and installs the matching pack. All twenty packs ship: e-commerce (tested against ShopLab), and SaaS with GraphQL, AI and LLM apps over SSE, chat over WebSocket, ticketing with a waiting room, login and identity, public APIs with rate limits, fintech with duplicate-payment checks, social feeds with live notifications, news behind a cache, HLS video and live streaming, exams with a live channel, government results and applications, ride hailing and food delivery with live tracking, mobile app backends, serverless cold starts and concurrency limits, IoT over MQTT, event pipelines on Kafka, databases and caches (PostgreSQL and Redis) and game backends (WebSocket matchmaking, a UDP game server). Each is tested on every push against a small reference app with planted bottlenecks (PackLab); the last four use the protocol plugins, against an in-process broker, Kafka cluster, Redis or UDP server, and PostgreSQL in a service container (packs).

AI journey generation (optional, bring your own key, never during load). Anthropic, OpenAI, Gemini, Ollama or any OpenAI-compatible server turns a description, an OpenAPI spec, a GraphQL schema, a HAR file, an access log or a headless-browser crawl of the site into a scenario. Every journey is dry-run against your target and repaired until it works before you approve it; recorded traffic is redacted before anything reaches a model (AI generation). The pipeline is tested with a scripted model; it has not yet been run against a real provider in this repository's CI. stampede run --narrative (or stampede report --narrative) adds a written summary to a finished report in which every claim cites the figures behind it and is labelled measured or suspected. stampede coverage shows which API endpoints no journey exercises, and stampede drift finds journeys an API change broke (coverage and drift).

Safety. Private targets just work; public targets stay under low caps until you prove ownership; requests cannot leave the target's host; hard caps per server and per target; audit log (safety).

Planned

Connection-flood and slow-client stresses, and published cluster-scale measurements (200 workers, 100,000 requests per second across them, 50,000 WebSocket connections). The nightly comparison with k6 and wrk2 and one process's measured throughput are in bench and on the website's benchmarks page.

Deploy

How	Guide	State
Docker Compose, one machine	docs/deploy/compose.md	`docker compose up -d` at the repository root
Kubernetes, Helm chart	docs/deploy/helm.md	tested on kind: install, `helm test`, a distributed run
Kubernetes operator (`StampedeCluster`, `StampedeRun`)	docs/deploy/operator.md	alpha; envtest-tested, and on kind in CI
Workers in several AWS/GCP regions, Terraform	docs/deploy/terraform.md	validated, not yet applied
Air-gapped networks, offline bundle	docs/deploy/airgap.md	a nightly CI job builds it, removes every image, and installs and starts Stampede from the bundle alone
Upgrades, backups, restores	docs/deploy/upgrades.md

Each release has binaries for Linux, macOS and Windows (amd64 and arm64) with SBOMs and signed checksums, signed multi-arch images on ghcr.io/ivan825/stampede, the Helm chart on oci://ghcr.io/ivan825/charts and offline bundles. The latest is v1.0.0.

Documentation

Everything is in docs/: quick start, concepts, guides (among them using Stampede from the CLI), the scenario reference, the CLI reference and configuration.

Building from source

git clone https://github.com/Ivan825/Stampede
cd Stampede
make build        # bin/stampede
make test
go run ./bench/accuracy -quick

Requires Go 1.27 or later.

Contributing and security

See CONTRIBUTING.md. Report vulnerabilities privately as described in SECURITY.md.

Licence

Apache-2.0. See LICENSE.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
bench
accuracy command Command accuracy measures how closely Stampede's reported latency percentiles match ground truth.	Command accuracy measures how closely Stampede's reported latency percentiles match ground truth.
compare command Command compare runs the same open-model workload through Stampede, k6 and wrk2 against the calibrated echo server, and compares each tool's p50, p95 and p99 with the server's exact hold times.	Command compare runs the same open-model workload through Stampede, k6 and wrk2 against the calibrated echo server, and compares each tool's p50, p95 and p99 with the server's exact hold times.
echo Package echo is the calibrated target used by Stampede's accuracy benchmark.	Package echo is the calibrated target used by Stampede's accuracy benchmark.
echoserver command Command echoserver runs the calibrated echo target used by Stampede's accuracy benchmark.	Command echoserver runs the calibrated echo target used by Stampede's accuracy benchmark.
scale command Command scale measures how much load one Stampede process can generate before the generator, not the target, becomes the limit.	Command scale measures how much load one Stampede process can generate before the generator, not the target, becomes the limit.
cmd
stampede command Command stampede is the single Stampede binary: server, worker, agent, standalone runner and terminal UI.	Command stampede is the single Stampede binary: server, worker, agent, standalone runner and terminal UI.
examples
packlab command Command packlab runs one of the in-memory reference apps that the product packs are tested against:	Command packlab runs one of the in-memory reference apps that the product packs are tested against:
packlab/apilab Package apilab is APILab, a public developer API: API keys, per-key rate limits answered with 429 and Retry-After, cursor pagination, idempotent creates and webhook deliveries.	Package apilab is APILab, a public developer API: API keys, per-key rate limits answered with 429 and Retry-After, cursor pagination, idempotent creates and webhook deliveries.
packlab/authlab Package authlab is AuthLab, a small OAuth 2.0 and OpenID Connect token service: password, refresh-token and client-credentials grants, userinfo, introspection and revocation, with Ed25519-signed JWT access tokens.	Package authlab is AuthLab, a small OAuth 2.0 and OpenID Connect token service: password, refresh-token and client-credentials grants, userinfo, introspection and revocation, with Ed25519-signed JWT access tokens.
packlab/banklab Package banklab is BankLab, a retail bank's API: customers with current and savings accounts, transaction history, monthly statements, transfers and bill payments that take an Idempotency-Key, and a reconciliation check.	Package banklab is BankLab, a retail bank's API: customers with current and savings accounts, transaction history, monthly statements, transfers and bill payments that take an Idempotency-Key, and a reconciliation check.
packlab/chatlab Package chatlab is ChatLab, a chat service: rooms, message history over HTTP and live messages over WebSocket with fan-out to every member.	Package chatlab is ChatLab, a chat service: rooms, message history over HTTP and live messages over WebSocket with fan-out to every member.
packlab/dblab Package dblab is DBLab, the data tier of a shop: PostgreSQL tables for customers, products and orders, seeded into a database you give it, and an in-process Redis (miniredis) with a product cache and a popularity ranking.	Package dblab is DBLab, the data tier of a shop: PostgreSQL tables for customers, products and orders, seeded into a database you give it, and an in-process Redis (miniredis) with a product cache and a popularity ranking.
packlab/edgelab Package edgelab is EdgeLab, a small serverless app on a simulated function platform: a link shortener whose routes are functions (create a link, redirect, stats, a link-preview image) running on instances that start cold, stay warm while used, are reclaimed when idle, and are limited in number per function.	Package edgelab is EdgeLab, a small serverless app on a simulated function platform: a link shortener whose routes are functions (create a link, redirect, stats, a link-preview image) running on instances that start cold, stay warm while used, are reclaimed when idle, and are limited in number per function.
packlab/examlab Package examlab is ExamLab, an online learning and exam platform: courses, timed exams taken question by question with every answer saved as it is given, a WebSocket channel per exam for the timer, proctoring heartbeats and announcements, and assignment submissions checked for similarity.	Package examlab is ExamLab, an online learning and exam platform: courses, timed exams taken question by question with every answer saved as it is given, a WebSocket channel per exam for the timer, proctoring heartbeats and announcements, and assignment submissions checked for similarity.
packlab/gamelab Package gamelab is GameLab, a game backend: sign-in and a leaderboard over HTTP, matchmaking over WebSocket, and a UDP game server that players join with the ticket matchmaking gave them and send inputs to, answered on the server's tick.	Package gamelab is GameLab, a game backend: sign-in and a leaderboard over HTTP, matchmaking over WebSocket, and a UDP game server that players join with the ticket matchmaking gave them and send inputs to, answered on the server's tick.
packlab/govlab Package govlab is GovLab, a government services portal: exam results looked up by roll number and date of birth with downloadable PDF marksheets, notices, and an online application (sign-in by one-time code, a form in sections, document upload, submission with an acknowledgement number and a PDF receipt) with a deadline.	Package govlab is GovLab, a government services portal: exam results looked up by roll number and date of birth with downloadable PDF marksheets, notices, and an online application (sign-in by one-time code, a form in sections, document upload, submission with an acknowledgement number and a PDF receipt) with a deadline.
packlab/iotlab Package iotlab is IoTLab, an IoT platform: an MQTT broker that devices connect to and publish readings through, an ingest service that stores every reading and acknowledges it to its device, device shadows (a desired state set over HTTP and fetched or pushed over MQTT), and a device registry and telemetry store over HTTP.	Package iotlab is IoTLab, an IoT platform: an MQTT broker that devices connect to and publish readings through, an ingest service that stores every reading and acknowledges it to its device, device shadows (a desired state set over HTTP and fetched or pushed over MQTT), and a device registry and telemetry store over HTTP.
packlab/labkit Package labkit holds the small pieces every PackLab reference app shares: JSON helpers, fix flags, bearer tokens, a minimal OpenAPI document, a work counter used to show where the planted bottlenecks spend their time, and the App shape of the apps that also listen on another protocol.	Package labkit holds the small pieces every PackLab reference app shares: JSON helpers, fix flags, bearer tokens, a minimal OpenAPI document, a work counter used to show where the planted bottlenecks spend their time, and the App shape of the apps that also listen on another protocol.
packlab/llmlab Package llmlab is LLMLab, an OpenAI-compatible chat completions API that streams made-up tokens over server-sent events.	Package llmlab is LLMLab, an OpenAI-compatible chat completions API that streams made-up tokens over server-sent events.
packlab/mobilelab Package mobilelab is MobileLab, the backend of a mobile to-do and habits app, shaped like most mobile backends: remote config and feature flags fetched at launch, a minimum app version, device registration for push, delta sync of the user's items with offline changes, batched analytics events, and a GraphQL endpoint with persisted queries for the home screen.	Package mobilelab is MobileLab, the backend of a mobile to-do and habits app, shaped like most mobile backends: remote config and feature flags fetched at launch, a minimum app version, device registration for push, delta sync of the user's items with offline changes, batched analytics events, and a GraphQL endpoint with persisted queries for the home screen.
packlab/newslab Package newslab is NewsLab, a news site: HTML home, section and article pages, an RSS feed and a JSON API, behind a page cache of the kind a CDN or reverse proxy provides (Cache-Control, ETag, Age and X-Cache headers, conditional requests).	Package newslab is NewsLab, a news site: HTML home, section and article pages, an RSS feed and a JSON API, behind a page cache of the kind a CDN or reverse proxy provides (Cache-Control, ETag, Age and X-Cache headers, conditional requests).
packlab/pipelinelab Package pipelinelab is PipelineLab, an event pipeline: an in-process Kafka cluster (franz-go's kfake) with an orders topic, an enricher service that consumes it as the "enricher" consumer group, looks up each order's customer and writes the result to orders.enriched, and an admin API over HTTP that reports topics and consumer lag.	Package pipelinelab is PipelineLab, an event pipeline: an in-process Kafka cluster (franz-go's kfake) with an orders topic, an enricher service that consumes it as the "enricher" consumer group, looks up each order's customer and writes the result to orders.enriched, and an admin API over HTTP that reports topics and consumer lag.
packlab/ridelab Package ridelab is RideLab, an on-demand rides and food delivery service: riders see nearby cars, ask for an ETA and request a ride or order from a restaurant; a dispatcher matches each trip to a driver; the rider follows the driver live over a WebSocket until the trip is complete; drivers' apps stream their locations over a WebSocket.	Package ridelab is RideLab, an on-demand rides and food delivery service: riders see nearby cars, ask for an ETA and request a ride or order from a restaurant; a dispatcher matches each trip to a driver; the rider follows the driver live over a WebSocket until the trip is complete; drivers' apps stream their locations over a WebSocket.
packlab/saaslab Package saaslab is SaaSLab, a multi-tenant B2B app: sign-in, records that users create and edit, heavy reports, a REST API and a GraphQL API (with automatic persisted queries) for dashboards.	Package saaslab is SaaSLab, a multi-tenant B2B app: sign-in, records that users create and edit, heavy reports, a REST API and a GraphQL API (with automatic persisted queries) for dashboards.
packlab/sociallab Package sociallab is SocialLab, a social network's API: a home feed built from the accounts a user follows, posts, likes, comments, follows, and notifications delivered live over a WebSocket.	Package sociallab is SocialLab, a social network's API: a home feed built from the accounts a user follows, posts, likes, comments, follows, and notifications delivered live over a WebSocket.
packlab/streamlab Package streamlab is StreamLab, a video service that delivers HLS: a catalogue, playback sessions with signed tokens, multivariant and media playlists, MPEG-TS segments in four renditions for 30 on-demand videos, two live channels whose playlists slide forward every two seconds, and playback heartbeats.	Package streamlab is StreamLab, a video service that delivers HLS: a catalogue, playback sessions with signed tokens, multivariant and media playlists, MPEG-TS segments in four renditions for 30 on-demand videos, two live channels whose playlists slide forward every two seconds, and playback heartbeats.
packlab/ticketlab Package ticketlab is TicketLab, a ticketing service: events with seat maps, seat holds that expire, orders, and a WebSocket waiting room in front of the headline on-sale.	Package ticketlab is TicketLab, a ticketing service: events with seat maps, seat holds that expire, orders, and a WebSocket waiting room in front of the headline on-sale.
gen
stampede/plugin/v1
stampede/worker/v1
internal
agent Package agent is stampede agent: a helper that runs inside the user's environment and injects faults into dependencies during a load test.	Package agent is stampede agent: a helper that runs inside the user's environment and injects faults into dependencies during a load test.
ai Package ai generates Stampede scenarios with a language model, before any load is run.	Package ai generates Stampede scenarios with a language model, before any load is run.
ai/provider Package provider talks to large language model APIs for Stampede's optional AI journey generation.	Package provider talks to large language model APIs for Stampede's optional AI journey generation.
api/gen Package gen provides primitives to interact with the openapi HTTP API.	Package gen provides primitives to interact with the openapi HTTP API.
auth Package auth handles passwords, session and API tokens, roles and the identity of the caller.	Package auth handles passwords, session and API tokens, roles and the identity of the caller.
cli Package cli wires the stampede command tree.	Package cli wires the stampede command tree.