Report: Add data
[csit.git] / resources / tools / wrk / doc / wrk_lld.rst
1 Onboarding of wrk as a http traffic generator in CSIT
2 -----------------------------------------------------
3
4 wrk is a modern HTTP benchmarking tool capable of generating significant
5 load when run on a single multi-core CPU.
6
7 An optional LuaJIT script can perform HTTP request generation, response
8 processing, and custom reporting.
9
10
11 wrk installation on TG node
12 '''''''''''''''''''''''''''
13
14 **Procedure**
15
16     #. Check if wrk is installed on the TG node.
17     #. If not, install it.
18
19 **wrk installation**
20
21 ::
22
23     # Install pre-requisites:
24     sudo apt-get install build-essential libssl-dev git -y
25
26     # Get the specified version:
27     wget ${WRK_DWNLD_PATH}/${WRK_TAR}
28     tar xzf ${WRK_TAR}
29     cd wrk-${WRK_VERSION}
30
31     # Build the wrk:
32     cd wrk
33     make
34
35     # Move the executable to somewhere in the PATH, e.q:
36     sudo cp wrk /usr/local/bin
37
38
39 wrk traffic profile
40 '''''''''''''''''''
41
42 **The traffic profile can include these items:**
43
44     - List of URLs - mandatory,
45     - The first CPU used to run wrk - mandatory,
46     - Number of CPUs used for wrk - mandatory,
47     - Test duration - mandatory,
48     - Number of threads - mandatory,
49     - Number of connections - mandatory,
50     - LuaJIT script - optional, defaults to no script,
51     - HTTP header - optional, defaults to no header,
52     - Latency - optional, defaults to False,
53     - Timeout - optional, defaults to wrk default.
54
55 **List of URLs**
56
57 List of URLs for requests. Each URL is requested in a separate instance of wrk.
58 Type: list
59
60 *Example:*
61
62 ::
63
64     urls:
65       - "http://192.168.1.1/1kB.bin"
66       - "http://192.168.1.2/1kB.bin"
67       - "http://192.168.1.3/1kB.bin"
68
69 **The first CPU used to run wrk**
70 The first CPU used to run wrk. The other CPUs follow this one.
71 Type: integer
72
73 *Example:*
74
75 ::
76
77     first-cpu: 1
78
79 **Number of CPUs used for wrk**
80
81 The number of CPUs used for wrk. The number of CPUs must be a multiplication
82 of the number of URLs.
83 Type: integer
84
85 *Example:*
86
87 ::
88
89     cpus: 6
90
91 .. note::
92
93     The combinations of URLs and a number of CPUs create following use cases:
94
95         - One URL and one CPU - One instance of wrk sends one request (URL) via
96           one NIC
97         - One URL and n CPUs - n instances of wrk send the same request (URL)
98           via one or more NICs
99         - n URLs and n CPUs - n instances of wrk send n requests (URL) via one
100           or more NICs
101         - n URLs and m CPUs, m = a * n - m instances of wrk send n requests
102           (URL) via one or more NICs
103
104 **Test duration**
105
106 Duration of the test in seconds.
107 Type: integer
108
109 *Example:*
110
111 ::
112
113     duration: 30
114
115 **Number of threads**
116
117 Total number of threads to use by wrk to send traffic.
118 Type: integer
119
120 *Example:*
121
122 ::
123
124     nr-of-threads: 1
125
126 **Number of connections**
127
128 Total number of HTTP connections to keep open with each thread handling
129 N = connections / threads.
130 Type: integer
131
132 *Example:*
133
134 ::
135
136     nr-of-connections: 50
137
138 **LuaJIT script**
139
140 Path to LuaJIT script.
141 Type: string
142
143 For more information see: https://github.com/wg/wrk/blob/master/SCRIPTING
144
145 *Example:*
146
147 ::
148
149     script: "scripts/report.lua"
150
151 **HTTP header**
152
153 HTTP header to add to request.
154 Type: string (taken as it is) or dictionary
155
156 *Example:*
157
158 ::
159
160     # Dictionary:
161     header:
162       Connection: "close"
163
164 or
165
166 ::
167
168     # String:
169     header: "Connection: close"
170
171 **Latency**
172
173 Print detailed latency statistics.
174 Type: boolean
175
176 *Example:*
177
178 ::
179
180     latency: False
181
182 **Timeout**
183
184 Record a timeout if a response is not received within this amount of time.
185 Type: integer
186
187 ::
188
189     timeout: 5
190
191 **Examples of a wrk traffic profile**
192
193 *Get the number of connections per second:*
194
195 - Use 3 CPUs to send 3 different requests via 3 NICs.
196 - The test takes 30 seconds.
197 - wrk sends traffic in one thread per CPU.
198 - There will be open max 50 connection at the same time.
199 - The header is set to 'Connection: "close"' so wrk opens separate connection
200   for each request. Then the number of requests equals to the number of
201   connections.
202 - Timeout for responses from the server is set to 5 seconds.
203
204 ::
205
206     urls:
207       - "http://192.168.1.1/0B.bin"
208       - "http://192.168.1.2/0B.bin"
209       - "http://192.168.1.3/0B.bin"
210     cpus: 3
211     duration: 30
212     nr-of-threads: 1
213     nr-of-connections: 50
214     header:
215       Connection: "close"
216     timeout: 5
217
218 *Get the number of requests per second:*
219
220 - Use 3 CPUs to send 3 different requests via 3 NICs.
221 - The test takes 30 seconds.
222 - wrk sends traffic in one thread per CPU.
223 - There will be max 50 concurrent open connections.
224
225 ::
226
227     urls:
228       - "http://192.168.1.1/1kB.bin"
229       - "http://192.168.1.2/1kB.bin"
230       - "http://192.168.1.3/1kB.bin"
231     cpus: 3
232     duration: 30
233     nr-of-threads: 1
234     nr-of-connections: 50
235
236 *Get the bandwidth:*
237
238 - Use 3 CPUs to send 3 different requests via 3 NICs.
239 - The test takes 30 seconds.
240 - wrk sends traffic in one thread per CPU.
241 - There will be open max 50 connection at the same time.
242 - Timeout for responses from the server is set to 5 seconds.
243
244 ::
245
246     urls:
247       - "http://192.168.1.1/1MB.bin"
248       - "http://192.168.1.2/1MB.bin"
249       - "http://192.168.1.3/1MB.bin"
250     cpus: 3
251     duration: 30
252     nr-of-threads: 1
253     nr-of-connections: 50
254     timeout: 5
255
256
257 Running wrk
258 '''''''''''
259
260 **Suite setup phase**
261
262 CSIT framework checks if wrk is installed on the TG node. If not, or if the
263 installation is forced, it installs it on the TG node.
264
265 *Procedure:*
266
267     #. Make sure TRex is stopped.
268     #. Bind used TG interfaces to corresponding drivers (defined in the topology
269        file).
270     #. If the wrk installation is forced:
271
272         - Destroy existing wrk
273
274     #. If the wrk installation is not forced:
275
276         - Check if wrk is installed.
277         - If installed, exit.
278
279     #. Clone wrk from git (https://github.com/wg/wrk.git)
280     #. Build wrk.
281     #. Copy the executable to /usr/local/bin so it is in the PATH.
282
283 **Test phase**
284
285 *Procedure:*
286
287 #. Read the wrk traffic profile.
288 #. Verify the profile.
289 #. Use the information from the profile to set the wrk parameters.
290 #. Run wrk.
291 #. Read the output.
292 #. Evaluate and log the output.
293