<?xml version="1.0"?>

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

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

<module name="Модуль ngx_http_log_module"
        link="/ru/docs/http/ngx_http_log_module.html"
        lang="ru"
        rev="11">

<section id="summary">

<para>
Модуль <literal>ngx_http_log_module</literal> записывает логи запросов
в указанном формате.
</para>

<para>
Логи записываются в контексте location’а, где заканчивается обработка.
Это может быть location, отличный от первоначального, если в процессе
обработки запроса происходит
<link doc="ngx_http_core_module.xml" id="internal">внутреннее
перенаправление</link>.
</para>

</section>


<section id="example" name="Пример конфигурации">

<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="Директивы">

<directive name="access_log">
<syntax>
    <value>путь</value>
    [<value>формат</value>
    [<literal>buffer</literal>=<value>размер</value>
    [<literal>flush</literal>=<value>время</value>]]]</syntax>
<syntax>
    <value>путь</value>
    <value>формат</value>
    <literal>gzip[=<value>степень</value>]</literal>
    [<literal>buffer</literal>=<value>размер</value>]
    [<literal>flush</literal>=<value>время</value>]</syntax>
<syntax>
    <literal>syslog:</literal><literal>server</literal>=<value>адрес</value>[,<value>параметр</value>=<value>значение</value>]
    [<value>формат</value>]</syntax>
<syntax><literal>off</literal></syntax>
<default>logs/access.log combined</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if в location</context>
<context>limit_except</context>

<para>
Задаёт путь, формат и настройки буферизованной записи в лог.
На одном уровне может использоваться несколько логов.
Запись в syslog настраивается указанием префикса
“<literal>syslog:</literal>” в первом параметре.
Специальное значение <literal>off</literal> отменяет все директивы
<literal>access_log</literal> для текущего уровня.
Если формат не указан, то используется предопределённый формат
“<literal>combined</literal>”.
</para>

<para>
Если задан размер буфера с помощью параметра <literal>buffer</literal> или
указан параметр <literal>gzip</literal> (1.3.10, 1.2.7), то запись будет
буферизованной.
<note>
Размер буфера должен быть не больше размера атомарной записи в дисковый файл.
Для FreeBSD этот размер неограничен.
</note>
</para>

<para>
При включённой буферизации данные записываются в файл:
<list type="bullet">

<listitem>
если очередная строка лога не помещается в буфер;
</listitem>

<listitem>
если данные в буфере находятся дольше интервала времени, заданного
параметром <literal>flush</literal> (1.3.10, 1.2.7);
</listitem>

<listitem>
при <link doc="../control.xml">переоткрытии</link> лог-файла или
завершении рабочего процесса.
</listitem>

</list>
</para>

<para>
Если задан параметр <literal>gzip</literal>, то буфер будет сжиматься перед
записью в файл.
Степень сжатия может быть задана в диапазоне от 1 (быстрее, но хуже сжатие)
до 9 (медленнее, но лучше сжатие).
По умолчанию используются буфер размером 64К байт и степень сжатия 1.
Данные сжимаются атомарными блоками, и в любой момент времени лог-файл может
быть распакован или прочитан с помощью утилиты “<literal>zcat</literal>”.
</para>

<para>
Пример:
<example>
access_log /path/to/log.gz combined gzip flush=5m;
</example>
</para>

<para>
<note>
Для поддержки gzip-сжатия логов nginx должен быть собран с библиотекой zlib.
</note>
</para>

<para>
В пути файла можно использовать переменные (0.7.6+),
но такие логи имеют некоторые ограничения:
<list type="bullet">

<listitem>
<link doc="../ngx_core_module.xml" id="user">пользователь</link>,
с правами которого работают рабочие процессы, должен
иметь права на создание файлов в каталоге с такими логами;
</listitem>

<listitem>
не работает буферизация;
</listitem>

<listitem>
файл открывается для каждой записи в лог и сразу же после записи закрывается.
Следует однако иметь в виду, что поскольку дескрипторы часто используемых файлов
могут храниться в <link id="open_log_file_cache">кэше</link>,
то при вращении логов в течение времени, заданного параметром
<literal>valid</literal> директивы <link id="open_log_file_cache"/>,
запись может продолжаться в старый файл.
</listitem>

<listitem>
при каждой записи в лог проверяется существование
<link doc="ngx_http_core_module.xml" id="root">корневого каталога</link>
для запроса — если этот каталог не существует, то лог не создаётся.
Поэтому <link doc="ngx_http_core_module.xml" id="root"/>
и <literal>access_log</literal> нужно описывать на одном уровне:
<example>
server {
    root       /spool/vhost/data/$host;
    access_log /spool/vhost/logs/$host;
    ...
</example>
</listitem>

</list>
</para>

<para>
Запись в syslog настраивается при помощи следующих параметров:
<list type="tag">

<tag-name><literal>server=</literal><value>адрес</value></tag-name>
<tag-desc>
Задаёт адрес сервера syslog.
Адрес может быть указан в виде доменного имени, IP-адреса или
в виде пути UNIX-сокета (указывается после префикса
“<literal>unix:</literal>”).
Вместе с именем или адресом может быть указан порт.
Если порт не указан, используется порт 514.
Если доменному имени соответствует несколько IP-адресов,
используется только первый адрес.
</tag-desc>

<tag-name><literal>facility=</literal><value>строка</value></tag-name>
<tag-desc>
Задаёт категорию сообщений syslog в соответствии с
<link url="http://tools.ietf.org/html/rfc3164#section-4.1.1">RFC 3164</link>.
В качестве категории может быть указано одно из следующих значений:
“<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>”.
По умолчанию используется “<literal>local7</literal>”.
</tag-desc>

<tag-name><literal>severity=</literal><value>строка</value></tag-name>
<tag-desc>
Задаёт важность сообщений syslog в соответствии с
<link url="http://tools.ietf.org/html/rfc3164#section-4.1.1">RFC 3164</link>.
Возможны те же самые значения, что и у второго параметра (уровень)
директивы <link doc="../ngx_core_module.xml" id="error_log"/>.
По умолчанию используется “<literal>info</literal>”.
</tag-desc>

<tag-name><literal>tag=</literal><value>строка</value></tag-name>
<tag-desc>
Задаёт метку сообщений syslog.
По умолчанию используется “<literal>nginx</literal>”.
</tag-desc>

<!--
<tag-name><literal>bare=</literal><literal>on</literal> |
<literal>off</literal></tag-name>
<tag-desc>
Если включено, сообщения отправляются без заголовка syslog.
По умолчанию выключено.
</tag-desc>
-->

</list>
Пример конфигурации syslog:
<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>
Запись в syslog доступна как часть
<commercial_version>коммерческой подписки</commercial_version>.
</note>
</para>

</directive>


<directive name="log_format">
<syntax>
    <value>название</value>
    <value>строка</value> ...</syntax>
<default>combined "..."</default>
<context>http</context>

<para>
Задаёт формат лога.
</para>

<para>
Кроме общих переменных в формате можно использовать переменные,
существующие только на момент записи в лог:
<list type="tag">

<tag-name id="var_bytes_sent"><var>$bytes_sent</var></tag-name>
<tag-desc>
число байт, переданное клиенту
</tag-desc>

<tag-name id="var_connection"><var>$connection</var></tag-name>
<tag-desc>
порядковый номер соединения
</tag-desc>

<tag-name id="var_connection_requests"><var>$connection_requests</var>
</tag-name>
<tag-desc>
текущее число запросов в соединении (1.1.18)
</tag-desc>

<tag-name id="var_msec"><var>$msec</var></tag-name>
<tag-desc>
время в секундах с точностью до миллисекунд на момент записи в лог
</tag-desc>

<tag-name id="var_pipe"><var>$pipe</var></tag-name>
<tag-desc>
“<literal>p</literal>” если запрос был pipelined, иначе “<literal>.</literal>”
</tag-desc>

<tag-name id="var_request_length"><var>$request_length</var></tag-name>
<tag-desc>
длина запроса (включая строку запроса, заголовок и тело запроса)
</tag-desc>

<tag-name id="var_request_time"><var>$request_time</var></tag-name>
<tag-desc>
время обработки запроса в секундах с точностью до миллисекунд;
время, прошедшее с момента чтения первых байт от клиента до
момента записи в лог после отправки последних байт клиенту
</tag-desc>

<tag-name id="var_status"><var>$status</var></tag-name>
<tag-desc>
статус ответа
</tag-desc>

<tag-name id="var_time_iso8601"><var>$time_iso8601</var></tag-name>
<tag-desc>
локальное время в формате по стандарту ISO 8601
</tag-desc>

<tag-name id="var_time_local"><var>$time_local</var></tag-name>
<tag-desc>
локальное время в Common Log Format
</tag-desc>

</list>

<note>
В современных версиях nginx переменные
<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)
и
<link doc="ngx_http_core_module.xml" id="var_time_local">$time_local</link>
(1.3.12, 1.2.7)
также доступны как общие переменные.
</note>

</para>

<para>
Строки заголовка, переданные клиенту, начинаются с префикса
“<literal>sent_http_</literal>”, например,
<var>$sent_http_content_range</var>.
</para>

<para>
В конфигурации всегда существует предопределённый формат
“<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>время</value>]
[<literal>min_uses</literal>=<value>N</value>]
[<literal>valid</literal>=<value>время</value>]</syntax>
<syntax><literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт кэш, в котором хранятся дескрипторы файлов часто используемых
логов, имена которых заданы с использованием переменных.
Параметры директивы:
<list type="tag">

<tag-name><literal>max</literal></tag-name>
<tag-desc>
задаёт максимальное число дескрипторов в кэше;
при переполнении кэша наименее востребованные (LRU)
дескрипторы закрываются
</tag-desc>

<tag-name><literal>inactive</literal></tag-name>
<tag-desc>
задаёт время, после которого закэшированный дескриптор закрывается,
если к нему не было обращений в течение этого времени;
по умолчанию 10 секунд
</tag-desc>

<tag-name><literal>min_uses</literal></tag-name>
<tag-desc>
задаёт минимальное число использований файла в течение
времени, заданного параметром <literal>inactive</literal>,
после которого дескриптор файла будет оставаться открытым в кэше;
по умолчанию 1
</tag-desc>

<tag-name><literal>valid</literal></tag-name>
<tag-desc>
задаёт, через какое время нужно проверять, что файл ещё
существует под тем же именем;
по умолчанию 60 секунд
</tag-desc>

<tag-name><literal>off</literal></tag-name>
<tag-desc>
запрещает кэш
</tag-desc>

</list>
</para>

<para>
Пример использования:
<example>
open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;
</example>
</para>

</directive>

</section>

</module>