Mercurial > hg > nginx-site
view xml/ru/docs/stream/ngx_stream_log_module.xml @ 2954:4cfe7dc4a871
nginx-1.24.0
author | Maxim Dounin <mdounin@mdounin.ru> |
---|---|
date | Tue, 11 Apr 2023 17:30:02 +0300 |
parents | 4add6ae1296f |
children |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Модуль ngx_stream_log_module" link="/ru/docs/stream/ngx_stream_log_module.html" lang="ru" rev="8"> <section id="summary"> <para> Модуль <literal>ngx_stream_log_module</literal> (1.11.4) записывает логи сессий в указанном формате. </para> </section> <section id="example" name="Пример конфигурации"> <para> <example> log_format basic '$remote_addr [$time_local] ' '$protocol $status $bytes_sent $bytes_received ' '$session_time'; access_log /spool/logs/nginx-access.log basic buffer=32k; </example> </para> </section> <section id="directives" name="Директивы"> <directive name="access_log"> <syntax> <value>путь</value> <value>формат</value> [<literal>buffer</literal>=<value>размер</value>] [<literal>gzip[=<value>степень</value>]</literal>] [<literal>flush</literal>=<value>время</value>] [<literal>if</literal>=<value>условие</value>]</syntax> <syntax><literal>off</literal></syntax> <default>off</default> <context>stream</context> <context>server</context> <para> Задаёт путь, <link id="log_format">формат</link> и настройки буферизованной записи в лог. На одном уровне конфигурации может использоваться несколько логов. Запись в <link doc="../syslog.xml">syslog</link> настраивается указанием префикса “<literal>syslog:</literal>” в первом параметре. Специальное значение <literal>off</literal> отменяет все директивы <literal>access_log</literal> для текущего уровня. </para> <para> Если задан размер буфера с помощью параметра <literal>buffer</literal> или указан параметр <literal>gzip</literal>, то запись будет буферизованной. <note> Размер буфера должен быть не больше размера атомарной записи в дисковый файл. Для FreeBSD этот размер неограничен. </note> </para> <para> При включённой буферизации данные записываются в файл: <list type="bullet"> <listitem> если очередная строка лога не помещается в буфер; </listitem> <listitem> если данные в буфере находятся дольше интервала времени, заданного параметром <literal>flush</literal>; </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 basic gzip flush=5m; </example> </para> <para> <note> Для поддержки gzip-сжатия логов nginx должен быть собран с библиотекой zlib. </note> </para> <para> В пути файла можно использовать переменные, но такие логи имеют некоторые ограничения: <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> </list> </para> <para> Параметр <literal>if</literal> включает условную запись в лог. Сессия не будет записываться в лог, если результатом вычисления <value>условия</value> является “0” или пустая строка. </para> </directive> <directive name="log_format"> <syntax> <value>название</value> [<literal>escape</literal>=<literal>default</literal>|<literal>json</literal>|<literal>none</literal>] <value>строка</value> ...</syntax> <default></default> <context>stream</context> <para> Задаёт формат лога, например: <example> log_format proxy '$remote_addr [$time_local] ' '$protocol $status $bytes_sent $bytes_received ' '$session_time "$upstream_addr" ' '"$upstream_bytes_sent" "$upstream_bytes_received" "$upstream_connect_time"'; </example> </para> <para id="log_format_escape"> Параметр <literal>escape</literal> (1.11.8) позволяет задать экранирование символов <literal>json</literal> или <literal>default</literal> в переменных, по умолчанию используется <literal>default</literal>. Параметр <literal>none</literal> (1.13.10) отключает экранирование символов. </para> <para id="log_format_escape_default"> При использовании <literal>default</literal> символы “<literal>"</literal>”, “<literal>\</literal>”, a также символы со значениями меньше 32 или больше 126 экранируются как “<literal>\xXX</literal>”. Если значение переменной не найдено, то в качестве значения в лог будет записываться дефис (“<literal>-</literal>”). </para> <para id="log_format_escape_json"> При использовании <literal>json</literal> экранируются все символы, недопустимые в JSON <link url="https://datatracker.ietf.org/doc/html/rfc8259#section-7">строках</link>: символы “<literal>"</literal>” и “<literal>\</literal>” экранируются как “<literal>\"</literal>” и “<literal>\\</literal>”, символы со значениями меньше 32 экранируются как “<literal>\n</literal>”, “<literal>\r</literal>”, “<literal>\t</literal>”, “<literal>\b</literal>”, “<literal>\f</literal>” или “<literal>\u00XX</literal>”. </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>stream</context> <context>server</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>