ADR 007: Target Capabilities and Architecture Aspirations¶

1. Progressive disclosure of scale¶

A load test should be trivial to run on a laptop and scale — unchanged — to a high-throughput single host and then to a distributed fleet, with results that remain comparable across all three. The user names the scale (single-process, multi-process, distributed); the scenario, metrics, and thresholds do not change.

Achievable: locust runs the same user classes in a single process or across a ZeroMQ master/worker fleet — see locust/runners.py; artillery runs the same script locally or fanned out across AWS Lambda/Fargate.

→ Follow-up ADR: scale modes (single-process / multi-process / distributed).

2. Measurement integrity under load¶

The numbers must stay honest when the target is overloaded — the moment they matter most. That means open-loop arrival modeling, monotonic timing, recording scheduled-versus-actual start time, and resistance to coordinated omission, so a slow target reduces neither the offered load nor the reported tail latency silently.

Achievable: vegeta’s pacer fires on a schedule independent of in-flight latency and catches up when behind — see lib/pacer.go; wrk records latency in a monotonic histogram with an explicit coordinated-omission correction pass in src/stats.c. jmeter having to bolt on an open-model thread group years later is the cautionary counter-example.

→ Follow-up ADR: execution & scheduling model.

3. Multi-protocol behind one contract¶

HTTP/1.1 and HTTP/2, WebSocket, and gRPC should share one scenario API, one metric vocabulary, and one threshold language. A user learns the contract once; protocols are pluggable engines beneath it.

Achievable: artillery drives each protocol through a separate engine behind one runner — the HTTP engine in packages/core/lib/engine_http.js sits beside sibling engine packages, all emitting the same metric shape.

→ Follow-up ADR: protocol client engines.

4. Scenarios authored in real Python, with a declarative subset¶

Power users write scenarios as ordinary (async) Python; a declarative subset — targets, steps, checks — covers the common case, travels well, and is the only thing a future faster execution mode must understand. Arbitrary Python always runs in Python.

Achievable: locust scenarios are plain Python classes and weighted tasks — see locust/user/task.py; artillery offers a declarative flow for the common case alongside imperative JavaScript hooks for the rest.

→ Follow-up ADR: scenario API and the native execution mode (under ADR 003).

5. Pass/fail as a first-class product¶

A load test should answer “did it pass?”, not just “how fast was it?”. Per-request checks (status, header, body shape) and post-aggregate SLO thresholds (p99 < 500ms, error_rate < 1%) drive an abort decision and a CI exit code.

Achievable: artillery’s ensure plugin turns aggregate thresholds into a pass/fail gate — see packages/artillery-plugin-ensure/index.js.

→ Follow-up ADR: checks & thresholds.

6. Metrics you can trust and merge¶

Latency aggregates must hold in bounded memory regardless of run length, merge correctly across workers (combine summaries, never average percentiles), and mean the same thing at every scale.

Achievable: vegeta keeps percentiles in a constant-memory t-digest — see lib/metrics.go; locust merges worker stats by summing histograms and computing percentiles after the merge in locust/stats.py.

→ Follow-up ADR: metric engine & storage.

7. Observability and outputs by default¶

Results should reach a human and a machine without ceremony: a console summary, JSON, CSV, and HTML out of the box, plus streaming to OpenTelemetry, Prometheus, InfluxDB, and Datadog — all off the measurement hot path.

Achievable: jmeter streams live metrics through an asynchronous backend-listener queue to Graphite/InfluxDB without slowing the samplers — see .../visualizers/backend/BackendListener.java; artillery ships a publish-metrics plugin family for the same.

→ Follow-up ADR: outputs & exporters.

8. Python-first, optionally Rust-accelerated, never at the cost of integrity¶

The pure-Python implementation installs and runs anywhere and is the source of truth. Rust earns its place only at measured, coarse boundaries, releasing the interpreter during heavy native work, and never changing what a load test measures.

Achievable: polars has Python build a declarative plan and Rust execute it, releasing the GIL during the compute, through a thin binding crate — crates/polars-python/src/lazyframe/general.rs; cython’s discipline is to compile only what profiling proves hot, never changing semantics — see its compilation guide; goose shows a load generator built natively end-to-end in goose@0.18.1.

→ Follow-up ADR: Rust acceleration map (building on ADR 002 and ADR 003).

9. A framework that measures itself¶

Self-harnessing, self-benchmarking, and self-profiling are part of the product, not an afterthought. This is already specified — see ADR 004, ADR 005, and ADR 006 — and is named here only to place it within the vision.

Positive¶

• Gives the project and its contributors a shared, concrete picture of what rampa is for.

• Anchors each capability to a working example, so the vision is demonstrably achievable, not speculative.

• Sequences the design work into named, scoped follow-up ADRs instead of one monolithic redesign.

• Keeps the hard technical choices open and explicit rather than implied by today’s code.

Tradeoffs¶

• A vision ADR carries no mechanism; on its own it changes nothing in the product.

• Naming follow-up ADRs creates an expectation to write them.

Risks¶

• Aspirations without follow-through. Mitigation: the roadmap names each follow-up ADR, and ADRs 001–006 already establish the disciplines those ADRs must satisfy.

• Scope drift between the vision and what gets built. Mitigation: each follow-up ADR cites the aspiration it serves, and the progressive-disclosure invariant (comparable results across scales) is a testable constraint per ADR 003.