Mercurial > hg > nginx-site
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
--- /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>