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, 69 insertions(+), 332 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/GNUmakefile +++ b/xml/en/GNUmakefile @@ -100,6 +100,7 @@ REFS = \ 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 +++ b/xml/en/docs/index.xml @@ -8,7 +8,7 @@ <article name="nginx documentation" link="/en/docs/" lang="en" - rev="30" + rev="31" toc="no"> @@ -512,6 +512,11 @@ ngx_stream_limit_conn_module</link> </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>
copy from xml/en/docs/http/ngx_http_log_module.xml copy to xml/en/docs/stream/ngx_stream_log_module.xml --- a/xml/en/docs/http/ngx_http_log_module.xml +++ b/xml/en/docs/stream/ngx_stream_log_module.xml @@ -1,31 +1,23 @@ <?xml version="1.0"?> <!-- - Copyright (C) Igor Sysoev Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> -<module name="Module ngx_http_log_module" - link="/en/docs/http/ngx_http_log_module.html" +<module name="Module ngx_stream_log_module" + link="/en/docs/stream/ngx_stream_log_module.html" lang="en" - rev="15"> + rev="1"> <section id="summary"> <para> -The <literal>ngx_http_log_module</literal> module writes request logs +The <literal>ngx_stream_log_module</literal> module writes session logs in the specified format. </para> -<para> -Requests are logged in the context of a location where processing ends. -It may be different from the original location, if an -<link doc="ngx_http_core_module.xml" id="internal">internal -redirect</link> happens during request processing. -</para> - </section> @@ -33,11 +25,11 @@ redirect</link> happens during request p <para> <example> -log_format compression '$remote_addr - $remote_user [$time_local] ' - '"$request" $status $bytes_sent ' - '"$http_referer" "$http_user_agent" "$gzip_ratio"'; +log_format basic '$remote_addr [$time_local] ' + '$protocol $status $bytes_sent $bytes_received ' + '$session_time'; -access_log /spool/logs/nginx-access.log compression buffer=32k; +access_log /spool/logs/nginx-access.log detailed buffer=32k; </example> </para> @@ -49,34 +41,29 @@ access_log /spool/logs/nginx-access.log <directive name="access_log"> <syntax> <value>path</value> - [<value>format</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> + [<literal>if</literal>=<value>condition</value>]</syntax> <syntax><literal>off</literal></syntax> -<default>logs/access.log combined</default> -<context>http</context> +<default>off</default> +<context>stream</context> <context>server</context> -<context>location</context> -<context>if in location</context> -<context>limit_except</context> <para> -Sets the path, format, and configuration for a buffered log write. +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. -If the format is not specified then the predefined -“<literal>combined</literal>” format is used. </para> <para> If either the <literal>buffer</literal> or <literal>gzip</literal> -(1.3.10, 1.2.7) 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. @@ -94,7 +81,7 @@ if the next log line does not fit into t <listitem> if the buffered data is older than specified by the <literal>flush</literal> -parameter (1.3.10, 1.2.7); +parameter; </listitem> <listitem> @@ -119,7 +106,7 @@ or read by “<literal>zcat</literal>” at any time. <para> Example: <example> -access_log /path/to/log.gz combined gzip flush=5m; +access_log /path/to/log.gz basic gzip flush=5m; </example> </para> @@ -130,7 +117,7 @@ For gzip compression to work, nginx must </para> <para> -The file path can contain variables (0.7.6+), +The file path can contain variables, but such logs have some constraints: <list type="bullet"> @@ -153,39 +140,13 @@ can continue during the time specified b directive’s <literal>valid</literal> parameter </listitem> -<listitem> -during each log write the existence of the request’s -<link doc="ngx_http_core_module.xml" id="root">root directory</link> -is checked, and if it does not exist the log is not -created. -It is thus a good idea to specify both -<link doc="ngx_http_core_module.xml" id="root"/> -and <literal>access_log</literal> on the same level: -<example> -server { - root /spool/vhost/data/$host; - access_log /spool/vhost/logs/$host; - ... -</example> -</listitem> - </list> </para> <para> -The <literal>if</literal> parameter (1.7.0) enables conditional logging. -A request will not be logged if the <value>condition</value> evaluates to “0” +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. -In the following example, the requests with response codes 2xx and 3xx -will not be logged: -<example> -map $status $loggable { - ~^[23] 0; - default 1; -} - -access_log /path/to/access.log combined if=$loggable; -</example> </para> </directive> @@ -195,115 +156,16 @@ access_log /path/to/access.log combined <syntax> <value>name</value> <value>string</value> ...</syntax> -<default>combined "..."</default> -<context>http</context> - -<para> -Specifies log format. -</para> +<default></default> +<context>stream</context> <para> -The log format can contain common variables, and variables that -exist only at the time of a log write: -<list type="tag"> - -<tag-name id="var_bytes_sent"><var>$bytes_sent</var></tag-name> -<tag-desc> -the number of bytes sent to a client -</tag-desc> - -<tag-name id="var_connection"><var>$connection</var></tag-name> -<tag-desc> -connection serial number -</tag-desc> - -<tag-name id="var_connection_requests"><var>$connection_requests</var> -</tag-name> -<tag-desc> -the current number of requests made through a connection (1.1.18) -</tag-desc> - -<tag-name id="var_msec"><var>$msec</var></tag-name> -<tag-desc> -time in seconds with a milliseconds resolution at the time of the log write -</tag-desc> - -<tag-name id="var_pipe"><var>$pipe</var></tag-name> -<tag-desc> -“<literal>p</literal>” if request was pipelined, “<literal>.</literal>” -otherwise -</tag-desc> - -<tag-name id="var_request_length"><var>$request_length</var></tag-name> -<tag-desc> -request length (including request line, header, and request body) -</tag-desc> - -<tag-name id="var_request_time"><var>$request_time</var></tag-name> -<tag-desc> -request processing time in seconds with a milliseconds resolution; -time elapsed between the first bytes were read from the client and -the log write after the last bytes were sent to the client -</tag-desc> - -<tag-name id="var_status"><var>$status</var></tag-name> -<tag-desc> -response status -</tag-desc> - -<tag-name id="var_time_iso8601"><var>$time_iso8601</var></tag-name> -<tag-desc> -local time in the ISO 8601 standard format -</tag-desc> - -<tag-name id="var_time_local"><var>$time_local</var></tag-name> -<tag-desc> -local time in the Common Log Format -</tag-desc> - -</list> - -<note> -In the modern nginx versions variables -<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), -and -<link doc="ngx_http_core_module.xml" id="var_time_local">$time_local</link> -(1.3.12, 1.2.7) -are also available as common variables. -</note> - -</para> - -<para> -Header lines sent to a client have the prefix -“<literal>sent_http_</literal>”, for example, -<var>$sent_http_content_range</var>. -</para> - -<para> -The configuration always includes the predefined -“<literal>combined</literal>” format: +Specifies the log format, for example: <example> -log_format combined '$remote_addr - $remote_user [$time_local] ' - '"$request" $status $body_bytes_sent ' - '"$http_referer" "$http_user_agent"'; +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> @@ -319,9 +181,8 @@ log_format combined '$remote_addr - $rem [<literal>valid</literal>=<value>time</value>]</syntax> <syntax><literal>off</literal></syntax> <default>off</default> -<context>http</context> +<context>stream</context> <context>server</context> -<context>location</context> <para> Defines a cache that stores the file descriptors of frequently used logs
--- a/xml/ru/GNUmakefile +++ b/xml/ru/GNUmakefile @@ -88,6 +88,7 @@ REFS = \ 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 +++ b/xml/ru/docs/index.xml @@ -8,7 +8,7 @@ <article name="nginx: документация" link="/ru/docs/" lang="ru" - rev="30" + rev="31" toc="no"> @@ -516,6 +516,11 @@ ngx_stream_limit_conn_module</link> </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>
copy from xml/ru/docs/http/ngx_http_log_module.xml copy to xml/ru/docs/stream/ngx_stream_log_module.xml --- a/xml/ru/docs/http/ngx_http_log_module.xml +++ b/xml/ru/docs/stream/ngx_stream_log_module.xml @@ -1,32 +1,23 @@ <?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" +<module name="Модуль ngx_stream_log_module" + link="/ru/docs/stream/ngx_stream_log_module.html" lang="ru" - rev="15"> + rev="1"> <section id="summary"> <para> -Модуль <literal>ngx_http_log_module</literal> записывает логи запросов +Модуль <literal>ngx_stream_log_module</literal> записывает логи сессий в указанном формате. </para> -<para> -Логи записываются в контексте location’а, где заканчивается обработка. -Это может быть location, отличный от первоначального, если в процессе -обработки запроса происходит -<link doc="ngx_http_core_module.xml" id="internal">внутреннее -перенаправление</link>. -</para> - </section> @@ -34,11 +25,11 @@ <para> <example> -log_format compression '$remote_addr - $remote_user [$time_local] ' - '"$request" $status $bytes_sent ' - '"$http_referer" "$http_user_agent" "$gzip_ratio"'; +log_format basic '$remote_addr [$time_local] ' + '$protocol $status $bytes_sent $bytes_received ' + ' $session_time'; -access_log /spool/logs/nginx-access.log compression buffer=32k; +access_log /spool/logs/nginx-access.log basic buffer=32k; </example> </para> @@ -50,34 +41,30 @@ access_log /spool/logs/nginx-access.log <directive name="access_log"> <syntax> <value>путь</value> - [<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> + [<literal>if</literal>=<value>условие</value>]</syntax> <syntax><literal>off</literal></syntax> -<default>logs/access.log combined</default> -<context>http</context> +<default>off</default> +<context>stream</context> <context>server</context> -<context>location</context> -<context>if в location</context> -<context>limit_except</context> <para> -Задаёт путь, формат и настройки буферизованной записи в лог. +Задаёт путь, <link id="log_format">формат</link> +и настройки буферизованной записи в лог. На одном уровне может использоваться несколько логов. Запись в <link doc="../syslog.xml">syslog</link> настраивается указанием префикса “<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), то запись будет +указан параметр <literal>gzip</literal>, то запись будет буферизованной. <note> Размер буфера должен быть не больше размера атомарной записи в дисковый файл. @@ -95,7 +82,7 @@ access_log /spool/logs/nginx-access.log <listitem> если данные в буфере находятся дольше интервала времени, заданного -параметром <literal>flush</literal> (1.3.10, 1.2.7); +параметром <literal>flush</literal>; </listitem> <listitem> @@ -119,7 +106,7 @@ access_log /spool/logs/nginx-access.log <para> Пример: <example> -access_log /path/to/log.gz combined gzip flush=5m; +access_log /path/to/log.gz basic gzip flush=5m; </example> </para> @@ -130,7 +117,7 @@ access_log /path/to/log.gz combined gzip </para> <para> -В пути файла можно использовать переменные (0.7.6+), +В пути файла можно использовать переменные, но такие логи имеют некоторые ограничения: <list type="bullet"> @@ -153,37 +140,13 @@ access_log /path/to/log.gz combined gzip запись может продолжаться в старый файл. </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) включает условную запись в лог. -Запрос не будет записываться в лог, если результатом вычисления +Параметр <literal>if</literal> включает условную запись в лог. +Сессия не будет записываться в лог, если результатом вычисления <value>условия</value> является “0” или пустая строка. -В следующем примере запросы с кодами ответа 2xx и 3xx -не будут записываться в лог: -<example> -map $status $loggable { - ~^[23] 0; - default 1; -} - -access_log /path/to/access.log combined if=$loggable; -</example> </para> </directive> @@ -193,114 +156,16 @@ access_log /path/to/access.log combined <syntax> <value>название</value> <value>строка</value> ...</syntax> -<default>combined "..."</default> -<context>http</context> - -<para> -Задаёт формат лога. -</para> +<default></default> +<context>stream</context> <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"'; +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> @@ -316,9 +181,8 @@ log_format combined '$remote_addr - $rem [<literal>valid</literal>=<value>время</value>]</syntax> <syntax><literal>off</literal></syntax> <default>off</default> -<context>http</context> +<context>stream</context> <context>server</context> -<context>location</context> <para> Задаёт кэш, в котором хранятся дескрипторы файлов часто используемых