currawong

A concurrent HTTP load-testing CLI in Crystal

currawong

A concurrent HTTP load-testing command line tool written in Crystal. Fibers for the workers, nothing outside the standard library.

License Language Tests

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 its nil.
  • A shared atomic Budget makes 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.run takes 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