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
26 requests 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.
61 Default: 30
63 -W, --connection-window-bits=<N>
65 Sets the connection level initial window size to
66 (2**<N>)-1.
67 Default: 30
69 -H, --header=<HEADER>
71 Add/Override a header to the requests.
72 --ciphers=<SUITE>
74 Set allowed cipher list. The format of the string is
75 described in OpenSSL ciphers(1).
76 Default:
78 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
79 -p, --no-tls-proto=<PROTOID>
81 Specify ALPN identifier of the protocol to be used when access‐
82 ing http URI without SSL/TLS. Available protocols: h2c and
83 http/1.1
84 Default: h2c
86 -d, --data=<PATH>
88 Post FILE to server. The request method is changed to POST.
89 For http/1.1 connection, if -d is used, the maximum number
90 of in-flight pipelined requests is set to 1.
91 -r, --rate=<N>
93 Specifies the fixed rate at which connections are cre‐
94 ated. The rate must be a positive integer, represent‐
95 ing the number of connections to be made per rate period.
96 The maximum number of connections to be made is given in
97 -c option. This rate will be distributed among threads
98 as evenly as possible. For example, with -t2 and -r4,
99 each thread gets 2 connections per period. When the rate is
100 0, the program will run as it normally does, creating connec‐
101 tions at whatever variable rate it wants. The default value
102 for this option is 0. -r and -D are mutually exclusive.
103 --rate-period=<DURATION>
105 Specifies the time period between creating connections. The
106 period must be a positive number, representing the length of
107 the period in time. This option is ignored if the rate option
108 is not used. The default value for this option is 1s.
109 -D, --duration=<N>
111 Specifies the main duration for the measurements in case of tim‐
112 ing-based benchmarking. -D and -r are mutually exclusive.
113 --warm-up-time=<DURATION>
115 Specifies the time period before starting the actual mea‐
116 surements, in case of timing-based benchmarking. Needs to
117 provided along with -D option.
118 -T, --connection-active-timeout=<DURATION>
120 Specifies the maximum time that h2load is willing to keep a
121 connection open, regardless of the activity on said connec‐
122 tion. <DURATION> must be a positive integer, specifying the
123 amount of time to wait. When no timeout value is set (either
124 active or inactive), h2load will keep a connection open
125 indefinitely, waiting for a response.
126 -N, --connection-inactivity-timeout=<DURATION>
128 Specifies the amount of time that h2load is willing to wait to
129 see activity on a given connection. <DURATION> must be a
130 positive integer, specifying the amount of time to wait.
131 When no timeout value is set (either active or inactive),
132 h2load will keep a connection open indefinitely, waiting for a
133 response.
134 --timing-script-file=<PATH>
136 Path of a file containing one or more lines separated by EOLs.
137 Each script line is composed of two tab-separated fields. The
138 first field represents the time offset from the start of execu‐
139 tion, expressed as a positive value of milliseconds with
140 microsecond resolution. The second field represents the URI.
141 This option will disable URIs getting from command-line. If
142 '-' is given as <PATH>, script lines will be read from stdin.
143 Script lines are used in order for each client. If -n is
144 given, it must be less than or equal to the number of script
145 lines, larger values are clamped to the number of script lines.
146 If -n is not given, the number of requests will default to the
147 number of script lines. The scheme, host and port defined in
148 the first URI are used solely. Values contained in other
149 URIs, if present, are ignored. Definition of a base URI
150 overrides all scheme, host or port values.
151 -B, --base-uri=(<URI>|unix:<PATH>)
153 Specify URI from which the scheme, host and port will be used
154 for all requests. The base URI overrides all values
155 defined either at the command line or inside input files.
156 If argument starts with "unix:", then the rest of the argu‐
157 ment will be treated as UNIX domain socket path. The con‐
158 nection is made through that path instead of TCP. In this
159 case, scheme is inferred from the first URI appeared in the
160 command line or inside input files as usual.
161 --npn-list=<LIST>
163 Comma delimited list of ALPN protocol identifier sorted in the
164 order of preference. That means most desirable protocol comes
165 first. This is used in both ALPN and NPN. The parameter
166 must be delimited by a single comma only and any white spaces
167 are treated as a part of protocol string.
168 Default: h2,h2-16,h2-14,http/1.1
170 --h1 Short hand for --npn-list=http/1.1
172 --no-tls-proto=http/1.1, which effectively force
173 http/1.1 for both http and https URI.
174 --header-table-size=<SIZE>
176 Specify decoder header table size.
177 Default: 4K
179 --encoder-header-table-size=<SIZE>
181 Specify encoder header table size. The decoder (server) speci‐
182 fies the maximum dynamic table size it accepts. Then the
183 negotiated dynamic table size is the minimum of this option
184 value and the value which server specified.
185 Default: 4K
187 --log-file=<PATH>
189 Write per-request information to a file as tab-separated col‐
190 umns: start time as microseconds since epoch; HTTP status
191 code; microseconds until end of response. More columns may be
192 added later. Rows are ordered by end-of- response time when
193 using one worker thread, but may appear slightly out of
194 order with multiple threads due to buffering. Status code is
195 -1 for failed streams.
196 --connect-to=<HOST>[:<PORT>]
198 Host and port to connect instead of using the authority in
199 <URI>.
200 -v, --verbose
202 Output debug information.
203 --version
205 Display version information and exit.
206 -h, --help
208 Display this help and exit.
209 The <SIZE> argument is an integer and an optional unit (e.g., 10K is 10
211 * 1024). Units are K, M and G (powers of 1024).
212 The <DURATION> argument is an integer and an optional unit (e.g., 1s is
214 1 second and 500ms is 500 milliseconds). Units are h, m, s or ms
215 (hours, minutes, seconds and milliseconds, respectively). If a unit is
216 omitted, a second is used as unit.
217
219 requests
220 total The number of requests h2load was instructed to make.
222 started
224 The number of requests h2load has started.
225 done The number of requests completed.
227 succeeded
229 The number of requests completed successfully. Only HTTP
230 status code 2xx or3xx are considered as success.
231 failed The number of requests failed, including HTTP level fail‐
233 ures (non-successful HTTP status code).
234 errored
236 The number of requests failed, except for HTTP level
237 failures. This is the subset of the number reported in
238 failed and most likely the network level failures or
239 stream was reset by RST_STREAM.
240 timeout
242 The number of requests whose connection timed out before
243 they were completed. This is the subset of the
244 number reported in errored.
245 status codes
247 The number of status code h2load received.
248 traffic
250 total The number of bytes received from the server "on the
252 wire". If requests were made via TLS, this value is the
253 number of decrypted bytes.
254 headers
256 The number of response header bytes from the server
257 without decompression. The space savings shows effi‐
258 ciency of header compression. Let decompressed(headers)
259 to the number of bytes used for header fields after
260 decompression. The space savings is calculated by (1 -
261 headers / decompressed(headers)) * 100. For HTTP/1.1,
262 this is usually 0.00%, since it does not have header
263 compression. For HTTP/2, it shows some insightful num‐
264 bers.
265 data The number of response body bytes received from the
267 server.
268 time for request
270 min The minimum time taken for request and response.
272 max The maximum time taken for request and response.
274 mean The mean time taken for request and response.
276 sd The standard deviation of the time taken for request and
278 response.
279 +/- sd The fraction of the number of requests within standard
281 deviation range (mean +/- sd) against total number of
282 successful requests.
283 time for connect
285 min The minimum time taken to connect to a server including
287 TLS handshake.
288 max The maximum time taken to connect to a server including
290 TLS handshake.
291 mean The mean time taken to connect to a server including TLS
293 handshake.
294 sd The standard deviation of the time taken to connect to a
296 server.
297 +/- sd The fraction of the number of connections within
299 standard deviation range (mean +/- sd) against total
300 number of successful connections.
301 time for 1st byte (of (decrypted in case of TLS) application data)
303 min The minimum time taken to get 1st byte from a server.
305 max The maximum time taken to get 1st byte from a server.
307 mean The mean time taken to get 1st byte from a server.
309 sd The standard deviation of the time taken to get 1st byte
311 from a server.
312 +/- sd The fraction of the number of connections within standard
314 deviation range (mean +/- sd) against total number of
315 successful connections.
316 req/s
318 min The minimum request per second among all clients.
320 max The maximum request per second among all clients.
322 mean The mean request per second among all clients.
324 sd The standard deviation of request per second among all
326 clients. server.
327 +/- sd The fraction of the number of connections within standard
329 deviation range (mean +/- sd) against total number of
330 successful connections.
331
333 h2load sets large flow control window by default, and effectively dis‐
334 ables flow control to avoid under utilization of server performance.
335 To set smaller flow control window, use -w and -W options. For exam‐
336 ple, use -w16 -W16 to set default window size described in HTTP/2 pro‐
337 tocol specification.
338
340 nghttp(1), nghttpd(1), nghttpx(1)
341
343 Tatsuhiro Tsujikawa
344
346 2012, 2015, 2016, Tatsuhiro Tsujikawa
3471.43.0 Feb 02, 2021 H2LOAD(1)