summaryrefslogtreecommitdiffstats
path: root/doc/h2load.1.rst
blob: 0f65849d6830a2bb32a229f7526678f15c1ada0b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
.. GENERATED by help2rst.py.  DO NOT EDIT DIRECTLY.

.. program:: h2load

h2load(1)
=========

SYNOPSIS
--------

**h2load** [OPTIONS]... [URI]...

DESCRIPTION
-----------

benchmarking tool for HTTP/2 server

.. describe:: <URI>

    Specify URI to access.   Multiple URIs can be specified.
    URIs are used  in this order for each  client.  All URIs
    are used, then  first URI is used and then  2nd URI, and
    so  on.  The  scheme, host  and port  in the  subsequent
    URIs, if present,  are ignored.  Those in  the first URI
    are used solely.  Definition of a base URI overrides all
    scheme, host or port values.

OPTIONS
-------

.. option:: -n, --requests=<N>

    Number of  requests across all  clients.  If it  is used
    with :option:`--timing-script-file` option,  this option specifies
    the number of requests  each client performs rather than
    the number of requests  across all clients.  This option
    is ignored if timing-based  benchmarking is enabled (see
    :option:`--duration` option).

    Default: ``1``

.. option:: -c, --clients=<N>

    Number  of concurrent  clients.   With  :option:`-r` option,  this
    specifies the maximum number of connections to be made.

    Default: ``1``

.. option:: -t, --threads=<N>

    Number of native threads.

    Default: ``1``

.. option:: -i, --input-file=<PATH>

    Path of a file with multiple URIs are separated by EOLs.
    This option will disable URIs getting from command-line.
    If '-' is given as <PATH>, URIs will be read from stdin.
    URIs are used  in this order for each  client.  All URIs
    are used, then  first URI is used and then  2nd URI, and
    so  on.  The  scheme, host  and port  in the  subsequent
    URIs, if present,  are ignored.  Those in  the first URI
    are used solely.  Definition of a base URI overrides all
    scheme, host or port values.

.. option:: -m, --max-concurrent-streams=<N>

    Max  concurrent  streams  to issue  per  session.   When
    http/1.1  is used,  this  specifies the  number of  HTTP
    pipelining requests in-flight.

    Default: ``1``

.. option:: -f, --max-frame-size=<SIZE>

    Maximum frame size that the local endpoint is willing to
    receive.

    Default: ``16K``

.. option:: -w, --window-bits=<N>

    Sets the stream level initial window size to (2\*\*<N>)-1.
    For QUIC, <N> is capped to 26 (roughly 64MiB).

    Default: ``30``

.. option:: -W, --connection-window-bits=<N>

    Sets  the  connection  level   initial  window  size  to
    (2\*\*<N>)-1.

    Default: ``30``

.. option:: -H, --header=<HEADER>

    Add/Override a header to the requests.

.. option:: --ciphers=<SUITE>

    Set  allowed cipher  list  for TLSv1.2  or earlier.   The
    format of the string is described in OpenSSL ciphers(1).

    Default: ``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``

.. option:: --tls13-ciphers=<SUITE>

    Set allowed cipher list for  TLSv1.3.  The format of the
    string is described in OpenSSL ciphers(1).

    Default: ``TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_CCM_SHA256``

.. option:: -p, --no-tls-proto=<PROTOID>

    Specify ALPN identifier of the  protocol to be used when
    accessing http URI without SSL/TLS.
    Available protocols: h2c and http/1.1

    Default: ``h2c``

.. option:: -d, --data=<PATH>

    Post FILE to  server.  The request method  is changed to
    POST.   For  http/1.1 connection,  if  :option:`-d`  is used,  the
    maximum number of in-flight pipelined requests is set to
    1.

.. option:: -r, --rate=<N>

    Specifies  the  fixed  rate  at  which  connections  are
    created.   The   rate  must   be  a   positive  integer,
    representing the  number of  connections to be  made per
    rate period.   The maximum  number of connections  to be
    made  is  given  in  :option:`-c`   option.   This  rate  will  be
    distributed among  threads as  evenly as  possible.  For
    example,  with   :option:`-t`\2  and   :option:`-r`\4,  each  thread   gets  2
    connections per period.  When the rate is 0, the program
    will run  as it  normally does, creating  connections at
    whatever variable rate it  wants.  The default value for
    this option is 0.  :option:`-r` and :option:`\-D` are mutually exclusive.

.. option:: --rate-period=<DURATION>

    Specifies the time  period between creating connections.
    The period  must be a positive  number, representing the
    length of the period in time.  This option is ignored if
    the rate option is not used.  The default value for this
    option is 1s.

.. option:: -D, --duration=<DURATION>

    Specifies the main duration for the measurements in case
    of timing-based  benchmarking.  :option:`-D`  and :option:`\-r`  are mutually
    exclusive.

.. option:: --warm-up-time=<DURATION>

    Specifies the  time  period  before  starting the actual
    measurements, in  case  of  timing-based benchmarking.
    Needs to provided along with :option:`-D` option.

.. option:: -T, --connection-active-timeout=<DURATION>

    Specifies  the maximum  time that  h2load is  willing to
    keep a  connection open,  regardless of the  activity on
    said connection.  <DURATION> must be a positive integer,
    specifying the amount of time  to wait.  When no timeout
    value is  set (either  active or inactive),  h2load will
    keep  a  connection  open indefinitely,  waiting  for  a
    response.

.. option:: -N, --connection-inactivity-timeout=<DURATION>

    Specifies the amount  of time that h2load  is willing to
    wait to see activity  on a given connection.  <DURATION>
    must  be a  positive integer,  specifying the  amount of
    time  to wait.   When no  timeout value  is set  (either
    active or inactive), h2load  will keep a connection open
    indefinitely, waiting for a response.

.. option:: --timing-script-file=<PATH>

    Path of a file containing one or more lines separated by
    EOLs.  Each script line is composed of two tab-separated
    fields.  The first field represents the time offset from
    the start of execution, expressed as a positive value of
    milliseconds  with microsecond  resolution.  The  second
    field represents the URI.  This option will disable URIs
    getting from  command-line.  If '-' is  given as <PATH>,
    script lines will be read  from stdin.  Script lines are
    used in order for each client.   If :option:`-n` is given, it must
    be less  than or  equal to the  number of  script lines,
    larger values are clamped to the number of script lines.
    If :option:`-n` is not given,  the number of requests will default
    to the  number of  script lines.   The scheme,  host and
    port defined in  the first URI are  used solely.  Values
    contained  in  other  URIs,  if  present,  are  ignored.
    Definition of a  base URI overrides all  scheme, host or
    port   values.   :option:`--timing-script-file`   and  :option:`\--rps`   are
    mutually exclusive.

.. option:: -B, --base-uri=(<URI>|unix:<PATH>)

    Specify URI from which the scheme, host and port will be
    used  for  all requests.   The  base  URI overrides  all
    values  defined either  at  the command  line or  inside
    input files.  If argument  starts with "unix:", then the
    rest  of the  argument will  be treated  as UNIX  domain
    socket path.   The connection is made  through that path
    instead of TCP.   In this case, scheme  is inferred from
    the first  URI appeared  in the  command line  or inside
    input files as usual.

.. option:: --npn-list=<LIST>

    Comma delimited list of  ALPN protocol identifier sorted
    in the  order of preference.  That  means most desirable
    protocol comes  first.  This  is used  in both  ALPN and
    NPN.  The parameter must be  delimited by a single comma
    only  and any  white spaces  are  treated as  a part  of
    protocol string.

    Default: ``h2,h2-16,h2-14,http/1.1``

.. option:: --h1

    Short        hand         for        :option:`--npn-list`\=http/1.1
    :option:`--no-tls-proto`\=http/1.1,    which   effectively    force
    http/1.1 for both http and https URI.

.. option:: --header-table-size=<SIZE>

    Specify decoder header table size.

    Default: ``4K``

.. option:: --encoder-header-table-size=<SIZE>

    Specify encoder header table size.  The decoder (server)
    specifies  the maximum  dynamic table  size it  accepts.
    Then the negotiated dynamic table size is the minimum of
    this option value and the value which server specified.

    Default: ``4K``

.. option:: --log-file=<PATH>

    Write per-request information to a file as tab-separated
    columns: start  time as  microseconds since  epoch; HTTP
    status code;  microseconds until end of  response.  More
    columns may be added later.  Rows are ordered by end-of-
    response  time when  using  one worker  thread, but  may
    appear slightly  out of order with  multiple threads due
    to buffering.  Status code is -1 for failed streams.

.. option:: --qlog-file-base=<PATH>

    Enable qlog output and specify base file name for qlogs.
    Qlog is emitted  for each connection.  For  a given base
    name   "base",    each   output   file    name   becomes
    "base.M.N.sqlog" where M is worker ID and N is client ID
    (e.g. "base.0.3.sqlog").  Only effective in QUIC runs.

.. option:: --connect-to=<HOST>[:<PORT>]

    Host and port to connect  instead of using the authority
    in <URI>.

.. option:: --rps=<N>

    Specify request  per second for each  client.  :option:`--rps` and
    :option:`--timing-script-file` are mutually exclusive.

.. option:: --groups=<GROUPS>

    Specify the supported groups.

    Default: ``X25519:P-256:P-384:P-521``

.. option:: --no-udp-gso

    Disable UDP GSO.

.. option:: --max-udp-payload-size=<SIZE>

    Specify the maximum outgoing UDP datagram payload size.

.. option:: --ktls

    Enable ktls.

.. option:: -v, --verbose

    Output debug information.

.. option:: --version

    Display version information and exit.

.. option:: -h, --help

    Display this help and exit.



The <SIZE> argument is an integer and an optional unit (e.g., 10K is
10 * 1024).  Units are K, M and G (powers of 1024).

The <DURATION> argument is an integer and an optional unit (e.g., 1s
is 1 second and 500ms is 500 milliseconds).  Units are h, m, s or ms
(hours, minutes, seconds and milliseconds, respectively).  If a unit
is omitted, a second is used as unit.

.. _h2load-1-output:

OUTPUT
------

requests
  total
    The number of requests h2load was instructed to make.
  started
    The number of requests h2load has started.
  done
    The number of requests completed.
  succeeded
    The number of requests completed successfully.  Only HTTP status
    code 2xx or3xx are considered as success.
  failed
    The number of requests failed, including HTTP level failures
    (non-successful HTTP status code).
  errored
    The number of requests failed, except for HTTP level failures.
    This is the subset of the number reported in ``failed`` and most
    likely the network level failures or stream was reset by
    RST_STREAM.
  timeout
    The number of requests whose connection timed out before they were
    completed.   This  is  the  subset   of  the  number  reported  in
    ``errored``.

status codes
  The number of status code h2load received.

traffic
  total
    The number of bytes received from the server "on the wire".  If
    requests were made via TLS, this value is the number of decrypted
    bytes.
  headers
    The  number  of response  header  bytes  from the  server  without
    decompression.  The  ``space savings`` shows efficiency  of header
    compression.  Let ``decompressed(headers)`` to the number of bytes
    used for header fields after decompression.  The ``space savings``
    is calculated  by (1 - ``headers``  / ``decompressed(headers)``) *
    100.  For HTTP/1.1, this is usually  0.00%, since it does not have
    header compression.  For HTTP/2, it shows some insightful numbers.
  data
    The number of response body bytes received from the server.

time for request
  min
    The minimum time taken for request and response.
  max
    The maximum time taken for request and response.
  mean
    The mean time taken for request and response.
  sd
    The standard deviation of the time taken for request and response.
  +/- sd
    The fraction of the number of requests within standard deviation
    range (mean +/- sd) against total number of successful requests.

time for connect
  min
    The minimum time taken to connect to a server including TLS
    handshake.
  max
    The maximum time taken to connect to a server including TLS
    handshake.
  mean
    The mean time taken to connect to a server including TLS
    handshake.
  sd
    The standard deviation of the time taken to connect to a server.
  +/- sd
    The  fraction  of  the   number  of  connections  within  standard
    deviation range (mean  +/- sd) against total  number of successful
    connections.

time for 1st byte (of (decrypted in case of TLS) application data)
  min
    The minimum time taken to get 1st byte from a server.
  max
    The maximum time taken to get 1st byte from a server.
  mean
    The mean time taken to get 1st byte from a server.
  sd
    The standard deviation of the time taken to get 1st byte from a
    server.
  +/- sd
    The fraction of the number of connections within standard
    deviation range (mean +/- sd) against total number of successful
    connections.

req/s
  min
    The minimum request per second among all clients.
  max
    The maximum request per second among all clients.
  mean
    The mean request per second among all clients.
  sd
    The standard deviation of request per second among all clients.
    server.
  +/- sd
    The fraction of the number of connections within standard
    deviation range (mean +/- sd) against total number of successful
    connections.

FLOW CONTROL
------------

h2load sets large flow control window by default, and effectively
disables flow control to avoid under utilization of server
performance.  To set smaller flow control window, use :option:`-w` and
:option:`-W` options.  For example, use ``-w16 -W16`` to set default
window size described in HTTP/2 protocol specification.

SEE ALSO
--------

:manpage:`nghttp(1)`, :manpage:`nghttpd(1)`, :manpage:`nghttpx(1)`