diff xml/en/docs/stream/ngx_stream_log_module.xml @ 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 xml/en/docs/http/ngx_http_log_module.xml@080b36ad8d76
children 8b1ef02c8686
line wrap: on
line diff
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