# H2O

the optimized HTTP/1.x, HTTP/2 server

×
Powered by Oktavia

## Configure > Access Log Directives

This document describes the configuration directives of the access_log handler.

### `"access-log"`

Description:

  The directive sets the path and optionally the format of the access log.

  If the supplied argument is a scalar, it is treated as the path of the log file, or if the value starts with a `|`, it is treated as a command to which the log should be emitted.

  Example. Emit access log to file

      access-log: /path/to/access-log-file

  Example. Emit access log through pipe

      access-log: "| rotatelogs /path/to/access-log-file.%Y%m%d 86400"

  If the supplied argument is a mapping, its `path` property is considered as the path of the log file or the pipe command, and the `format` property is treated as the format of the log file. Starting from version 2.2, `escape` property can be used to specify the escape sequence that should be used to emit unsafe octets.

  Two forms of escape sequences are supported. If `apache` is specified as the value of the `escape` property, unsafe octets are emitted in the form of `\xNN`, where N is a hexadecimal number in lower case. If `json` is specified, unsafe octets are emitted in the form of `\u00NN`. `apache` is the default escape method.

  Example. Emit access log to file using Common Log Format

      access-log:
          path: /path/to/access-log-file
          format: "%h %l %u %t \"%r\" %s %b"
          escape: apache

  The list of format strings recognized by H2O is as follows.

  Format String | Description
  --- | ---
  `%%` | the percent sign
  `%A` | local address (e.g. `4.5.6.7`)
  `%b` | size of the response body in bytes
  `%H` | request protocol as sent by the client (e.g. `HTTP/1.1`)
  `%h` | remote address (e.g. `1.2.3.4`)
  `%l` | remote logname (always `-`)
  `%m` | request method (e.g. `GET`, `POST`)
  `%p` | local port (`%{local}p` is a synonym that is supported since version 2.2)
  `%{remote}p` | remote port (since version 2.2)
  `%q` | query string (`?` is prepended if exists, otherwise an empty string)
  `%r` | request line (e.g. `GET / HTTP/1.1`)
  `%s` | status code sent to client (e.g. `200`)
  `%<s` | status code received from upstream (or initially generated)
  `%t` | time when the request was received in format: `[02/Jan/2006:15:04:05 -0700]`

  `%{FORMAT}t`

  time when the request was received using the specified format. `FORMAT` should be an argument to `strftime`, or one of:

  `sec` | number of seconds since Epoch
  `msec` | number of milliseconds since Epoch
  `usec` | number of microseconds since Epoch
  `msec_frac` | millisecond fraction
  `usec_frac` | microsecond fraction

  As an example, it is possible to log timestamps in millisecond resolution using `%{%Y/%m/%d:%H:%M:%S}t.%{msec_frac}t`, which results in a timestamp like `2006-01-02:15:04:05.000`.

  `%U` | requested URL path, not including the query string
  `%u` | remote user if the request was authenticated (always `-`)
  `%V` | requested server name (or the default server name if not specified by the client)
  `%v` | canonical server name
  `%{VARNAME}e` | request environment variable (since version 2.3; see Logging Arbitrary Variable)
  `%{HEADERNAME}i` | value of the given request header (e.g. `%{user-agent}i`)
  `%{HEADERNAME}o` | value of the given response header sent to client (e.g. `%{set-cookie}o`)
  `%<{HEADERNAME}o` | value of the response header received from upstream (or initially generated)

  `%{NAME}x`

  various extensions. `NAME` must be one listed in the following tables. A dash (`-`) is emitted if the directive is not applicable to the request being logged.

  Access Timings
  Name | Description
  --- | ---
  `connect-time` | time spent to establish the connection (i.e. since connection gets `accept(2)`-ed until first octet of the request is received)
  `request-header-time` | time spent receiving request headers
  `request-body-time` | time spent receiving request body
  `request-total-time` | sum of `request-header-time` and `request-body-time`
  `process-time` | time spent after receiving request, before starting to send response
  `response-time` | time spent sending response
  `duration` | sum of `request-total-time`, `process-time`, `response-time`

  Connection (since v2.0)
  Name | Description
  --- | ---
  `connection-id` | 64-bit internal ID assigned to every client connection
  `ssl.protocol-version` | SSL protocol version obtained from `SSL_get_version`
  `ssl.session-reused` | `1` if the SSL session was reused, or `0` if not1
  `ssl.session-id` | base64-encoded value of the session id used for resuming the session (since v2.2)
  `ssl.cipher` | name of the cipher suite being used, obtained from SSL_CIPHER_get_name
  `ssl.cipher-bits` | strength of the cipher suite in bits

  HTTP/2 (since v2.0)
  Name | Description
  --- | ---
  `http2.stream-id` | stream ID
  `http2.priority.received` | colon-concatenated values of exclusive, parent, weight
  `http2.priority.received.exclusive` | exclusive bit of the most recent priority specified by the client
  `http2.priority.received.parent` | parent stream ID of the most recent priority specified by the client
  `http2.priority.received.weight` | weight of the most recent priority specified by the client

  Miscellaneous
  Name | Description
  --- | ---
  `error` | request-level errors. Unless specified otherwise by using the `error-log.emit-request-errors` directive, the same messages are emitted to the error-log. (since v2.1)

  The default format is `%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-agent}i"`, a.k.a. the NCSA extended/combined log format.

  Note that you may need to quote (and escape) the format string as required by YAML (see Yaml Cookbook).

Level:
  global, host, path, extension
See also:
  `error-log` `error-log.emit-request-errors`

### Notes:

1. A single SSL connection may transfer more than one HTTP request.