Celeris Benchmarks

Reproducible HTTP server benchmarks on bare-metal AWS instances. Compare production Go frameworks against theoretical maximum performance using raw syscalls.

Why This Exists

This suite exists to accurately measure the real performance of Celeris across releases, engines, and resource profiles — providing reliable guidance on how it performs against production Go frameworks and the theoretical syscall ceiling.

Most benchmarks run on shared VMs with noisy neighbors, making results unreliable. This suite runs on dedicated bare-metal instances (c7g.metal, c7i.metal-24xl) with automated CI/CD, so every release gets consistent, comparable numbers.

We test three categories:

• Baseline: Production frameworks (Gin, Fiber, Echo, Chi, Iris, Hertz, FastHTTP, stdlib)
• Celeris: Celeris engines (io_uring, epoll, adaptive) with latency/throughput/balanced profiles
• Theoretical: Raw epoll/io_uring implementations showing the performance ceiling

Latest Results

Results are published to the goceleris/docs repository on each metal benchmark run, keyed by Celeris library version. See benchmark data for:

• ARM64 (Graviton) on c7g.metal
• x86-64 (Intel) on c7i.metal-24xl

Servers Tested

Production Frameworks

Server	Protocol	Framework
stdhttp	HTTP/1.1, H2C, Hybrid	Go stdlib
fasthttp	HTTP/1.1	FastHTTP
fiber	HTTP/1.1	Fiber
gin	HTTP/1.1, H2C, Hybrid	Gin
chi	HTTP/1.1, H2C, Hybrid	Chi
echo	HTTP/1.1, H2C, Hybrid	Echo
hertz	HTTP/1.1, H2C, Hybrid	Hertz
iris	HTTP/1.1, H2C, Hybrid	Iris

Celeris

Server	Protocol	Implementation
celeris-iouring	HTTP/1.1, H2C, Hybrid	Celeris io_uring engine
celeris-epoll	HTTP/1.1, H2C, Hybrid	Celeris epoll engine
celeris-adaptive	HTTP/1.1, H2C, Hybrid	Celeris adaptive engine (runtime selection)

Each Celeris engine is tested with three resource objective profiles: latency, throughput, and balanced.

Theoretical Maximum

Server	Protocol	Implementation
epoll	HTTP/1.1, H2C, Hybrid	Raw epoll syscalls
iouring	HTTP/1.1, H2C, Hybrid	io_uring with multishot (kernel 6.15+)

Quick Start

# Clone and build
git clone https://github.com/goceleris/benchmarks
cd benchmarks
mage build

# Run a quick local benchmark
mage benchmarkQuick

# Run full benchmark (30s per server)
mage benchmark

Benchmark Tool

./bin/bench -mode baseline -duration 30s -connections 256
./bin/bench -mode theoretical -duration 30s -connections 256
./bin/bench -mode all -duration 60s -connections 512

Benchmark Types

Type	Endpoint	Description
simple	GET /	Plain text response
json	GET /json	JSON serialization
path	GET /users/:id	Path parameter extraction
body	POST /upload	2KB request body
headers	GET /users/:id	Realistic API headers (~850 bytes: JWT, cookies, User-Agent)

CI/CD

Benchmarks run automatically:

• On Release: Full metal benchmark on bare-metal instances
• On PR (with label): Quick validation on smaller instances

The C2 orchestration system manages AWS spot instances, handles capacity fallbacks, and commits results automatically.

Infrastructure

Benchmarks run on AWS using a C2 (command and control) server that:

• Provisions spot instances with on-demand fallback across multiple regions
• Selects regions dynamically based on spot pricing and vCPU quota availability
• Coordinates server/client workers across availability zones
• Logs region/AZ placement for each worker in workflow output
• Collects results and publishes to goceleris/docs
• Cleans up resources automatically

PRs can deploy their own C2 server by adding a benchmark label (bench-fast, bench-med, or bench-metal), enabling testing of C2 code changes in isolation.

Instance Types

Each benchmark mode uses a fixed instance type to ensure consistent, comparable results:

Mode	ARM64 Server	ARM64 Client	x86 Server	x86 Client
fast	c6g.medium	t4g.small	c5.large	t3.small
med	c6g.2xlarge	c6g.xlarge	c5a.2xlarge	c5a.xlarge
metal	c7g.metal	c7g.16xlarge	c7i.metal-24xl	c7i.24xlarge

AWS Quota Requirements

Mode	ARM64 vCPUs	x86 vCPUs
fast	3	4
med	12	12
metal	128	192

Contributing

Requirements

• Go 1.26+: Download
• Mage: Build tool (Go-based Make alternative)

  go install github.com/magefile/mage@latest
  # or on macOS
  brew install mage

Run mage -l to see all available commands with descriptions.

Development Workflow

1. Fork and create a feature branch
2. Make your changes
3. Run mage check to verify everything passes
4. Submit a pull request
5. Add bench-fast label to PRs for benchmark validation

Adding a Server

1. Create package in servers/baseline/ or servers/theoretical/
2. Implement all benchmark endpoints
3. Register in cmd/server/main.go

License

Apache 2.0