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.

git clone https://github.com/wg/wrk
make

If you prefer to use system‑installed LuaJIT and OpenSSL, compile with WITH_LUAJIT and WITH_OPENSSL options, e.g.:

make WITH_LUAJIT=/usr WITH_OPENSSL=/usr

Basic Usage

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

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

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

function setup(thread)
  -- optional per‑thread initialization
end

Running Phase

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

Done Phase

function done(summary, latency, requests)
  -- generate custom report
end

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.