# wrk — Modern Multi-Threaded HTTP Benchmarking with Lua

> Practical guide to wrk — modern multi-threaded HTTP benchmarking with Lua. Configure load profiles, measure latency percentiles, automate POST requests.

Source: https://www.jpkc.com/db/en/cheatsheets/networking/wrk/

<!-- PROSE:intro -->
wrk is a modern, multi-threaded HTTP benchmarking tool that generates significant load with minimal system resources. Its event-driven model (epoll/kqueue) delivers far higher throughput than classic tools like ab while using only a handful of threads and connections. Lua scripting lets you customise requests, headers and response handling on the fly – from simple GET throughput tests to complex scenarios with dynamic bodies. Perfect when you need to know whether an endpoint holds up under real pressure.
<!-- PROSE:intro:end -->

## Basic Usage

`wrk -t <threads> -c <connections> -d <duration> <url>` — Run a benchmark with threads, connections, and duration.

```bash
wrk -t4 -c100 -d30s http://localhost:8080/
```

`wrk <url>` — Quick benchmark with defaults (2 threads, 10 connections, 10s).

```bash
wrk http://localhost:8080/
```

`wrk -t <threads> -c <connections> -d <duration> --latency <url>` — Show detailed latency percentiles.

```bash
wrk -t4 -c100 -d30s --latency http://localhost:8080/
```

`wrk -t1 -c1 -d5s <url>` — Single-thread single-connection test (baseline latency).

```bash
wrk -t1 -c1 -d5s http://localhost:8080/api
```

## Connections & Duration

`wrk -c <connections> <url>` — Set the number of concurrent connections.

```bash
wrk -c 200 -d 10s http://localhost:8080/
```

`wrk -d <duration> <url>` — Set the test duration (s=seconds, m=minutes).

```bash
wrk -d 1m http://localhost:8080/
```

`wrk -t <threads> <url>` — Set the number of threads (usually = CPU cores).

```bash
wrk -t $(nproc) -c 400 -d 30s http://localhost:8080/
```

`wrk --timeout <duration> <url>` — Set request timeout.

```bash
wrk --timeout 5s -c 100 -d 30s http://localhost:8080/
```

## Headers & Custom Requests

`wrk -H '<header>' <url>` — Add a custom HTTP header.

```bash
wrk -H 'Authorization: Bearer token123' -c 50 -d 10s http://localhost:8080/api
```

`wrk -H 'Content-Type: application/json' <url>` — Set content type header.

```bash
wrk -H 'Content-Type: application/json' -c 50 -d 10s http://localhost:8080/api
```

`wrk -H '<h1>' -H '<h2>' <url>` — Add multiple custom headers.

```bash
wrk -H 'Accept: application/json' -H 'X-API-Key: abc123' -c 50 -d 10s http://localhost/api
```

## Lua Scripts

`wrk -s <script> <url>` — Use a Lua script for custom requests.

```bash
wrk -s post.lua -t4 -c100 -d30s http://localhost:8080/api
```

`wrk -s <script> -- <arg1> <arg2>` — Pass arguments to a Lua script.

```bash
wrk -s bench.lua -t4 -c100 -d30s http://localhost/ -- arg1 arg2
```

## Common Patterns

`wrk -t4 -c10 -d10s --latency <url>` — Light load test with latency distribution.

```bash
wrk -t4 -c10 -d10s --latency http://localhost:8080/
```

`wrk -t8 -c500 -d60s --latency <url>` — Heavy load test for stress testing.

```bash
wrk -t8 -c500 -d60s --latency http://localhost:8080/
```

`for c in 10 50 100 500; do echo "--- $c connections ---"; wrk -t4 -c$c -d10s <url>; done` — Progressive load test at different concurrency levels.

```bash
for c in 10 50 100 500; do echo "--- $c connections ---"; wrk -t4 -c$c -d10s http://localhost:8080/; done
```

<!-- PROSE:outro -->
## Conclusion

wrk is your go-to measuring instrument when you need hard numbers on how many requests per second an endpoint can actually sustain. A single command covers simple throughput tests; Lua scripts unlock realistic scenarios – POST bodies, token authentication, dynamic payloads. Focus on latency percentiles and error rate alongside raw requests per second for a complete picture.

## Further Reading

- [wrk – GitHub Repository](https://github.com/wg/wrk) – source code, README and Lua scripting API
- [wrk Scripting Documentation](https://github.com/wg/wrk/blob/master/SCRIPTING) – Lua hooks for request generation and result evaluation
<!-- PROSE:outro:end -->

## Related Commands

- [ab](https://www.jpkc.com/db/en/cheatsheets/networking/ab/) – classic Apache benchmarker for simple load profiles
- [siege](https://www.jpkc.com/db/en/cheatsheets/networking/siege/) – load testing with URL lists and HTTP authentication
- [h2load](https://www.jpkc.com/db/en/cheatsheets/networking/h2load/) – HTTP/2 and HTTP/3 benchmarking with nghttp2