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.


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
    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 StringDescription
%%the percent sign
%Alocal address (e.g.
%bsize of the response body in bytes
%Hrequest protocol as sent by the client (e.g. HTTP/1.1)
%hremote address (e.g.
%lremote logname (always -)
%mrequest method (e.g. GET, POST)
%plocal port (%{local}p is a synonym that is supported since version 2.2)
%{remote}premote port (since version 2.2)
%qquery string (? is prepended if exists, otherwise an empty string)
%rrequest line (e.g. GET / HTTP/1.1)
%sstatus code sent to client (e.g. 200)
%<sstatus code received from upstream (or initially generated)
%ttime when the request was received in format: [02/Jan/2006:15:04:05 -0700]
%{FORMAT}ttime when the request was received using the specified format. FORMAT should be an argument to strftime, or one of:
secnumber of seconds since Epoch
msecnumber of milliseconds since Epoch
usecnumber of microseconds since Epoch
msec_fracmillisecond fraction
usec_fracmicrosecond 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.
%Urequested URL path, not including the query string
%uremote user if the request was authenticated (always -)
%Vrequested server name (or the default server name if not specified by the client)
%vcanonical server name
%{VARNAME}erequest environment variable (since version 2.3; see Logging Arbitrary Variable)
%{HEADERNAME}ivalue of the given request header (e.g. %{user-agent}i)
%{HEADERNAME}ovalue of the given response header sent to client (e.g. %{set-cookie}o)
%<{HEADERNAME}ovalue of the response header received from upstream (or initially generated)
%{NAME}xvarious 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
connect-timetime spent to establish the connection (i.e. since connection gets accept(2)-ed until first octet of the request is received)
request-header-timetime spent receiving request headers
request-body-timetime spent receiving request body
request-total-timesum of request-header-time and request-body-time
process-timetime spent after receiving request, before starting to send response
response-timetime spent sending response
durationsum of request-total-time, process-time, response-time
Connection (since v2.0)
connection-id64-bit internal ID assigned to every client connection
ssl.protocol-versionSSL protocol version obtained from SSL_get_version
ssl.session-reused1 if the SSL session was reused, or 0 if not1
ssl.session-idbase64-encoded value of the session id used for resuming the session (since v2.2)
ssl.ciphername of the cipher suite being used, obtained from SSL_CIPHER_get_name
ssl.cipher-bitsstrength of the cipher suite in bits
HTTP/2 (since v2.0)
http2.stream-idstream ID
http2.priority.receivedcolon-concatenated values of exclusive, parent, weight
http2.priority.received.exclusiveexclusive bit of the most recent priority specified by the client
http2.priority.received.parentparent stream ID of the most recent priority specified by the client
http2.priority.received.weightweight of the most recent priority specified by the client
errorrequest-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).

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


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