kemal-route-benchmark

master branch1 version

master branchlatestOct 31, 2025

github.com/sdogruyol/kemal-router-benchmark

Kemal Router Benchmark

1 stars

0 dependents

License: MIT

Installation

# Add this to your shard.yml
dependencies:
  kemal-route-benchmark:
    github: sdogruyol/kemal-router-benchmark
    branch: master

master is a branch, not a release, so this tracks it rather than pinning a version.

Then run:

shards install

shard.yml

Crystal

>= 1.18.2

License

MIT

Author

Serdar Dogruyol

Target

kemal-route-benchmark from src/kemal-route-benchmark.cr

Dependencies

Runtime Dependencies

kemal*github: kemalcr/kemal, branch: lru-cache

README

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