wrk

intent

use this skill to run, design, and interpret HTTP load tests with wrk, a high-performance benchmarking tool that combines multiple threads, persistent connections, and event-driven architecture. wrk excels at generating substantial load from a single machine and supports lua scripting for dynamic request generation (randomized headers, POST bodies, per-request behavior). use it when you need realistic traffic simulation on authorized targets: internal services, dev/staging/sandbox environments, or explicitly approved performance-test targets. do not use wrk on production systems or third-party targets without explicit authorization.

inputs

wrk binary: must be installed locally. on macOS, install via brew install wrk. on linux, build from source or use your package manager.

target URL: full HTTPS or HTTP endpoint, e.g., https://example.internal/api/v1/items. verify before each test that the target is authorized for load testing.

lua script (optional): file path to a .lua script if you need dynamic headers, randomized inputs, request bodies, or per-request logic. wrk calls these functions during the test: setup(thread) (once per thread before test), init(args) (per thread init), request() (before each HTTP request), response(status, headers, body) (after each response), done(summary, latency, requests) (after benchmark finishes).

authorization context: if the target requires authentication, provide bearer tokens, API keys, cookies, or tenant IDs via lua script or -H static headers. store secrets in environment variables, not in scripts or command lines that may be logged.

monitoring/observability: gather links to service logs, dashboards, alert thresholds, rate limit configs, WAF rules, CDN behavior, and load balancer settings before running tests. know your downstream dependencies (databases, caches, third-party APIs) that may be hit by the test.

procedure

1. confirm authorization: verify with the service owner or operations team that load testing is permitted on the target environment (local, dev, staging, sandbox, or production-approved test slot). document the approval.

2. start with conservative parameters: run a 30-second baseline test with minimal load to verify connectivity and response behavior.

   • input: target URL, 2 threads, 20 connections, 30-second duration.
   • command: wrk -t2 -c20 -d30s --latency https://example.internal/health.
   • output: latency distribution, requests/sec, socket errors (if any), non-2xx responses.

3. create or review lua script (if needed): if you need dynamic headers, request bodies, or randomized inputs, write a .lua file with a request() function that returns wrk.format(method, path, headers, body). seed math.random once per thread with os.time() plus a counter to avoid identical sequences in long tests.

   • input: test strategy (e.g., "randomize X-Forwarded-For per request").
   • output: .lua file with request() function and helper functions (e.g., random_public_ipv4()).

4. validate lua script locally: run the test with the script and a small load (2 threads, 20 connections, 30 seconds) to catch syntax errors, logic bugs, or unexpected response codes.

   • input: .lua file, conservative parameters, target URL.
   • command: wrk -t2 -c20 -d30s --latency -s script.lua https://example.internal/api/endpoint.
   • output: latency distribution, requests/sec, response codes, errors.

5. scale load incrementally: increase threads, connections, or duration in steps. monitor service health, logs, autoscaling events, rate limit rejections, and downstream dependency health between each step.

   • input: previous test results, monitoring dashboards, service capacity estimate.
   • step examples:
     • test 1: 2t, 20c, 30s.
     • test 2: 4t, 100c, 60s.
     • test 3: 8t, 500c, 300s.
   • stop if: socket errors spike, non-2xx responses exceed acceptable threshold, service alerts fire, or downstream dependencies show strain.
   • output: latency, throughput (req/sec), error rates at each step.

6. collect final results: run the target load profile (determined in step 5) and capture full output including latency percentiles, socket errors, and response codes.

   • input: final load parameters, target URL, lua script (if applicable).
   • command: wrk -t<threads> -c<connections> -d<duration> --latency [-s script.lua] <url>.
   • output: latency avg/stdev/max, latency distribution (50th, 90th, 99th percentiles), requests/sec, transfer/sec, socket errors, non-2xx counts.

7. interpret results: compare latency, throughput, and error rates against baseline and SLA targets. identify bottlenecks (client resources, network, service, database, cache, downstream) by reviewing logs and monitoring dashboards during the test window.

   • input: wrk output, service logs, dashboard metrics, response samples.
   • output: analysis of whether the service met performance targets, where bottlenecks occurred, and recommendations for capacity or optimization.

decision points

if the target requires authentication: add -H 'Authorization: Bearer <token>' for static bearer tokens, or define headers in your lua request() function if tokens rotate or differ per request. never hardcode secrets; use environment variables or secure secret management.

if you need dynamic request properties (randomized IPs, variable paths, request bodies): write a lua script. otherwise, use simple -H flags for static headers.

if the baseline test shows socket errors or non-2xx responses: investigate before scaling. check service logs, network connectivity, authentication, WAF rules, and rate limits. do not assume the service is saturated until you rule out misconfiguration.

if socket errors appear during scaling but service logs show no errors: the bottleneck is likely on the client side (file descriptor limits, ephemeral port exhaustion, thread pool saturation). increase client OS limits (ulimit -n, system TCP tuning) or reduce connection count per thread.

if latency is stable but throughput is lower than expected: the service may be rate-limiting or applying backpressure. check response headers for rate-limit info, WAF rules, or explicit rate-limit headers. reduce load slightly or extend duration to stay within limits.

if you need to test a production endpoint and cannot get explicit authorization: do not proceed. wrk can be disruptive even at moderate settings if endpoints are expensive, hit shared dependencies, or lack rate-limit protections. test only approved, isolated, or replica environments.

if randomized X-Forwarded-For headers are needed: use the provided lua helper (random_public_ipv4()) to generate public-looking IPs while avoiding private/reserved ranges. confirm with the service owner that this header is safe (will not bypass IP-based aggregation, caching, rate limiting, or security controls unintentionally).

output contract

wrk outputs a text summary to stdout. capture and store this for each test run:

• latency table: avg, stdev, max, +/- stdev (if --latency flag used); includes 50th, 90th, 99th, 99.9th percentile latencies.
• requests/sec: approximate throughput achieved by the test client.
• transfer/sec: observed response bandwidth in bytes/sec.
• socket errors: count of connection failures, read/write errors, timeouts, broken pipes.
• non-2xx or 3xx responses: count and breakdown of application-level errors or unexpected status codes.

store results in a timestamped file or result dashboard for trending:

test-run-2024-01-15T14-30-00Z.txt
test-run-2024-01-15T14-35-00Z.txt
...

include in each result file: target URL, parameters (-t, -c, -d, script name), test start/end time, and full wrk output. optionally append service logs or dashboard snapshots from the test window for correlation.

outcome signal

the skill worked if:

• wrk runs without command-line or syntax errors and produces a latency summary with requests/sec and error counts.
• latency percentiles (50th, 90th, 99th) are within acceptable bounds for your SLA (e.g., p99 < 500ms).
• socket errors are zero or negligible (< 0.1% of requests).
• non-2xx responses are expected (e.g., 0 if all successful, or a known percentage if testing error paths).
• throughput (requests/sec) matches or exceeds baseline expectations for the given thread/connection/duration parameters.
• service health metrics (CPU, memory, disk I/O, downstream latency) remain stable during the test window and return to baseline shortly after the test ends.
• if using lua scripts, headers and request bodies are validated in service logs or application metrics (e.g., X-Forwarded-For appears in logs with randomized IPs per request).
• no alerts or escalations fired during the test (unless intentionally testing saturation).

if latency degrades, errors spike, or alerts fire, stop the test, investigate root cause via logs and dashboards, fix the issue, and retest at a lower load.

appendix: examples

example: baseline health check

wrk -t2 -c20 -d30s --latency https://example.internal/health

example: GET with static headers and latency distribution

wrk -t4 -c100 -d60s --latency \
  -H 'Authorization: Bearer test-token' \
  -H 'Accept: application/json' \
  https://example.internal/api/v1/items

example: GET with random X-Forwarded-For

save as random_xff.lua:

-- random_xff.lua
-- sends each request with a randomized X-Forwarded-For IPv4 address.

local counter = 0

local function random_octet(min, max)
  return math.random(min, max)
end

local function random_public_ipv4()
  -- avoid common private, loopback, link-local, multicast, and reserved ranges.
  -- choose from documentation-safe-ish public-looking ranges for testing.
  local first_octets = { 8, 23, 34, 44, 52, 63, 74, 96, 104, 128, 137, 150, 172, 198 }
  local first = first_octets[math.random(#first_octets)]

  -- avoid 172.16.0.0/12 when first octet is 172.
  local second
  if first == 172 then
    local allowed = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 32, 64, 96, 128, 160, 192, 224 }
    second = allowed[math.random(#allowed)]
  else
    second = random_octet(0, 255)
  end

  return string.format(
    "%d.%d.%d.%d",
    first,
    second,
    random_octet(0, 255),
    random_octet(1, 254)
  )
end

request = function()
  counter = counter + 1

  -- seed periodically. wrk runs lua per thread, so this keeps sequences from being identical.
  if counter == 1 then
    math.randomseed(os.time() + counter)
  end

  local ip = random_public_ipv4()
  local headers = {
    ["X-Forwarded-For"] = ip,
    ["X-Real-IP"] = ip,
    ["Accept"] = "application/json",
    ["User-Agent"] = "wrk-random-xff/1.0"
  }

  return wrk.format("GET", nil, headers)
end

run:

wrk -t4 -c100 -d60s --latency -s random_xff.lua https://example.internal/api/v1/items

example: POST JSON with random X-Forwarded-For

save as post_random_xff.lua:

-- post_random_xff.lua

local function random_public_ipv4()
  local first_octets = { 8, 23, 34, 44, 52, 63, 74, 96, 104, 128, 137, 150, 198 }
  return string.format(
    "%d.%d.%d.%d",
    first_octets[math.random(#first_octets)],
    math.random(0, 255),
    math.random(0, 255),
    math.random(1, 254)
  )
end

init = function(args)
  math.randomseed(os.time())
end

request = function()
  local ip = random_public_ipv4()
  local body = string.format('{"requestId":"wrk-%d","sourceIp":"%s"}', math.random(1000000000), ip)

  local headers = {
    ["Content-Type"] = "application/json",
    ["Accept"] = "application/json",
    ["X-Forwarded-For"] = ip
  }

  return wrk.format("POST", "/api/v1/events", headers, body)
end

run:

wrk -t4 -c100 -d60s --latency -s post_random_xff.lua https://example.internal

common pitfalls

• wrk does not model browsers, JavaScript, or user journeys: it is a raw HTTP load generator, not a browser simulator.
• high connection counts exhaust client resources before the service saturates: file descriptor limits, ephemeral port exhaustion, and thread pool saturation can all hit before the server is stressed. increase OS limits or reduce connections per thread.
• randomized X-Forwarded-For may bypass IP-based controls: logs, rate limiters, caches, dashboards, and abuse controls that aggregate by IP will see scattered sources instead of a concentrated load signature. use this only if explicitly authorized and aware of the implications.
• some proxies overwrite X-Forwarded-For: verify in application logs what the service actually receives.
• production tests are disruptive without careful tuning: even moderate settings can saturate expensive endpoints or shared dependencies. test only approved, isolated, or replica environments.
• socket errors do not always mean the service is saturated: they can indicate misconfiguration, auth failures, network issues, WAF blocking, or client resource exhaustion. check logs and dashboards.
• latency distribution matters more than average: high percentile latencies (p99, p99.9) are often where user experience suffers. focus on those when setting SLA targets.