--- /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>