1H2LOAD(1) nghttp2 H2LOAD(1)
2
6 h2load - HTTP/2 benchmarking tool
7
9 h2load [OPTIONS]... [URI]...
10
12 benchmarking tool for HTTP/2 server
13 <URI> Specify URI to access. Multiple URIs can be specified. URIs
15 are used in this order for each client. All URIs are used,
16 then first URI is used and then 2nd URI, and so on. The
17 scheme, host and port in the subsequent URIs, if present,
18 are ignored. Those in the first URI are used solely. Defini‐
19 tion of a base URI overrides all scheme, host or port values.
20
22 -n, --requests=<N>
23 Number of requests across all clients. If it is used with
24 --timing-script-file option, this option specifies the number
25 of requests each client performs rather than the number of re‐
26 quests across all clients. This option is ignored if tim‐
27 ing-based benchmarking is enabled (see --duration option).
28 Default: 1
30 -c, --clients=<N>
32 Number of concurrent clients. With -r option, this speci‐
33 fies the maximum number of connections to be made.
34 Default: 1
36 -t, --threads=<N>
38 Number of native threads.
39 Default: 1
41 -i, --input-file=<PATH>
43 Path of a file with multiple URIs are separated by EOLs. This
44 option will disable URIs getting from command-line. If '-' is
45 given as <PATH>, URIs will be read from stdin. URIs are used
46 in this order for each client. All URIs are used, then first
47 URI is used and then 2nd URI, and so on. The scheme, host
48 and port in the subsequent URIs, if present, are ignored.
49 Those in the first URI are used solely. Definition of a base
50 URI overrides all scheme, host or port values.
51 -m, --max-concurrent-streams=<N>
53 Max concurrent streams to issue per session. When
54 http/1.1 is used, this specifies the number of HTTP pipe‐
55 lining requests in-flight.
56 Default: 1
58 -f, --max-frame-size=<SIZE>
60 Maximum frame size that the local endpoint is willing to re‐
61 ceive.
62 Default: 16K
64 -w, --window-bits=<N>
66 Sets the stream level initial window size to (2**<N>)-1. For
67 QUIC, <N> is capped to 26 (roughly 64MiB).
68 Default: 30
70 -W, --connection-window-bits=<N>
72 Sets the connection level initial window size to
73 (2**<N>)-1.
74 Default: 30
76 -H, --header=<HEADER>
78 Add/Override a header to the requests.
79 --ciphers=<SUITE>
81 Set allowed cipher list for TLSv1.2 or earlier. The format
82 of the string is described in OpenSSL ciphers(1).
83 Default:
85 ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
86 --tls13-ciphers=<SUITE>
88 Set allowed cipher list for TLSv1.3. The format of the string
89 is described in OpenSSL ciphers(1).
90 Default:
92 TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_CCM_SHA256
93 -p, --no-tls-proto=<PROTOID>
95 Specify ALPN identifier of the protocol to be used when access‐
96 ing http URI without SSL/TLS. Available protocols: h2c and
97 http/1.1
98 Default: h2c
100 -d, --data=<PATH>
102 Post FILE to server. The request method is changed to POST.
103 For http/1.1 connection, if -d is used, the maximum number
104 of in-flight pipelined requests is set to 1.
105 -r, --rate=<N>
107 Specifies the fixed rate at which connections are cre‐
108 ated. The rate must be a positive integer, represent‐
109 ing the number of connections to be made per rate period.
110 The maximum number of connections to be made is given in
111 -c option. This rate will be distributed among threads
112 as evenly as possible. For example, with -t2 and -r4,
113 each thread gets 2 connections per period. When the rate is
114 0, the program will run as it normally does, creating connec‐
115 tions at whatever variable rate it wants. The default value
116 for this option is 0. -r and -D are mutually exclusive.
117 --rate-period=<DURATION>
119 Specifies the time period between creating connections. The
120 period must be a positive number, representing the length of
121 the period in time. This option is ignored if the rate option
122 is not used. The default value for this option is 1s.
123 -D, --duration=<DURATION>
125 Specifies the main duration for the measurements in case of tim‐
126 ing-based benchmarking. -D and -r are mutually exclusive.
127 --warm-up-time=<DURATION>
129 Specifies the time period before starting the actual mea‐
130 surements, in case of timing-based benchmarking. Needs to
131 provided along with -D option.
132 -T, --connection-active-timeout=<DURATION>
134 Specifies the maximum time that h2load is willing to keep a
135 connection open, regardless of the activity on said connec‐
136 tion. <DURATION> must be a positive integer, specifying the
137 amount of time to wait. When no timeout value is set (either
138 active or inactive), h2load will keep a connection open in‐
139 definitely, waiting for a response.
140 -N, --connection-inactivity-timeout=<DURATION>
142 Specifies the amount of time that h2load is willing to wait to
143 see activity on a given connection. <DURATION> must be a
144 positive integer, specifying the amount of time to wait.
145 When no timeout value is set (either active or inactive),
146 h2load will keep a connection open indefinitely, waiting for a
147 response.
148 --timing-script-file=<PATH>
150 Path of a file containing one or more lines separated by EOLs.
151 Each script line is composed of two tab-separated fields. The
152 first field represents the time offset from the start of execu‐
153 tion, expressed as a positive value of milliseconds with mi‐
154 crosecond resolution. The second field represents the URI.
155 This option will disable URIs getting from command-line. If
156 '-' is given as <PATH>, script lines will be read from stdin.
157 Script lines are used in order for each client. If -n is
158 given, it must be less than or equal to the number of script
159 lines, larger values are clamped to the number of script lines.
160 If -n is not given, the number of requests will default to the
161 number of script lines. The scheme, host and port defined in
162 the first URI are used solely. Values contained in other
163 URIs, if present, are ignored. Definition of a base URI
164 overrides all scheme, host or port values.
165 --timing-script-file and --rps are mutually exclusive.
166 -B, --base-uri=(<URI>|unix:<PATH>)
168 Specify URI from which the scheme, host and port will be used
169 for all requests. The base URI overrides all values de‐
170 fined either at the command line or inside input files. If
171 argument starts with "unix:", then the rest of the argument
172 will be treated as UNIX domain socket path. The connection
173 is made through that path instead of TCP. In this case,
174 scheme is inferred from the first URI appeared in the com‐
175 mand line or inside input files as usual.
176 --npn-list=<LIST>
178 Comma delimited list of ALPN protocol identifier sorted in the
179 order of preference. That means most desirable protocol comes
180 first. This is used in both ALPN and NPN. The parameter
181 must be delimited by a single comma only and any white spaces
182 are treated as a part of protocol string.
183 Default: h2,h2-16,h2-14,http/1.1
185 --h1 Short hand for --npn-list=http/1.1
187 --no-tls-proto=http/1.1, which effectively force
188 http/1.1 for both http and https URI.
189 --header-table-size=<SIZE>
191 Specify decoder header table size.
192 Default: 4K
194 --encoder-header-table-size=<SIZE>
196 Specify encoder header table size. The decoder (server) speci‐
197 fies the maximum dynamic table size it accepts. Then the
198 negotiated dynamic table size is the minimum of this option
199 value and the value which server specified.
200 Default: 4K
202 --log-file=<PATH>
204 Write per-request information to a file as tab-separated col‐
205 umns: start time as microseconds since epoch; HTTP status
206 code; microseconds until end of response. More columns may be
207 added later. Rows are ordered by end-of- response time when
208 using one worker thread, but may appear slightly out of or‐
209 der with multiple threads due to buffering. Status code is -1
210 for failed streams.
211 --qlog-file-base=<PATH>
213 Enable qlog output and specify base file name for qlogs. Qlog
214 is emitted for each connection. For a given base name
215 "base", each output file name becomes
216 "base.M.N.sqlog" where M is worker ID and N is client ID (e.g.
217 "base.0.3.sqlog"). Only effective in QUIC runs.
218 --connect-to=<HOST>[:<PORT>]
220 Host and port to connect instead of using the authority in
221 <URI>.
222 --rps=<N>
224 Specify request per second for each client. --rps and
225 --timing-script-file are mutually exclusive.
226 --groups=<GROUPS>
228 Specify the supported groups.
229 Default: X25519:P-256:P-384:P-521
231 --no-udp-gso
233 Disable UDP GSO.
234 --max-udp-payload-size=<SIZE>
236 Specify the maximum outgoing UDP datagram payload size.
237 --ktls Enable ktls.
239 -v, --verbose
241 Output debug information.
242 --version
244 Display version information and exit.
245 -h, --help
247 Display this help and exit.
248 The <SIZE> argument is an integer and an optional unit (e.g., 10K is 10
250 * 1024). Units are K, M and G (powers of 1024).
251 The <DURATION> argument is an integer and an optional unit (e.g., 1s is
253 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms
254 (hours, minutes, seconds and milliseconds, respectively). If a unit is
255 omitted, a second is used as unit.
256
258 requests
259 total The number of requests h2load was instructed to make.
261 started
263 The number of requests h2load has started.
264 done The number of requests completed.
266 succeeded
268 The number of requests completed successfully. Only HTTP
269 status code 2xx or3xx are considered as success.
270 failed The number of requests failed, including HTTP level fail‐
272 ures (non-successful HTTP status code).
273 errored
275 The number of requests failed, except for HTTP level
276 failures. This is the subset of the number reported in
277 failed and most likely the network level failures or
278 stream was reset by RST_STREAM.
279 timeout
281 The number of requests whose connection timed out before
282 they were completed. This is the subset of the
283 number reported in errored.
284 status codes
286 The number of status code h2load received.
287 traffic
289 total The number of bytes received from the server "on the
291 wire". If requests were made via TLS, this value is the
292 number of decrypted bytes.
293 headers
295 The number of response header bytes from the server
296 without decompression. The space savings shows effi‐
297 ciency of header compression. Let decompressed(headers)
298 to the number of bytes used for header fields after de‐
299 compression. The space savings is calculated by (1 -
300 headers / decompressed(headers)) * 100. For HTTP/1.1,
301 this is usually 0.00%, since it does not have header
302 compression. For HTTP/2, it shows some insightful num‐
303 bers.
304 data The number of response body bytes received from the
306 server.
307 time for request
309 min The minimum time taken for request and response.
311 max The maximum time taken for request and response.
313 mean The mean time taken for request and response.
315 sd The standard deviation of the time taken for request and
317 response.
318 +/- sd The fraction of the number of requests within standard
320 deviation range (mean +/- sd) against total number of
321 successful requests.
322 time for connect
324 min The minimum time taken to connect to a server including
326 TLS handshake.
327 max The maximum time taken to connect to a server including
329 TLS handshake.
330 mean The mean time taken to connect to a server including TLS
332 handshake.
333 sd The standard deviation of the time taken to connect to a
335 server.
336 +/- sd The fraction of the number of connections within
338 standard deviation range (mean +/- sd) against total
339 number of successful connections.
340 time for 1st byte (of (decrypted in case of TLS) application data)
342 min The minimum time taken to get 1st byte from a server.
344 max The maximum time taken to get 1st byte from a server.
346 mean The mean time taken to get 1st byte from a server.
348 sd The standard deviation of the time taken to get 1st byte
350 from a server.
351 +/- sd The fraction of the number of connections within standard
353 deviation range (mean +/- sd) against total number of
354 successful connections.
355 req/s
357 min The minimum request per second among all clients.
359 max The maximum request per second among all clients.
361 mean The mean request per second among all clients.
363 sd The standard deviation of request per second among all
365 clients. server.
366 +/- sd The fraction of the number of connections within standard
368 deviation range (mean +/- sd) against total number of
369 successful connections.
370
372 h2load sets large flow control window by default, and effectively dis‐
373 ables flow control to avoid under utilization of server performance.
374 To set smaller flow control window, use -w and -W options. For exam‐
375 ple, use -w16 -W16 to set default window size described in HTTP/2 pro‐
376 tocol specification.
377
379 nghttp(1), nghttpd(1), nghttpx(1)
380
382 Tatsuhiro Tsujikawa
383
385 2012, 2015, 2016, Tatsuhiro Tsujikawa
3861.51.0 Nov 13, 2022 H2LOAD(1)