Mercurial

annotate third_party/wrk/SCRIPTING @ 178:94705b5986b3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ThirdParty] Added WRK and luajit for load testing.
author MrJuneJune <me@mrjunejune.com>
date Thu, 22 Jan 2026 20:10:30 -0800
parents
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
178
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
1 Overview
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
2
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
3 wrk supports executing a LuaJIT script during three distinct phases: setup,
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
4 running, and done. Each wrk thread has an independent scripting environment
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
5 and the setup & done phases execute in a separate environment which does
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
6 not participate in the running phase.
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
7
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
8 The public Lua API consists of a global table and a number of global
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
9 functions:
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
10
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
11 wrk = {
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
12 scheme = "http",
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
13 host = "localhost",
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
14 port = nil,
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
15 method = "GET",
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
16 path = "/",
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
17 headers = {},
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
18 body = nil,
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
19 thread = <userdata>,
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
20 }
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
21
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
22 function wrk.format(method, path, headers, body)
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
23
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
24 wrk.format returns a HTTP request string containing the passed parameters
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
25 merged with values from the wrk table.
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
26
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
27 function wrk.lookup(host, service)
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
28
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
29 wrk.lookup returns a table containing all known addresses for the host
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
30 and service pair. This corresponds to the POSIX getaddrinfo() function.
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
31
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
32 function wrk.connect(addr)
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
33
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
34 wrk.connect returns true if the address can be connected to, otherwise
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
35 it returns false. The address must be one returned from wrk.lookup().
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
36
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
37 The following globals are optional, and if defined must be functions:
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
38
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
39 global setup -- called during thread setup
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
40 global init -- called when the thread is starting
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
41 global delay -- called to get the request delay
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
42 global request -- called to generate the HTTP request
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
43 global response -- called with HTTP response data
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
44 global done -- called with results of run
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
45
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
46 Setup
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
47
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
48 function setup(thread)
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
49
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
50 The setup phase begins after the target IP address has been resolved and all
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
51 threads have been initialized but not yet started.
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
52
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
53 setup() is called once for each thread and receives a userdata object
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
54 representing the thread.
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
55
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
56 thread.addr - get or set the thread's server address
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
57 thread:get(name) - get the value of a global in the thread's env
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
58 thread:set(name, value) - set the value of a global in the thread's env
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
59 thread:stop() - stop the thread
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
60
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
61 Only boolean, nil, number, and string values or tables of the same may be
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
62 transfered via get()/set() and thread:stop() can only be called while the
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
63 thread is running.
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
64
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
65 Running
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
66
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
67 function init(args)
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
68 function delay()
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
69 function request()
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
70 function response(status, headers, body)
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
71
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
72 The running phase begins with a single call to init(), followed by
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
73 a call to request() and response() for each request cycle.
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
74
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
75 The init() function receives any extra command line arguments for the
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
76 script which must be separated from wrk arguments with "--".
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
77
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
78 delay() returns the number of milliseconds to delay sending the next
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
79 request.
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
80
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
81 request() returns a string containing the HTTP request. Building a new
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
82 request each time is expensive, when testing a high performance server
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
83 one solution is to pre-generate all requests in init() and do a quick
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
84 lookup in request().
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
85
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
86 response() is called with the HTTP response status, headers, and body.
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
87 Parsing the headers and body is expensive, so if the response global is
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
88 nil after the call to init() wrk will ignore the headers and body.
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
89
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
90 Done
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
91
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
92 function done(summary, latency, requests)
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
93
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
94 The done() function receives a table containing result data, and two
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
95 statistics objects representing the per-request latency and per-thread
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
96 request rate. Duration and latency are microsecond values and rate is
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
97 measured in requests per second.
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
98
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
99 latency.min -- minimum value seen
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
100 latency.max -- maximum value seen
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
101 latency.mean -- average value seen
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
102 latency.stdev -- standard deviation
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
103 latency:percentile(99.0) -- 99th percentile value
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
104 latency(i) -- raw value and count
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
105
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
106 summary = {
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
107 duration = N, -- run duration in microseconds
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
108 requests = N, -- total completed requests
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
109 bytes = N, -- total bytes received
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
110 errors = {
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
111 connect = N, -- total socket connection errors
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
112 read = N, -- total socket read errors
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
113 write = N, -- total socket write errors
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
114 status = N, -- total HTTP status codes > 399
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
115 timeout = N -- total request timeouts
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
116 }
94705b5986b3 [ThirdParty] Added WRK and luajit for load testing.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
117 }