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