Mercurial > hg > nginx-site
view xml/ru/docs/http/ngx_http_log_module.xml @ 1205:aab8a1667171
Syslog: added note when syslog appeared in oss and plus versions.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 27 May 2014 15:54:31 +0400 |
parents | 4eea26b34ea5 |
children | 4e89518a5999 |
line wrap: on
line source
<?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="13"> <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>]] [<literal>if</literal>=<value>условие</value>]]</syntax> <syntax> <value>путь</value> <value>формат</value> <literal>gzip[=<value>степень</value>]</literal> [<literal>buffer</literal>=<value>размер</value>] [<literal>flush</literal>=<value>время</value>] [<literal>if</literal>=<value>условие</value>]</syntax> <syntax> <literal>syslog:</literal><literal>server</literal>=<value>адрес</value>[,<value>параметр</value>=<value>значение</value>] [<value>формат</value> [<literal>if</literal>=<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> Параметр <literal>if</literal> (1.7.0) включает условную запись в лог. Запрос не будет записываться в лог, если результатом вычисления <value>условия</value> является “0” или пустая строка. В следующем примере запросы с кодами ответа 2xx и 3xx не будут записываться в лог: <example> map $status $loggable { ~^[23] 0; default 1; } access_log /path/to/access.log combined if=$loggable; </example> </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 доступна начиная с версии 1.7.1. Как часть <commercial_version>коммерческой подписки</commercial_version> запись в syslog доступна начиная с версии 1.5.3. </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>