currawong
currawong
A concurrent HTTP load-testing command line tool written in Crystal. Fibers for the workers, nothing outside the standard library.
Refer to LICENSE for the legal bits.
What's in it
- A pool of workers (fibers) sending GET requests to one URL.
- A run that ends after a fixed number of requests (
-n) or after a fixed time (-d). - A report with throughput, latency percentiles (p50, p90, p99), minimum, mean and maximum latency, the number of failed requests, and a histogram of HTTP status codes.
Currawong::Stats, which only deals with numbers and does no I/O.
Only run it against systems you're allowed to test.
bin/currawong -c 20 -n 2000 http://localhost:8080/health
bin/currawong -c 8 -d 15 http://localhost:8080/
-c, --concurrency=N number of workers (default 10)
-n, --requests=N total number of requests (default 100 when no duration is given)
-d, --duration=SECS run for this many seconds
๐๏ธ Architecture
src/main.cr โโถ Currawong::CLI.run(argv, stdout, stderr)
src/currawong.cr requires the three files below
โโ cli.cr OptionParser, validation, exit codes (0 ok, 2 usage), report
โ โ builds
โ โผ
โโ runner.cr Runner(url, workers, total, duration)
โ Budget (Atomic counter) โ hands out request slots
โ N fibers โ one HTTP::Client each โ fetch โโถ Channel(Sample?)
โ a nil on the channel means "this worker is done"
โโ stats.cr Sample(latency, status?) โโถ Stats.summarise โโถ Summary
percentile (nearest rank) | histogram | mean / min / max
- Each worker keeps one connection open and reconnects after an error. Workers send
Samples down a channel, and the runner collects until every worker has sent itsnil. - A shared atomic
Budgetmakes sure a count-limited run issues exactly the number of requests asked for, however many fibers are racing for them. - Failed requests (connection errors, timeouts) are
Samples with no status. They're counted as errors and left out of the latency figures, so a burst of timeouts doesn't distort the percentiles. - Percentiles use the nearest-rank method on the sorted latencies.
CLI.runtakes its streams as arguments, so the specs can call it without spawning a process.
๐ Quick start
shards build --release
bin/currawong -c 8 -n 2000 http://127.0.0.1:8080/health
Against a tiny local Crystal server returning ok:
requests: 2000 in 0.03s (59972.8/s)
errors: 0
latency ms: min 0.03 mean 0.13 max 4.59
p50 0.11 p90 0.14 p99 0.64
status codes:
200: 2000
That's a toy server on loopback inside a container, so read it as proof the output works rather than as a benchmark.
๐งช Testing
15 specs, all passing (crystal spec):
Stats(8): the nearest-rank percentile, small samples, empty data, out-of-range percentiles rejected, the status histogram being counted and ordered, a full summary of latencies and statuses, failed requests staying out of latency figures, and an empty run.Runner(5): exactly the requested number of requests, status codes recorded, stopping when the duration elapses, connection failures counted as errors, and a run with no limit rejected.CLI(2): usage errors print help and exit 2, and a run reports its results.
The runner specs start a local HTTP server on a free port.
โ ๏ธ Honest limits
- Only GET, with no request body, header or TLS verification options yet.
- Fibers run on a single thread by default, so a very fast server can end up limited by the load generator.
Licence
MIT.
Repository
currawong
Owner
Statistic
- 0
- 0
- 0
- 0
- 0
- about 4 hours ago
- November 19, 2026
License
MIT License
Links
Synced at
Thu, 19 Nov 2026 04:50:06 GMT
Languages