<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_http_log_module"
        link="/en/docs/http/ngx_http_log_module.html"
        lang="en"
        rev="10">

<section id="summary">

<para>
The <literal>ngx_http_log_module</literal> module writes request logs
in the specified format.
</para>

<para>
Requests are logged in a context of a location where processing ends.
This may be different from the original location, if an
<link doc="ngx_http_core_module.xml" id="internal">internal
redirect</link> happens during request processing.
</para>

</section>


<section id="example" name="Example Configuration">

<para>
<example>
log_format compression '$remote_addr - $remote_user [$time_local] '
                       '"$request" $status $bytes_sent '
                       '"$http_referer" "$http_user_agent" "$gzip_ratio"';

access_log /spool/logs/nginx-access.log compression buffer=32k;
</example>
</para>

</section>


<section id="directives" name="Directives">

<directive name="access_log">
<syntax>
    <value>path</value>
    [<value>format</value>
    [<literal>buffer</literal>=<value>size</value>
    [<literal>flush</literal>=<value>time</value>]]]</syntax>
<syntax>
    <value>path</value>
    <value>format</value>
    <literal>gzip[=<value>level</value>]</literal>
    [<literal>buffer</literal>=<value>size</value>]
    [<literal>flush</literal>=<value>time</value>]</syntax>
<syntax>
    <literal>syslog:</literal><literal>server</literal>=<value>address</value>[,<value>parameter</value>=<value>value</value>]
    [<value>format</value>]</syntax>
<syntax><literal>off</literal></syntax>
<default>logs/access.log combined</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if in location</context>
<context>limit_except</context>

<para>
Sets the path, format, and configuration of the buffered log writes.
Several logs can be specified on the same level.
Logging to syslog can be configured by specifying
the “<literal>syslog:</literal>” prefix in the first parameter.
The special value <literal>off</literal> cancels all
<literal>access_log</literal> directives on the current level.
If format is not specified then the predefined format
“<literal>combined</literal>” is used.
</para>

<para>
If either the <literal>buffer</literal> or <literal>gzip</literal>
(1.3.10, 1.2.7)
parameter is used, writes to log will be buffered.
<note>
The buffer size must not exceed the size of the atomic write to a disk file.
For FreeBSD this size is unlimited.
</note>
</para>

<para>
When buffering is enabled, the data will be written to the file:
<list type="bullet">

<listitem>
if the next log line does not fit into the buffer;
</listitem>

<listitem>
if the buffered data is older than specified by the <literal>flush</literal>
parameter (1.3.10, 1.2.7);
</listitem>

<listitem>
when a worker process is <link doc="../control.xml">re-opening</link> log
files or is shutting down.
</listitem>

</list>
</para>

<para>
If the <literal>gzip</literal> parameter is used, then the buffered data will
be compressed before writing to the file.
The compression level can be set between 1 (fastest, less compression)
and 9 (slowest, best compression).
By default the buffer size is equal to 64K bytes, and the compression level
is set to 1.
Since the data is compressed in atomic blocks, the log file can be decompressed
or read by “<literal>zcat</literal>” at any time.
</para>

<para>
Example:
<example>
access_log /path/to/log.gz combined gzip flush=5m;
</example>
</para>

<para>
<note>
For gzip compression to work, nginx must be built with the zlib library.
</note>
</para>

<para>
The file path can contain variables (0.7.6+),
but such logs have some constraints:
<list type="bullet">

<listitem>
the <link doc="../ngx_core_module.xml" id="user"/>
whose credentials are used by worker processes should
have permissions to create files in a directory with
such logs;
</listitem>

<listitem>
buffered writes do not work;
</listitem>

<listitem>
a file is opened and closed for each log write.
However, since the descriptors of frequently used files can be stored
in a <link id="open_log_file_cache">cache</link>, writes during the
time specified by the <literal>valid</literal> parameter of the
<link id="open_log_file_cache"/> directive can continue to be made
to the old file.
</listitem>

<listitem>
during each log write the existence of the request’s
<link doc="ngx_http_core_module.xml" id="root">root directory</link>
is checked, and if it does not exist the log is not
created.
It is thus a good idea to specify both
<link doc="ngx_http_core_module.xml" id="root"/>
and <literal>access_log</literal> on the same level:
<example>
server {
    root       /spool/vhost/data/$host;
    access_log /spool/vhost/logs/$host;
    ...
</example>
</listitem>

</list>
</para>

<para>
The following parameters configure logging to syslog:
<list type="tag">

<tag-name><literal>server=</literal><value>address</value></tag-name>
<tag-desc>
Defines an address of a syslog server.
An address can be specified as a domain name or IP address,
and an optional port, or as a UNIX-domain socket path
specified after the “<literal>unix:</literal>” prefix.
If port is not specified, the port 514 is used.
If a domain name resolves to several IP addresses, the first resolved
address is used.
</tag-desc>

<tag-name><literal>facility=</literal><value>string</value></tag-name>
<tag-desc>
Sets facility of syslog messages, as defined in
<link url="http://tools.ietf.org/html/rfc3164#section-4.1.1">RFC 3164</link>.
Facility can be one of “<literal>kern</literal>”, “<literal>user</literal>”,
“<literal>mail</literal>”, “<literal>daemon</literal>”,
“<literal>auth</literal>”, “<literal>intern</literal>”,
“<literal>lpr</literal>”, “<literal>news</literal>”, “<literal>uucp</literal>”,
“<literal>clock</literal>”, “<literal>authpriv</literal>”,
“<literal>ftp</literal>”, “<literal>ntp</literal>”, “<literal>audit</literal>”,
“<literal>alert</literal>”, “<literal>cron</literal>”,
“<literal>local0</literal>”..“<literal>local7</literal>”.
Default is “<literal>local7</literal>”.
</tag-desc>

<tag-name><literal>severity=</literal><value>string</value></tag-name>
<tag-desc>
Sets severity of syslog messages, as defined in
<link url="http://tools.ietf.org/html/rfc3164#section-4.1.1">RFC 3164</link>.
Possible values are the same as for the second parameter (level) of the
<link doc="../ngx_core_module.xml" id="error_log"/> directive.
Default is “<literal>info</literal>”.
</tag-desc>

<tag-name><literal>tag=</literal><value>string</value></tag-name>
<tag-desc>
Sets tag of syslog messages.
Default is “<literal>nginx</literal>”.
</tag-desc>

<!--
<tag-name><literal>bare=</literal><literal>on</literal> |
<literal>off</literal></tag-name>
<tag-desc>
If enabled, messages are sent without syslog headers.
Default is <literal>off</literal>.
</tag-desc>
-->

</list>
Example syslog configuration:
<example>
access_log syslog:server=192.168.1.1;
access_log syslog:server=unix:/var/log/nginx.sock;
access_log syslog:server=[2001:db8::1]:12345,facility=local7,tag=nginx,severity=info combined;
</example>
</para>

<para>
<note>
Logging to syslog is available as part of our <commercial_version/> only.
</note>
</para>

</directive>


<directive name="log_format">
<syntax>
    <value>name</value>
    <value>string</value> ...</syntax>
<default>combined "..."</default>
<context>http</context>

<para>
Specifies format of a log.
</para>

<para>
The log format can contain common variables, and variables that
exist only at the time of a log write:
<list type="tag">

<tag-name><var>$bytes_sent</var></tag-name>
<tag-desc>
the number of bytes sent to a client
</tag-desc>

<tag-name><var>$connection</var></tag-name>
<tag-desc>
connection serial number
</tag-desc>

<tag-name><var>$connection_requests</var></tag-name>
<tag-desc>
the current number of requests made through a connection (1.1.18)
</tag-desc>

<tag-name><var>$msec</var></tag-name>
<tag-desc>
time in seconds with a milliseconds resolution at the time of log write
</tag-desc>

<tag-name><var>$pipe</var></tag-name>
<tag-desc>
“<literal>p</literal>” if request was pipelined, “<literal>.</literal>”
otherwise
</tag-desc>

<tag-name><var>$request_length</var></tag-name>
<tag-desc>
request length (including request line, header, and request body)
</tag-desc>

<tag-name><var>$request_time</var></tag-name>
<tag-desc>
request processing time in seconds with a milliseconds resolution;
time elapsed between the first bytes were read from the client and
the log write after the last bytes were sent to the client
</tag-desc>

<tag-name><var>$status</var></tag-name>
<tag-desc>
response status
</tag-desc>

<tag-name><var>$time_iso8601</var></tag-name>
<tag-desc>
local time in the ISO 8601 standard format
</tag-desc>

<tag-name><var>$time_local</var></tag-name>
<tag-desc>
local time in the Common Log Format
</tag-desc>

</list>

<note>
In modern versions of nginx variables
<link doc="ngx_http_core_module.xml" id="var_status">$status</link>
(1.3.2, 1.2.2),
<link doc="ngx_http_core_module.xml" id="var_bytes_sent">$bytes_sent</link>
(1.3.8, 1.2.5),
<link doc="ngx_http_core_module.xml" id="var_connection">$connection</link>
(1.3.8, 1.2.5),
<link doc="ngx_http_core_module.xml" id="var_connection_requests">$connection_requests</link>
(1.3.8, 1.2.5),
<link doc="ngx_http_core_module.xml" id="var_msec">$msec</link>
(1.3.9, 1.2.6),
<link doc="ngx_http_core_module.xml" id="var_request_time">$request_time</link>
(1.3.9, 1.2.6),
<link doc="ngx_http_core_module.xml" id="var_pipe">$pipe</link>
(1.3.12, 1.2.7),
<link doc="ngx_http_core_module.xml" id="var_request_length">$request_length</link>
(1.3.12, 1.2.7),
<link doc="ngx_http_core_module.xml" id="var_time_iso8601">$time_iso8601</link>
(1.3.12, 1.2.7),
and
<link doc="ngx_http_core_module.xml" id="var_time_local">$time_local</link>
(1.3.12, 1.2.7)
are also available as common variables.
</note>

</para>

<para>
Header lines sent to a client have the prefix
“<literal>sent_http_</literal>”, for example,
<var>$sent_http_content_range</var>.
</para>

<para>
The configuration always includes the predefined format
“<literal>combined</literal>”:
<example>
log_format combined '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent"';
</example>
</para>

</directive>


<directive name="open_log_file_cache">

<syntax>
<literal>max</literal>=<value>N</value>
[<literal>inactive</literal>=<value>time</value>]
[<literal>min_uses</literal>=<value>N</value>]
[<literal>valid</literal>=<value>time</value>]</syntax>
<syntax><literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Defines a cache that stores file descriptors of frequently used logs
whose names contain variables.
The directive has the following parameters:
<list type="tag">

<tag-name><literal>max</literal></tag-name>
<tag-desc>
sets a maximum number of descriptors in a cache;
if cache becomes full the least recently used (LRU)
descriptors are closed
</tag-desc>

<tag-name><literal>inactive</literal></tag-name>
<tag-desc>
sets a time after which the cached descriptor is closed
if there were no access during this time;
by default, 10 seconds
</tag-desc>

<tag-name><literal>min_uses</literal></tag-name>
<tag-desc>
sets a minimum number of file uses during the time
defined by the <literal>inactive</literal> parameter
after which the descriptor will stay open in a cache;
by default, 1
</tag-desc>

<tag-name><literal>valid</literal></tag-name>
<tag-desc>
sets a time after which it should be checked that the file
still exists with the same name; by default, 60 seconds
</tag-desc>

<tag-name><literal>off</literal></tag-name>
<tag-desc>
disables caching
</tag-desc>

</list>
</para>

<para>
Example usage:
<example>
open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;
</example>
</para>

</directive>

</section>

</module>