Mercurial > hg > nginx-site
changeset 1776:8d0372178e00
Documented the ngx_stream_log_module module.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Wed, 07 Sep 2016 19:42:32 +0300 |
parents | a469e77d446f |
children | 8b1ef02c8686 |
files | xml/en/GNUmakefile xml/en/docs/index.xml xml/en/docs/stream/ngx_stream_log_module.xml xml/ru/GNUmakefile xml/ru/docs/index.xml xml/ru/docs/stream/ngx_stream_log_module.xml |
diffstat | 6 files changed, 495 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/GNUmakefile Wed Sep 07 14:39:54 2016 +0300 +++ b/xml/en/GNUmakefile Wed Sep 07 19:42:32 2016 +0300 @@ -100,6 +100,7 @@ stream/ngx_stream_geo_module \ stream/ngx_stream_geoip_module \ stream/ngx_stream_limit_conn_module \ + stream/ngx_stream_log_module \ stream/ngx_stream_map_module \ stream/ngx_stream_proxy_module \ stream/ngx_stream_return_module \
--- a/xml/en/docs/index.xml Wed Sep 07 14:39:54 2016 +0300 +++ b/xml/en/docs/index.xml Wed Sep 07 19:42:32 2016 +0300 @@ -8,7 +8,7 @@ <article name="nginx documentation" link="/en/docs/" lang="en" - rev="30" + rev="31" toc="no"> @@ -512,6 +512,11 @@ </listitem> <listitem> +<link doc="stream/ngx_stream_log_module.xml"> +ngx_stream_log_module</link> +</listitem> + +<listitem> <link doc="stream/ngx_stream_map_module.xml"> ngx_stream_map_module</link> </listitem>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/stream/ngx_stream_log_module.xml Wed Sep 07 19:42:32 2016 +0300 @@ -0,0 +1,240 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_stream_log_module" + link="/en/docs/stream/ngx_stream_log_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_stream_log_module</literal> module writes session logs +in the specified format. +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +log_format basic '$remote_addr [$time_local] ' + '$protocol $status $bytes_sent $bytes_received ' + '$session_time'; + +access_log /spool/logs/nginx-access.log detailed 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>gzip[=<value>level</value>]</literal>] + [<literal>flush</literal>=<value>time</value>] + [<literal>if</literal>=<value>condition</value>]</syntax> +<syntax><literal>off</literal></syntax> +<default>off</default> +<context>stream</context> +<context>server</context> + +<para> +Sets the path, <link id="log_format">format</link>, +and configuration for a buffered log write. +Several logs can be specified on the same level. +Logging to <link doc="../syslog.xml">syslog</link> +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. +</para> + +<para> +If either the <literal>buffer</literal> or <literal>gzip</literal> +parameter is used, writes to log will be buffered. +<note> +The buffer size must not exceed the size of an 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; +</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 basic 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, +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> +the 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>, writing to the old file +can continue during the time specified by the <link id="open_log_file_cache"/> +directive’s <literal>valid</literal> parameter +</listitem> + +</list> +</para> + +<para> +The <literal>if</literal> parameter enables conditional logging. +A session will not be logged if the <value>condition</value> evaluates to “0” +or an empty string. +</para> + +</directive> + + +<directive name="log_format"> +<syntax> + <value>name</value> + <value>string</value> ...</syntax> +<default></default> +<context>stream</context> + +<para> +Specifies the log format, for example: +<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_connection_time" '; +</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>stream</context> +<context>server</context> + +<para> +Defines a cache that stores the 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 the maximum number of descriptors in a cache; +if the cache becomes full the least recently used (LRU) +descriptors are closed +</tag-desc> + +<tag-name><literal>inactive</literal></tag-name> +<tag-desc> +sets the 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 the minimum number of file uses during the time +defined by the <literal>inactive</literal> parameter +to let the descriptor stay open in a cache; +by default, 1 +</tag-desc> + +<tag-name><literal>valid</literal></tag-name> +<tag-desc> +sets the 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> +Usage example: +<example> +open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2; +</example> +</para> + +</directive> + +</section> + +</module>
--- a/xml/ru/GNUmakefile Wed Sep 07 14:39:54 2016 +0300 +++ b/xml/ru/GNUmakefile Wed Sep 07 19:42:32 2016 +0300 @@ -88,6 +88,7 @@ stream/ngx_stream_geo_module \ stream/ngx_stream_geoip_module \ stream/ngx_stream_limit_conn_module \ + stream/ngx_stream_log_module \ stream/ngx_stream_map_module \ stream/ngx_stream_proxy_module \ stream/ngx_stream_return_module \
--- a/xml/ru/docs/index.xml Wed Sep 07 14:39:54 2016 +0300 +++ b/xml/ru/docs/index.xml Wed Sep 07 19:42:32 2016 +0300 @@ -8,7 +8,7 @@ <article name="nginx: документация" link="/ru/docs/" lang="ru" - rev="30" + rev="31" toc="no"> @@ -516,6 +516,11 @@ </listitem> <listitem> +<link doc="stream/ngx_stream_log_module.xml"> +ngx_stream_log_module</link> +</listitem> + +<listitem> <link doc="stream/ngx_stream_map_module.xml"> ngx_stream_map_module</link> </listitem>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/stream/ngx_stream_log_module.xml Wed Sep 07 19:42:32 2016 +0300 @@ -0,0 +1,241 @@ +<?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="1"> + +<section id="summary"> + +<para> +Модуль <literal>ngx_stream_log_module</literal> записывает логи сессий +в указанном формате. +</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> + <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_connection_time" '; +</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>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>