Mercurial > hg > nginx-site

changeset 1776:8d0372178e00

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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>
 Задаёт кэш, в котором хранятся дескрипторы файлов часто используемых