kemal-router-benchmark

Kemal RouteHandler Lookup Benchmark

Micro-benchmark for the Kemal Web Framework RouteHandler (route lookup). It registers many GET /bench/:id routes and measures lookup_route latency and throughput without starting an HTTP server.

Requirements

• Crystal >= 1.18.2
• Kemal via shards (kemalcr/kemal, lru-cache branch or the branch to compare)

All versions are pinned in shard.yml.

Install

shards install

Run

Quick run (debug build):

crystal run src/kemal-route-benchmark.cr -- [OPTIONS]

Max performance (release build):

crystal build --release src/kemal-route-benchmark.cr
./kemal-route-benchmark [OPTIONS]

Options

• --unique N: Number of unique GET routes to register. Default: 10000
• --lookups N: Number of lookup operations. Default: 200000
• --head P: Percentage of lookups using HEAD (falls back to GET). 0-100. Default: 0
• --seed N: RNG seed for reproducibility. Default: 42
• --paths-perf N: Print a progress dot every N ops. 0 disables. Default: 0
• -h, --help: Show help.

Examples

# Quick run with defaults
crystal run src/kemal-route-benchmark.cr --

# 50k routes, 1M lookups
crystal build --release src/kemal-route-benchmark.cr
./kemal-route-benchmark --unique 1000 --lookups 1000000

# Mixed workload with 20% HEAD requests
./kemal-route-benchmark --unique 1000 --lookups 1000000 --head 20

# Progress output (one dot per 100k ops)
./kemal-route-benchmark --paths-perf 100000

Output

The program prints environment and workload parameters, then final metrics:

• Elapsed: Total time (ms)
• Throughput: Lookups per second

Sample output:

Kemal RouteHandler Lookup Benchmark
Crystal 1.x.x | Kemal x.y.z
unique_paths=10000 lookups=200000 head_percent=0% seed=42
Elapsed: 123.45 ms
Throughput: 1620000.00 lookups/sec

Reproducibility

• Use the same --seed to reproduce the workload sequence.
• Release builds are sensitive to hardware/OS; compare on the same machine and conditions.

License

MIT