manpagez: man pages & more
man h2load(1)
Home | html | info | man
h2load(1)                           nghttp2                          h2load(1)




NAME

       h2load - HTTP/2 benchmarking tool


SYNOPSIS

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


DESCRIPTION

       benchmarking tool for HTTP/2 server

       <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.  Defini-
              tion of a base URI overrides all scheme, host or port values.


OPTIONS

       -n, --requests=<N>
              Number of  requests across all  clients.  If it   is  used  with
              --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 tim-
              ing-based  benchmarking is enabled (see --duration option).

              Default: 1

       -c, --clients=<N>
              Number  of concurrent  clients.   With  -r option,  this  speci-
              fies the maximum number of connections to be made.

              Default: 1

       -t, --threads=<N>
              Number of native threads.

              Default: 1

       -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.

       -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

       -w, --window-bits=<N>
              Sets the stream level initial window size to (2**<N>)-1.

              Default: 30

       -W, --connection-window-bits=<N>
              Sets   the   connection   level    initial   window   size    to
              (2**<N>)-1.

              Default: 30

       -H, --header=<HEADER>
              Add/Override a header to the requests.

       --ciphers=<SUITE>
              Set  allowed   cipher  list.   The   format  of  the   string is
              described in OpenSSL ciphers(1).

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

       -p, --no-tls-proto=<PROTOID>
              Specify ALPN identifier of the  protocol to be used when access-
              ing  http  URI  without  SSL/TLS.   Available protocols: h2c and
              http/1.1

              Default: h2c

       -d, --data=<PATH>
              Post FILE to  server.  The request method  is changed  to  POST.
              For   http/1.1 connection,  if  -d  is used,  the maximum number
              of in-flight pipelined requests is set to 1.

       -r, --rate=<N>
              Specifies  the  fixed  rate  at  which   connections   are  cre-
              ated.   The   rate  must   be  a   positive  integer, represent-
              ing the  number of  connections to be   made  per  rate  period.
              The  maximum   number  of connections  to be made  is  given  in
              -c   option.   This  rate  will  be distributed  among   threads
              as   evenly  as  possible.  For example,  with   -t2  and   -r4,
              each  thread   gets  2 connections per period.  When the rate is
              0, the program will run  as it  normally does, creating  connec-
              tions at whatever variable rate it  wants.   The  default  value
              for this option is 0.  -r and -D are mutually exclusive.

       --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.

       -D, --duration=<N>
              Specifies the main duration for the measurements in case of tim-
              ing-based  benchmarking.  -D  and -r  are mutually exclusive.

       --warm-up-time=<DURATION>
              Specifies  the   time   period  before  starting the actual mea-
              surements, in  case  of  timing-based  benchmarking.   Needs  to
              provided along with -D 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  connec-
              tion.   <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.

       -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.

       --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 execu-
              tion, 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  -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  -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.

       -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   argu-
              ment  will   be treated  as UNIX  domain socket path.   The con-
              nection 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.

       --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

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

       --header-table-size=<SIZE>
              Specify decoder header table size.

              Default: 4K

       --encoder-header-table-size=<SIZE>
              Specify encoder header table size.  The decoder (server)  speci-
              fies   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

       --log-file=<PATH>
              Write  per-request  information  to a file as tab-separated col-
              umns: 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.

       --connect-to=<HOST>[:<PORT>]
              Host  and  port  to  connect   instead of using the authority in
              <URI>.

       -v, --verbose
              Output debug information.

       --version
              Display version information and exit.

       -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.


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 or3x are considered as success.

              failed The number of requests failed, including HTTP level fail-
                     ures (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  effi-
                     ciency  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  num-
                     bers.

              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 dis-
       ables flow control to avoid under utilization  of  server  performance.
       To  set  smaller flow control window, use -w and -W options.  For exam-
       ple, use -w16 -W16 to set default window size described in HTTP/2  pro-
       tocol specification.


SEE ALSO

       nghttp(1), nghttpd(1), nghttpx(1)


AUTHOR

       Tatsuhiro Tsujikawa


COPYRIGHT

       2012, 2015, 2016, Tatsuhiro Tsujikawa



1.41.0                           Jun 02, 2020                        h2load(1)

nghttp2 1.41.0 - Generated Tue Jun 2 11:13:47 CDT 2020
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.