H2O

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

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.

The latter approach (i.e. |) needs to be used for rotating the logs. This is because the log file is opened (or the command that emits the log is spawned) before dropping privileges so that it can be owned by root or any other user; therefore it cannot be reopened by the server process itself once it starts running.

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 total-time same as duration (since v2.3) Proxy Timings (since v2.3) Name Description proxy.idle-time time spent after receiving request, before starting to connect to the upstream proxy.connect-time time spent to establish the connection (including SSL handshake) proxy.request-time time spent sending request (header and body) proxy.process-time time spent after sending request, before starting to receive response proxy.response-time time spent receiving response proxy.total-time sum of proxy-request-time, proxy-process-time, proxy-response-time Proxy (since v2.3) Name Description proxy.request-bytes number of bytes used by the proxy handler for sending the request (above TLS layer) proxy.request-bytes-header number of bytes used by the proxy handler for sending the request header (above TLS layer) proxy.request-bytes-body number of bytes used by the proxy handler for sending the request body (above TLS layer) proxy.response-bytes number of bytes used by the proxy handler for receiving the response (above TLS layer) proxy.response-bytes-header number of bytes used by the proxy handler for receiving the response header (above TLS layer) proxy.response-bytes-body number of bytes used by the proxy handler for receiving the response body (above TLS layer) 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 ssl.server-name hostname provided in Server Name Indication (SNI) extension, if any Upstream Proxy Connection (since v2.3) Name Description proxy.ssl.protocol-version SSL protocol version obtained from SSL_get_version proxy.ssl.session-reused 1 if the SSL session was reused, or 0 if not proxy.ssl.cipher name of the cipher suite being used, obtained from SSL_CIPHER_get_name proxy.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

Copyright © 2015-2023 DeNA Co., Ltd. et al.