Mastering wrk: Install, Basic Use, and Advanced Lua Scripting for HTTP Load Testing

Installation

wrk runs on most Unix‑like operating systems (Windows is not supported) and requires LuaJIT and OpenSSL. Install it by cloning the source from GitHub and running

make

in the project directory. The resulting

wrk

binary can be copied to a directory in

/usr/local/bin

for easy access.

<code>git clone https://github.com/wg/wrk
make</code>

If you prefer to use system‑installed LuaJIT and OpenSSL, compile with

WITH_LUAJIT

and

WITH_OPENSSL

options, e.g.:

<code>make WITH_LUAJIT=/usr WITH_OPENSSL=/usr</code>

Basic Usage

Running

wrk

without arguments displays the help message. A typical test command looks like:

<code>wrk -t8 -c200 -d30s --latency "http://www.bing.com"</code>

The output includes thread statistics, latency distribution, total requests, and throughput. For the example above, 8 threads and 200 connections were used for a 30‑second test against Bing, yielding about 59,658 requests per second.

Lua Script Customization

wrk allows Lua scripts to customize the load test in three phases: setup (executed once per thread before the test starts), init/request/delay/response (executed during the test), and done (executed once after the test finishes). Each thread gets its own Lua environment.

Setup Phase

<code>function setup(thread)
  -- optional per‑thread initialization
end</code>

Running Phase

<code>function init(args) end
function delay() end
function request()
  return wrk.format(nil, "/path")
end
function response(status, headers, body) end</code>

Done Phase

<code>function done(summary, latency, requests)
  -- generate custom report
end</code>

The global

wrk

table provides fields such as

scheme

,

host

,

port

,

method

,

path

,

headers

, and

body

, which can be modified to affect all requests.

Example Scripts

POST request: Set

wrk.method = "POST"

, define

wrk.body

, and add a

Content‑Type

header.

Dynamic URL parameter: In

request()

, generate a random

uid

and build the path

"/test?uid=" .. uid

.

Fixed delay: Return

10

from

delay()

to pause 10 ms before each request.

Token‑based authentication: Use an initial

GET /authenticate

request, capture the

X‑Token

header, then switch to

/resource

with the token added to subsequent request headers.

HTTP pipelining: In

init()

, concatenate multiple formatted requests (e.g.,

/?foo

,

/?bar

,

/?baz

) into a single string returned by

request()

.

These examples demonstrate how wrk’s Lua API can be leveraged to perform more realistic and complex load‑testing scenarios.

Conclusion

wrk is a lightweight, high‑performance HTTP benchmarking tool that, combined with Lua scripting, offers great flexibility for simulating real‑world traffic patterns.