<?xml version="1.0"?>

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

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

<section id="summary">

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

</section>


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

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

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

</section>


<section id="directives" name="Директивы">

<directive name="access_log">
<syntax>
  <argument>путь</argument>
  [<argument>формат</argument>
  [<parameter>buffer</parameter>=<argument>размер</argument>]]</syntax>
<syntax><value>off</value></syntax>
<default>log/access.log combined</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if в location</context>
<context>limit_except</context>

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

<para>
Размер буфера должен быть не больше размера атомарной записи в дисковый файл.
Для FreeBSD 3.0-6.0 этот размер неограничен.
</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>,
то при вращении логов в течение времени, заданного параметром
<parameter>valid</parameter> директивы <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"/>
и <code>access_log</code> нужно описывать на одном уровне:
<example>
server {
    root       /spool/vhost/data/$host;
    access_log /spool/vhost/logs/$host;
    ...
</example>
</listitem>

</list>
</para>

</directive>


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

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

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

<tag-name><var>$body_bytes_sent</var></tag-name>
<tag-desc>
число байт, переданных клиенту, за вычетом заголовка ответа;
переменная совместима с параметром “<code>%B</code>” модуля Apache
<code>mod_log_config</code>
</tag-desc>

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

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

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

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

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

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

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

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

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

</list>
</para>

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

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

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

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

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

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

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

<tag-name><value>off</value></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>