doc/h2load.1

   1 .\" Man page generated from reStructuredText.
   2 .
   3 .TH "H2LOAD" "1" "Jun 02, 2020" "1.41.0" "nghttp2"
   4 .SH NAME
   5 h2load \- HTTP/2 benchmarking tool
   6 .
   7 .nr rst2man-indent-level 0
   8 .
   9 .de1 rstReportMargin
  10 \\$1 \\n[an-margin]
  11 level \\n[rst2man-indent-level]
  12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
  13 -
  14 \\n[rst2man-indent0]
  15 \\n[rst2man-indent1]
  16 \\n[rst2man-indent2]
  17 ..
  18 .de1 INDENT
  19 .\" .rstReportMargin pre:
  20 . RS \\$1
  21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
  22 . nr rst2man-indent-level +1
  23 .\" .rstReportMargin post:
  24 ..
  25 .de UNINDENT
  26 . RE
  27 .\" indent \\n[an-margin]
  28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
  29 .nr rst2man-indent-level -1
  30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
  31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
  32 ..
  33 .SH SYNOPSIS
  34 .sp
  35 \fBh2load\fP [OPTIONS]... [URI]...
  36 .SH DESCRIPTION
  37 .sp
  38 benchmarking tool for HTTP/2 server
  39 .INDENT 0.0
  40 .TP
  41 .B <URI>
  42 Specify URI to access.   Multiple URIs can be specified.
  43 URIs are used  in this order for each  client.  All URIs
  44 are used, then  first URI is used and then  2nd URI, and
  45 so  on.  The  scheme, host  and port  in the  subsequent
  46 URIs, if present,  are ignored.  Those in  the first URI
  47 are used solely.  Definition of a base URI overrides all
  48 scheme, host or port values.
  49 .UNINDENT
  50 .SH OPTIONS
  51 .INDENT 0.0
  52 .TP
  53 .B \-n, \-\-requests=<N>
  54 Number of  requests across all  clients.  If it  is used
  55 with \fI\%\-\-timing\-script\-file\fP option,  this option specifies
  56 the number of requests  each client performs rather than
  57 the number of requests  across all clients.  This option
  58 is ignored if timing\-based  benchmarking is enabled (see
  59 \fI\%\-\-duration\fP option).
  60 .sp
  61 Default: \fB1\fP
  62 .UNINDENT
  63 .INDENT 0.0
  64 .TP
  65 .B \-c, \-\-clients=<N>
  66 Number  of concurrent  clients.   With  \fI\%\-r\fP option,  this
  67 specifies the maximum number of connections to be made.
  68 .sp
  69 Default: \fB1\fP
  70 .UNINDENT
  71 .INDENT 0.0
  72 .TP
  73 .B \-t, \-\-threads=<N>
  74 Number of native threads.
  75 .sp
  76 Default: \fB1\fP
  77 .UNINDENT
  78 .INDENT 0.0
  79 .TP
  80 .B \-i, \-\-input\-file=<PATH>
  81 Path of a file with multiple URIs are separated by EOLs.
  82 This option will disable URIs getting from command\-line.
  83 If \(aq\-\(aq is given as <PATH>, URIs will be read from stdin.
  84 URIs are used  in this order for each  client.  All URIs
  85 are used, then  first URI is used and then  2nd URI, and
  86 so  on.  The  scheme, host  and port  in the  subsequent
  87 URIs, if present,  are ignored.  Those in  the first URI
  88 are used solely.  Definition of a base URI overrides all
  89 scheme, host or port values.
  90 .UNINDENT
  91 .INDENT 0.0
  92 .TP
  93 .B \-m, \-\-max\-concurrent\-streams=<N>
  94 Max  concurrent  streams  to issue  per  session.   When
  95 http/1.1  is used,  this  specifies the  number of  HTTP
  96 pipelining requests in\-flight.
  97 .sp
  98 Default: \fB1\fP
  99 .UNINDENT
 100 .INDENT 0.0
 101 .TP
 102 .B \-w, \-\-window\-bits=<N>
 103 Sets the stream level initial window size to (2**<N>)\-1.
 104 .sp
 105 Default: \fB30\fP
 106 .UNINDENT
 107 .INDENT 0.0
 108 .TP
 109 .B \-W, \-\-connection\-window\-bits=<N>
 110 Sets  the  connection  level   initial  window  size  to
 111 (2**<N>)\-1.
 112 .sp
 113 Default: \fB30\fP
 114 .UNINDENT
 115 .INDENT 0.0
 116 .TP
 117 .B \-H, \-\-header=<HEADER>
 118 Add/Override a header to the requests.
 119 .UNINDENT
 120 .INDENT 0.0
 121 .TP
 122 .B \-\-ciphers=<SUITE>
 123 Set allowed  cipher list.  The  format of the  string is
 124 described in OpenSSL ciphers(1).
 125 .sp
 126 Default: \fBECDHE\-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\fP
 127 .UNINDENT
 128 .INDENT 0.0
 129 .TP
 130 .B \-p, \-\-no\-tls\-proto=<PROTOID>
 131 Specify ALPN identifier of the  protocol to be used when
 132 accessing http URI without SSL/TLS.
 133 Available protocols: h2c and http/1.1
 134 .sp
 135 Default: \fBh2c\fP
 136 .UNINDENT
 137 .INDENT 0.0
 138 .TP
 139 .B \-d, \-\-data=<PATH>
 140 Post FILE to  server.  The request method  is changed to
 141 POST.   For  http/1.1 connection,  if  \fI\%\-d\fP  is used,  the
 142 maximum number of in\-flight pipelined requests is set to
 143 1.
 144 .UNINDENT
 145 .INDENT 0.0
 146 .TP
 147 .B \-r, \-\-rate=<N>
 148 Specifies  the  fixed  rate  at  which  connections  are
 149 created.   The   rate  must   be  a   positive  integer,
 150 representing the  number of  connections to be  made per
 151 rate period.   The maximum  number of connections  to be
 152 made  is  given  in  \fI\%\-c\fP   option.   This  rate  will  be
 153 distributed among  threads as  evenly as  possible.  For
 154 example,  with   \fI\%\-t\fP2  and   \fI\%\-r\fP4,  each  thread   gets  2
 155 connections per period.  When the rate is 0, the program
 156 will run  as it  normally does, creating  connections at
 157 whatever variable rate it  wants.  The default value for
 158 this option is 0.  \fI\%\-r\fP and \fI\%\-D\fP are mutually exclusive.
 159 .UNINDENT
 160 .INDENT 0.0
 161 .TP
 162 .B \-\-rate\-period=<DURATION>
 163 Specifies the time  period between creating connections.
 164 The period  must be a positive  number, representing the
 165 length of the period in time.  This option is ignored if
 166 the rate option is not used.  The default value for this
 167 option is 1s.
 168 .UNINDENT
 169 .INDENT 0.0
 170 .TP
 171 .B \-D, \-\-duration=<N>
 172 Specifies the main duration for the measurements in case
 173 of timing\-based  benchmarking.  \fI\%\-D\fP  and \fI\%\-r\fP  are mutually
 174 exclusive.
 175 .UNINDENT
 176 .INDENT 0.0
 177 .TP
 178 .B \-\-warm\-up\-time=<DURATION>
 179 Specifies the  time  period  before  starting the actual
 180 measurements, in  case  of  timing\-based benchmarking.
 181 Needs to provided along with \fI\%\-D\fP option.
 182 .UNINDENT
 183 .INDENT 0.0
 184 .TP
 185 .B \-T, \-\-connection\-active\-timeout=<DURATION>
 186 Specifies  the maximum  time that  h2load is  willing to
 187 keep a  connection open,  regardless of the  activity on
 188 said connection.  <DURATION> must be a positive integer,
 189 specifying the amount of time  to wait.  When no timeout
 190 value is  set (either  active or inactive),  h2load will
 191 keep  a  connection  open indefinitely,  waiting  for  a
 192 response.
 193 .UNINDENT
 194 .INDENT 0.0
 195 .TP
 196 .B \-N, \-\-connection\-inactivity\-timeout=<DURATION>
 197 Specifies the amount  of time that h2load  is willing to
 198 wait to see activity  on a given connection.  <DURATION>
 199 must  be a  positive integer,  specifying the  amount of
 200 time  to wait.   When no  timeout value  is set  (either
 201 active or inactive), h2load  will keep a connection open
 202 indefinitely, waiting for a response.
 203 .UNINDENT
 204 .INDENT 0.0
 205 .TP
 206 .B \-\-timing\-script\-file=<PATH>
 207 Path of a file containing one or more lines separated by
 208 EOLs.  Each script line is composed of two tab\-separated
 209 fields.  The first field represents the time offset from
 210 the start of execution, expressed as a positive value of
 211 milliseconds  with microsecond  resolution.  The  second
 212 field represents the URI.  This option will disable URIs
 213 getting from  command\-line.  If \(aq\-\(aq is  given as <PATH>,
 214 script lines will be read  from stdin.  Script lines are
 215 used in order for each client.   If \fI\%\-n\fP is given, it must
 216 be less  than or  equal to the  number of  script lines,
 217 larger values are clamped to the number of script lines.
 218 If \fI\%\-n\fP is not given,  the number of requests will default
 219 to the  number of  script lines.   The scheme,  host and
 220 port defined in  the first URI are  used solely.  Values
 221 contained  in  other  URIs,  if  present,  are  ignored.
 222 Definition of a  base URI overrides all  scheme, host or
 223 port values.
 224 .UNINDENT
 225 .INDENT 0.0
 226 .TP
 227 .B \-B, \-\-base\-uri=(<URI>|unix:<PATH>)
 228 Specify URI from which the scheme, host and port will be
 229 used  for  all requests.   The  base  URI overrides  all
 230 values  defined either  at  the command  line or  inside
 231 input files.  If argument  starts with "unix:", then the
 232 rest  of the  argument will  be treated  as UNIX  domain
 233 socket path.   The connection is made  through that path
 234 instead of TCP.   In this case, scheme  is inferred from
 235 the first  URI appeared  in the  command line  or inside
 236 input files as usual.
 237 .UNINDENT
 238 .INDENT 0.0
 239 .TP
 240 .B \-\-npn\-list=<LIST>
 241 Comma delimited list of  ALPN protocol identifier sorted
 242 in the  order of preference.  That  means most desirable
 243 protocol comes  first.  This  is used  in both  ALPN and
 244 NPN.  The parameter must be  delimited by a single comma
 245 only  and any  white spaces  are  treated as  a part  of
 246 protocol string.
 247 .sp
 248 Default: \fBh2,h2\-16,h2\-14,http/1.1\fP
 249 .UNINDENT
 250 .INDENT 0.0
 251 .TP
 252 .B \-\-h1
 253 Short        hand         for        \fI\%\-\-npn\-list\fP=http/1.1
 254 \fI\%\-\-no\-tls\-proto\fP=http/1.1,    which   effectively    force
 255 http/1.1 for both http and https URI.
 256 .UNINDENT
 257 .INDENT 0.0
 258 .TP
 259 .B \-\-header\-table\-size=<SIZE>
 260 Specify decoder header table size.
 261 .sp
 262 Default: \fB4K\fP
 263 .UNINDENT
 264 .INDENT 0.0
 265 .TP
 266 .B \-\-encoder\-header\-table\-size=<SIZE>
 267 Specify encoder header table size.  The decoder (server)
 268 specifies  the maximum  dynamic table  size it  accepts.
 269 Then the negotiated dynamic table size is the minimum of
 270 this option value and the value which server specified.
 271 .sp
 272 Default: \fB4K\fP
 273 .UNINDENT
 274 .INDENT 0.0
 275 .TP
 276 .B \-\-log\-file=<PATH>
 277 Write per\-request information to a file as tab\-separated
 278 columns: start  time as  microseconds since  epoch; HTTP
 279 status code;  microseconds until end of  response.  More
 280 columns may be added later.  Rows are ordered by end\-of\-
 281 response  time when  using  one worker  thread, but  may
 282 appear slightly  out of order with  multiple threads due
 283 to buffering.  Status code is \-1 for failed streams.
 284 .UNINDENT
 285 .INDENT 0.0
 286 .TP
 287 .B \-\-connect\-to=<HOST>[:<PORT>]
 288 Host and port to connect  instead of using the authority
 289 in <URI>.
 290 .UNINDENT
 291 .INDENT 0.0
 292 .TP
 293 .B \-v, \-\-verbose
 294 Output debug information.
 295 .UNINDENT
 296 .INDENT 0.0
 297 .TP
 298 .B \-\-version
 299 Display version information and exit.
 300 .UNINDENT
 301 .INDENT 0.0
 302 .TP
 303 .B \-h, \-\-help
 304 Display this help and exit.
 305 .UNINDENT
 306 .sp
 307 The <SIZE> argument is an integer and an optional unit (e.g., 10K is
 308 10 * 1024).  Units are K, M and G (powers of 1024).
 309 .sp
 310 The <DURATION> argument is an integer and an optional unit (e.g., 1s
 311 is 1 second and 500ms is 500 milliseconds).  Units are h, m, s or ms
 312 (hours, minutes, seconds and milliseconds, respectively).  If a unit
 313 is omitted, a second is used as unit.
 314 .SH OUTPUT
 315 .INDENT 0.0
 316 .TP
 317 .B requests
 318 .INDENT 7.0
 319 .TP
 320 .B total
 321 The number of requests h2load was instructed to make.
 322 .TP
 323 .B started
 324 The number of requests h2load has started.
 325 .TP
 326 .B done
 327 The number of requests completed.
 328 .TP
 329 .B succeeded
 330 The number of requests completed successfully.  Only HTTP status
 331 code 2xx or3xx are considered as success.
 332 .TP
 333 .B failed
 334 The number of requests failed, including HTTP level failures
 335 (non\-successful HTTP status code).
 336 .TP
 337 .B errored
 338 The number of requests failed, except for HTTP level failures.
 339 This is the subset of the number reported in \fBfailed\fP and most
 340 likely the network level failures or stream was reset by
 341 RST_STREAM.
 342 .TP
 343 .B timeout
 344 The number of requests whose connection timed out before they were
 345 completed.   This  is  the  subset   of  the  number  reported  in
 346 \fBerrored\fP\&.
 347 .UNINDENT
 348 .TP
 349 .B status codes
 350 The number of status code h2load received.
 351 .TP
 352 .B traffic
 353 .INDENT 7.0
 354 .TP
 355 .B total
 356 The number of bytes received from the server "on the wire".  If
 357 requests were made via TLS, this value is the number of decrypted
 358 bytes.
 359 .TP
 360 .B headers
 361 The  number  of response  header  bytes  from the  server  without
 362 decompression.  The  \fBspace savings\fP shows efficiency  of header
 363 compression.  Let \fBdecompressed(headers)\fP to the number of bytes
 364 used for header fields after decompression.  The \fBspace savings\fP
 365 is calculated  by (1 \- \fBheaders\fP  / \fBdecompressed(headers)\fP) *
 366 100.  For HTTP/1.1, this is usually  0.00%, since it does not have
 367 header compression.  For HTTP/2, it shows some insightful numbers.
 368 .TP
 369 .B data
 370 The number of response body bytes received from the server.
 371 .UNINDENT
 372 .TP
 373 .B time for request
 374 .INDENT 7.0
 375 .TP
 376 .B min
 377 The minimum time taken for request and response.
 378 .TP
 379 .B max
 380 The maximum time taken for request and response.
 381 .TP
 382 .B mean
 383 The mean time taken for request and response.
 384 .TP
 385 .B sd
 386 The standard deviation of the time taken for request and response.
 387 .TP
 388 .B +/\- sd
 389 The fraction of the number of requests within standard deviation
 390 range (mean +/\- sd) against total number of successful requests.
 391 .UNINDENT
 392 .TP
 393 .B time for connect
 394 .INDENT 7.0
 395 .TP
 396 .B min
 397 The minimum time taken to connect to a server including TLS
 398 handshake.
 399 .TP
 400 .B max
 401 The maximum time taken to connect to a server including TLS
 402 handshake.
 403 .TP
 404 .B mean
 405 The mean time taken to connect to a server including TLS
 406 handshake.
 407 .TP
 408 .B sd
 409 The standard deviation of the time taken to connect to a server.
 410 .TP
 411 .B +/\- sd
 412 The  fraction  of  the   number  of  connections  within  standard
 413 deviation range (mean  +/\- sd) against total  number of successful
 414 connections.
 415 .UNINDENT
 416 .TP
 417 .B time for 1st byte (of (decrypted in case of TLS) application data)
 418 .INDENT 7.0
 419 .TP
 420 .B min
 421 The minimum time taken to get 1st byte from a server.
 422 .TP
 423 .B max
 424 The maximum time taken to get 1st byte from a server.
 425 .TP
 426 .B mean
 427 The mean time taken to get 1st byte from a server.
 428 .TP
 429 .B sd
 430 The standard deviation of the time taken to get 1st byte from a
 431 server.
 432 .TP
 433 .B +/\- sd
 434 The fraction of the number of connections within standard
 435 deviation range (mean +/\- sd) against total number of successful
 436 connections.
 437 .UNINDENT
 438 .TP
 439 .B req/s
 440 .INDENT 7.0
 441 .TP
 442 .B min
 443 The minimum request per second among all clients.
 444 .TP
 445 .B max
 446 The maximum request per second among all clients.
 447 .TP
 448 .B mean
 449 The mean request per second among all clients.
 450 .TP
 451 .B sd
 452 The standard deviation of request per second among all clients.
 453 server.
 454 .TP
 455 .B +/\- sd
 456 The fraction of the number of connections within standard
 457 deviation range (mean +/\- sd) against total number of successful
 458 connections.
 459 .UNINDENT
 460 .UNINDENT
 461 .SH FLOW CONTROL
 462 .sp
 463 h2load sets large flow control window by default, and effectively
 464 disables flow control to avoid under utilization of server
 465 performance.  To set smaller flow control window, use \fI\%\-w\fP and
 466 \fI\%\-W\fP options.  For example, use \fB\-w16 \-W16\fP to set default
 467 window size described in HTTP/2 protocol specification.
 468 .SH SEE ALSO
 469 .sp
 470 \fBnghttp(1)\fP, \fBnghttpd(1)\fP, \fBnghttpx(1)\fP
 471 .SH AUTHOR
 472 Tatsuhiro Tsujikawa
 473 .SH COPYRIGHT
 474 2012, 2015, 2016, Tatsuhiro Tsujikawa
 475 .\" Generated by docutils manpage writer.
 476 .