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 -w, --window-bits=<N>
60 Sets the stream level initial window size to (2**<N>)-1. For
61 QUIC, <N> is capped to 26 (roughly 64MiB).
62 Default: 30
64 -W, --connection-window-bits=<N>
66 Sets the connection level initial window size to
67 (2**<N>)-1.
68 Default: 30
70 -H, --header=<HEADER>
72 Add/Override a header to the requests.
73 --ciphers=<SUITE>
75 Set allowed cipher list for TLSv1.2 or ealier. The format
76 of the string is described in OpenSSL ciphers(1).
77 Default:
79 ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256
80 --tls13-ciphers=<SUITE>
82 Set allowed cipher list for TLSv1.3. The format of the string
83 is described in OpenSSL ciphers(1).
84 Default:
86 TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_CCM_SHA256
87 -p, --no-tls-proto=<PROTOID>
89 Specify ALPN identifier of the protocol to be used when access‐
90 ing http URI without SSL/TLS. Available protocols: h2c and
91 http/1.1
92 Default: h2c
94 -d, --data=<PATH>
96 Post FILE to server. The request method is changed to POST.
97 For http/1.1 connection, if -d is used, the maximum number
98 of in-flight pipelined requests is set to 1.
99 -r, --rate=<N>
101 Specifies the fixed rate at which connections are cre‐
102 ated. The rate must be a positive integer, represent‐
103 ing the number of connections to be made per rate period.
104 The maximum number of connections to be made is given in
105 -c option. This rate will be distributed among threads
106 as evenly as possible. For example, with -t2 and -r4,
107 each thread gets 2 connections per period. When the rate is
108 0, the program will run as it normally does, creating connec‐
109 tions at whatever variable rate it wants. The default value
110 for this option is 0. -r and -D are mutually exclusive.
111 --rate-period=<DURATION>
113 Specifies the time period between creating connections. The
114 period must be a positive number, representing the length of
115 the period in time. This option is ignored if the rate option
116 is not used. The default value for this option is 1s.
117 -D, --duration=<DURATION>
119 Specifies the main duration for the measurements in case of tim‐
120 ing-based benchmarking. -D and -r are mutually exclusive.
121 --warm-up-time=<DURATION>
123 Specifies the time period before starting the actual mea‐
124 surements, in case of timing-based benchmarking. Needs to
125 provided along with -D option.
126 -T, --connection-active-timeout=<DURATION>
128 Specifies the maximum time that h2load is willing to keep a
129 connection open, regardless of the activity on said connec‐
130 tion. <DURATION> must be a positive integer, specifying the
131 amount of time to wait. When no timeout value is set (either
132 active or inactive), h2load will keep a connection open in‐
133 definitely, waiting for a response.
134 -N, --connection-inactivity-timeout=<DURATION>
136 Specifies the amount of time that h2load is willing to wait to
137 see activity on a given connection. <DURATION> must be a
138 positive integer, specifying the amount of time to wait.
139 When no timeout value is set (either active or inactive),
140 h2load will keep a connection open indefinitely, waiting for a
141 response.
142 --timing-script-file=<PATH>
144 Path of a file containing one or more lines separated by EOLs.
145 Each script line is composed of two tab-separated fields. The
146 first field represents the time offset from the start of execu‐
147 tion, expressed as a positive value of milliseconds with mi‐
148 crosecond resolution. The second field represents the URI.
149 This option will disable URIs getting from command-line. If
150 '-' is given as <PATH>, script lines will be read from stdin.
151 Script lines are used in order for each client. If -n is
152 given, it must be less than or equal to the number of script
153 lines, larger values are clamped to the number of script lines.
154 If -n is not given, the number of requests will default to the
155 number of script lines. The scheme, host and port defined in
156 the first URI are used solely. Values contained in other
157 URIs, if present, are ignored. Definition of a base URI
158 overrides all scheme, host or port values.
159 --timing-script-file and --rps are mutually exclusive.
160 -B, --base-uri=(<URI>|unix:<PATH>)
162 Specify URI from which the scheme, host and port will be used
163 for all requests. The base URI overrides all values de‐
164 fined either at the command line or inside input files. If
165 argument starts with "unix:", then the rest of the argument
166 will be treated as UNIX domain socket path. The connection
167 is made through that path instead of TCP. In this case,
168 scheme is inferred from the first URI appeared in the com‐
169 mand line or inside input files as usual.
170 --npn-list=<LIST>
172 Comma delimited list of ALPN protocol identifier sorted in the
173 order of preference. That means most desirable protocol comes
174 first. This is used in both ALPN and NPN. The parameter
175 must be delimited by a single comma only and any white spaces
176 are treated as a part of protocol string.
177 Default: h2,h2-16,h2-14,http/1.1
179 --h1 Short hand for --npn-list=http/1.1
181 --no-tls-proto=http/1.1, which effectively force
182 http/1.1 for both http and https URI.
183 --header-table-size=<SIZE>
185 Specify decoder header table size.
186 Default: 4K
188 --encoder-header-table-size=<SIZE>
190 Specify encoder header table size. The decoder (server) speci‐
191 fies the maximum dynamic table size it accepts. Then the
192 negotiated dynamic table size is the minimum of this option
193 value and the value which server specified.
194 Default: 4K
196 --log-file=<PATH>
198 Write per-request information to a file as tab-separated col‐
199 umns: start time as microseconds since epoch; HTTP status
200 code; microseconds until end of response. More columns may be
201 added later. Rows are ordered by end-of- response time when
202 using one worker thread, but may appear slightly out of or‐
203 der with multiple threads due to buffering. Status code is -1
204 for failed streams.
205 --qlog-file-base=<PATH>
207 Enable qlog output and specify base file name for qlogs. Qlog
208 is emitted for each connection. For a given base name
209 "base", each output file name becomes "base.M.N.qlog" where M
210 is worker ID and N is client ID (e.g. "base.0.3.qlog"). Only
211 effective in QUIC runs.
212 --connect-to=<HOST>[:<PORT>]
214 Host and port to connect instead of using the authority in
215 <URI>.
216 --rps=<N>
218 Specify request per second for each client. --rps and
219 --timing-script-file are mutually exclusive.
220 --groups=<GROUPS>
222 Specify the supported groups.
223 Default: X25519:P-256:P-384:P-521
225 --no-udp-gso
227 Disable UDP GSO.
228 --max-udp-payload-size=<SIZE>
230 Specify the maximum outgoing UDP datagram payload size.
231 -v, --verbose
233 Output debug information.
234 --version
236 Display version information and exit.
237 -h, --help
239 Display this help and exit.
240 The <SIZE> argument is an integer and an optional unit (e.g., 10K is 10
242 * 1024). Units are K, M and G (powers of 1024).
243 The <DURATION> argument is an integer and an optional unit (e.g., 1s is
245 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms
246 (hours, minutes, seconds and milliseconds, respectively). If a unit is
247 omitted, a second is used as unit.
248
250 requests
251 total The number of requests h2load was instructed to make.
253 started
255 The number of requests h2load has started.
256 done The number of requests completed.
258 succeeded
260 The number of requests completed successfully. Only HTTP
261 status code 2xx or3xx are considered as success.
262 failed The number of requests failed, including HTTP level fail‐
264 ures (non-successful HTTP status code).
265 errored
267 The number of requests failed, except for HTTP level
268 failures. This is the subset of the number reported in
269 failed and most likely the network level failures or
270 stream was reset by RST_STREAM.
271 timeout
273 The number of requests whose connection timed out before
274 they were completed. This is the subset of the
275 number reported in errored.
276 status codes
278 The number of status code h2load received.
279 traffic
281 total The number of bytes received from the server "on the
283 wire". If requests were made via TLS, this value is the
284 number of decrypted bytes.
285 headers
287 The number of response header bytes from the server
288 without decompression. The space savings shows effi‐
289 ciency of header compression. Let decompressed(headers)
290 to the number of bytes used for header fields after de‐
291 compression. The space savings is calculated by (1 -
292 headers / decompressed(headers)) * 100. For HTTP/1.1,
293 this is usually 0.00%, since it does not have header
294 compression. For HTTP/2, it shows some insightful num‐
295 bers.
296 data The number of response body bytes received from the
298 server.
299 time for request
301 min The minimum time taken for request and response.
303 max The maximum time taken for request and response.
305 mean The mean time taken for request and response.
307 sd The standard deviation of the time taken for request and
309 response.
310 +/- sd The fraction of the number of requests within standard
312 deviation range (mean +/- sd) against total number of
313 successful requests.
314 time for connect
316 min The minimum time taken to connect to a server including
318 TLS handshake.
319 max The maximum time taken to connect to a server including
321 TLS handshake.
322 mean The mean time taken to connect to a server including TLS
324 handshake.
325 sd The standard deviation of the time taken to connect to a
327 server.
328 +/- sd The fraction of the number of connections within
330 standard deviation range (mean +/- sd) against total
331 number of successful connections.
332 time for 1st byte (of (decrypted in case of TLS) application data)
334 min The minimum time taken to get 1st byte from a server.
336 max The maximum time taken to get 1st byte from a server.
338 mean The mean time taken to get 1st byte from a server.
340 sd The standard deviation of the time taken to get 1st byte
342 from a server.
343 +/- sd The fraction of the number of connections within standard
345 deviation range (mean +/- sd) against total number of
346 successful connections.
347 req/s
349 min The minimum request per second among all clients.
351 max The maximum request per second among all clients.
353 mean The mean request per second among all clients.
355 sd The standard deviation of request per second among all
357 clients. server.
358 +/- sd The fraction of the number of connections within standard
360 deviation range (mean +/- sd) against total number of
361 successful connections.
362
364 h2load sets large flow control window by default, and effectively dis‐
365 ables flow control to avoid under utilization of server performance.
366 To set smaller flow control window, use -w and -W options. For exam‐
367 ple, use -w16 -W16 to set default window size described in HTTP/2 pro‐
368 tocol specification.
369
371 nghttp(1), nghttpd(1), nghttpx(1)
372
374 Tatsuhiro Tsujikawa
375
377 2012, 2015, 2016, Tatsuhiro Tsujikawa
3781.46.0 Oct 19, 2021 H2LOAD(1)