cryload - HTTP load testing for CI/CD

Cross-platform, single-binary HTTP load testing CLI. A modern alternative to ab / wrk / hey, written in Crystal.

---

Quick start

curl -sSfL https://raw.githubusercontent.com/sdogruyol/cryload/master/scripts/install.sh | sh
cryload https://example.com -n 1000 -c 50

1000 requests, 50 concurrent connections, JSON/CSV/plain output. That's it.

---

Why cryload?

Existing tools work fine on your laptop. cryload is built for the one place that matters most: CI/CD pipelines.

If you need a graph on your laptop, use wrk. If you need to fail a pipeline when p99 goes over 200ms, use cryload.

---

Features

• ⚡ Multi-core load generation (--workers), concurrent connections (-c)
• ⏱️ Duration or request count mode
• 📊 Latency percentiles: p50, p75, p90, p95, p99, p999 + histogram
• 🎯 Honest latency: coordinated-omission-corrected percentiles and rate attainment
• 🔍 Phase breakdown: DNS, connect, TLS, TTFB — see where the time actually went
• 🗂️ Per-URL and per-status breakdowns, not just one global number
• 🎯 CI threshold matrix: --max-p50 … --max-p999, --max-avg, --max-latency, --min-rps, --max-fail-rate, per-endpoint --url-threshold
• 🚦 Exit code taxonomy: slow service, unreachable target and bad config are different codes
• 📦 JSON / CSV / quiet output for pipelines, with a versioned schema
• 🔒 Rate limiting, warmup, keep-alive control, request deadlines, TLS skip
• 🌐 Multi-URL, redirects, proxy, cookies, custom success codes
• 🖥️ Cross-platform: Linux, macOS, Windows - single binary

---

Performance

cryload is fast. Written in Crystal, compiled to native code, and multi-core by default since 6.0.0.

All figures below are the median of 5 runs, with the observed spread, because a single run of a load generator on a shared machine is noise, not a number.

Large responses cost less memory than many small ones, because bodies are streamed through one fixed buffer per worker rather than materialised as a String.

Multi-core buys 3.0x on this hardware. Note that --workers 16 measures slower than --workers 8: once the schedulers outnumber the useful work they fight each other and the target for cores. That is why the default is min(cpu cores, connections) rather than "all of them", and why --workers is a dial worth turning rather than a number to max out.

Methodology. The target is a local Crystal HTTP::Server returning a 2-byte body, running as 7 processes sharing the port via SO_REUSEPORT so that the target is not the bottleneck. Hardware is an AMD Ryzen AI 9 465 (20 threads), over loopback, release build, 3-second runs, median of 5.

These are loopback numbers on one machine, not a claim about your network or your application. They exist to show the load generator's own ceiling — the number you need before you can trust that a measurement is about your server. Reproduce them with the commands in the table:

cryload http://localhost:3000 --workers 8 -c 128 -d 3
cryload http://localhost:3000 --workers 1 -c 128 -d 3

If throughput rises when you raise --workers, your earlier numbers were measuring the load generator, not the target. And look at that spread column before you set a --min-rps gate from a single local run.

No JVM, no Node. Just a single binary that starts instantly and uses almost no memory.

---

Honest latency

Most load testers measure latency from the moment a request is sent. That sounds reasonable until the target stalls. While it is stalled, no requests get sent — so no slow measurements get recorded — and the tool reports the handful of fast responses from before and after the freeze. A target that stops responding makes the numbers look better. This is called coordinated omission.

It is not a rounding error. Here is cryload's own regression test: freeze the target for 1 second during a -q 500 -d 5 run.

Read the second row twice. Same run, same server, same one-second outage: v5 reported a p99 of 0.37 ms and passed the gate, while quietly discarding 490 of the 2500 requests it was supposed to send. v6 reports 951.96 ms and fails the build. Note that v6's service p99 is still sub-millisecond and that is correct — the requests really were served fast once they got out. The outage lives in the waiting, which is exactly what a user would have felt.

v6 fixes this in three places:

• corrected_latency_ms charges each request for the time it spent waiting for its scheduled send slot, plus its service time. A request that was supposed to go out at t=1.0s but went out at t=2.0s is a 1-second-plus request, because that is what a real user would have experienced.
• rate.skipped_requests and rate.attainment_percent report the schedule slots that were never issued, so a run can no longer claim a rate it did not achieve.
• Threshold gates evaluate corrected latency by default, so --max-p99 250 fails on that frozen target instead of passing. Add --fail-on-rate-miss to also fail when the attained rate falls more than 1% short.

Corrected and uncorrected latency are identical when --rate is not set: without a request schedule there is no send delay to correct for. Pass --latency-correction off for v5 gate semantics.

---

Installation

Option 1: Install script (recommended)

Linux / macOS:

curl -sSfL https://raw.githubusercontent.com/sdogruyol/cryload/master/scripts/install.sh | sh -s

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/sdogruyol/cryload/master/scripts/install.ps1 | iex

Option 2: Prebuilt binary

Download from Releases:

chmod +x cryload-linux
./cryload-linux --help

Option 3: Docker

docker run --rm ghcr.io/sdogruyol/cryload https://example.com -n 1000 -c 50

Multi-arch (amd64/arm64) image, ~9 MB. Use --network host on Linux to reach services on the host's localhost. Tags follow the release version without the v prefix: 6.0.0, 6.0, 6, latest.

Option 4: GitHub Action

- uses: sdogruyol/cryload@v6
  with:
    url: http://127.0.0.1:3000/api
    requests: 500
    max_p99: "250"

See docs/github-action.md for all inputs and outputs.

Option 5: Build from source

Requires Crystal >= 1.21.0.

git clone https://github.com/sdogruyol/cryload.git && cd cryload
shards build --release

---

Usage

cryload <url> [options]

Threshold flags are in CI/CD below.

Common examples

# 10K requests, 100 concurrent
cryload http://localhost:3000 -n 10000 -c 100

# 30 seconds, 50 connections
cryload http://localhost:3000 -d 30s -c 50

# POST with JSON body
cryload http://localhost:3000/api -n 500 -m POST \
  -H "Content-Type: application/json" \
  -b '{"name":"cry"}' --timeout 5

See docs/examples.md for more.

---

CI/CD

cryload is built for pipelines. Use --json or --output-format csv for structured output, --output-format quiet for exit-code-only checks.

Threshold matrix

Any breached threshold exits 1.

Latency gates evaluate corrected latency by default; --latency-correction off restores v5 semantics. See Honest latency.

Per-endpoint gates

--url-threshold "PATTERN METRIC VALUE" is repeatable and scopes a gate to the target URLs whose text contains PATTERN:

cryload --urls-file urls.txt -d 30s -c 50 \
  --url-threshold "/api/users max-p99 120" \
  --url-threshold "/api/search max-p99 400" \
  --url-threshold "/api/orders max-fail-rate 0.5" \
  --min-rps 2000

METRIC is one of max-p50 max-p75 max-p90 max-p95 max-p99 max-p999 max-avg max-latency max-fail-rate min-rps. A pattern that matches no target URL is a config error (exit 2), so a renamed endpoint fails the build instead of silently un-gating itself.

Exit codes

A breached threshold takes precedence over a signal code. The same information is in the JSON report as verdict.exit_code and verdict.reason.

GitHub Actions example

Use the official action — it installs cryload, runs the benchmark, and exposes the JSON results as step outputs:

- name: Latency SLA
  id: bench
  uses: sdogruyol/cryload@v6
  with:
    url: http://localhost:3000/api
    requests: 500
    max_p99: "250"

- name: Show p99
  if: always()
  run: echo "p99 was ${{ steps.bench.outputs.p99 }} ms"

See docs/github-action.md for all inputs and outputs. Or install the binary directly:

- name: Install cryload
  run: curl -sSfL https://raw.githubusercontent.com/sdogruyol/cryload/master/scripts/install.sh | sh -s

- name: Latency SLA
  run: |
    cryload http://localhost:3000/api -d 30s -q 500 \
      --max-p99 250 --fail-on-rate-miss --json > result.json
    jq -e '.schema_version == 1' result.json
    jq -r '.thresholds.breached[] | "FAIL \(.name) \(.metric)=\(.actual) limit=\(.limit)"' result.json

--no-progress is no longer needed: progress is only enabled when stderr is a TTY, so CI logs stay clean by default.

---

How cryload compares

Full matrix: docs/comparison.md.

---

Built with Crystal

cryload is written in Crystal. Ruby-like syntax, compiled speed, single-binary deployment.

---

FAQ

Why not just use ab / hey / wrk?

Those tools are great for local benchmarks, and wrk still wins on Lua-scripted scenarios. cryload is built for CI/CD: coordinated-omission-corrected latency, a threshold matrix you can scope per endpoint, an exit code taxonomy, JSON/CSV output with a versioned schema, and cross-platform binaries. Since 6.0.0 it also saturates every core by default, so multi-core is no longer a reason to reach for another tool. If you want to fail a pipeline when p99 goes over 200ms — and be sure that p99 is honest — use cryload.

Can I use cryload for DDoS?

No. cryload is designed for testing your own servers and CI pipelines. Do not use it against targets you don't own.

Does cryload support HTTP/2?

Not yet. HTTP/1.1 only for now. HTTP/2 is on the roadmap.

What is coordinated omission and why should I care?

Most load testers start the latency clock when a request is sent. When the target stalls, nothing gets sent, so nothing slow gets measured — and the report shows only the fast responses from either side of the stall. A target that stops responding therefore looks faster. In cryload's own regression test, freezing the target for one second during a -q 500 -d 5 run made v5 report p99 = 0.37 ms while it silently dropped 490 of 2500 scheduled requests. v6 charges each request for the time it waited for its scheduled slot (corrected_latency_ms), reports the slots it never issued (rate.skipped_requests), and gates on corrected latency by default. See Honest latency.

Why did my exit code change from 1 to 2/3?

v5 returned 1 for every failure. v6 splits them so a pipeline can tell them apart: 1 is a breached threshold (a real regression to triage), 2 is a usage or config error (a broken command line or workflow file), and 3 is an unreachable target (nothing answered — usually a broken test harness, not a slow service). Signals now exit 130/143 instead of 0, so a killed run no longer looks like a pass. If your script did if cryload ...; then, it still behaves the same; if it matched on == 1, widen it to != 0 or switch on the code — docs/examples.md has a template.

Is there a Docker image?

Yes: docker pull ghcr.io/sdogruyol/cryload. The single binary is still the lightest option, but the image is handy for containerized pipelines (GitLab CI, Kubernetes jobs, etc.).

Why is it written in Crystal?

Crystal compiles to a single native binary with no runtime. It starts instantly, uses minimal memory, and delivers C-like performance with Ruby-like syntax.

Sponsors

If cryload helps your CI pipeline, consider sponsoring. Every dollar helps me keep building open source tools full time.

---

License

MIT