nginx-site: xml/en/docs/http/ngx_http_log

annotate xml/en/docs/http/ngx_http_log_module.xml @ 2540:b686736680e3

Documented escaping rules in log_format.

author	Yaroslav Zhuravlev <yar@nginx.com>
date	Tue, 12 May 2020 22:06:12 +0100
parents	64004f50b9dd
children	eeed494bba51

rev	line source
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	1 <?xml version="1.0"?>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	2
580 be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 452 diff changeset	3 <!--
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 452 diff changeset	4 Copyright (C) Igor Sysoev
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 452 diff changeset	5 Copyright (C) Nginx, Inc.
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 452 diff changeset	6 -->
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 452 diff changeset	7
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	9
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	10 <module name="Module ngx_http_log_module"
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	11 link="/en/docs/http/ngx_http_log_module.html"
589 764fbac1b8b4 Added document revision. Ruslan Ermilov <ru@nginx.com> parents: 580 diff changeset	12 lang="en"
2540 b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	13 rev="20">
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	14
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	15 <section id="summary">
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	16
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	17 <para>
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	18 The <literal>ngx_http_log_module</literal> module writes request logs
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	19 in the specified format.
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	20 </para>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	21
430 570b312367bd Documented the context of request logging. Ruslan Ermilov <ru@nginx.com> parents: 364 diff changeset	22 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	23 Requests are logged in the context of a location where processing ends.
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	24 It may be different from the original location, if an
430 570b312367bd Documented the context of request logging. Ruslan Ermilov <ru@nginx.com> parents: 364 diff changeset	25 <link doc="ngx_http_core_module.xml" id="internal">internal
570b312367bd Documented the context of request logging. Ruslan Ermilov <ru@nginx.com> parents: 364 diff changeset	26 redirect</link> happens during request processing.
570b312367bd Documented the context of request logging. Ruslan Ermilov <ru@nginx.com> parents: 364 diff changeset	27 </para>
570b312367bd Documented the context of request logging. Ruslan Ermilov <ru@nginx.com> parents: 364 diff changeset	28
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	29 </section>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	30
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	31
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	32 <section id="example" name="Example Configuration">
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	33
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	34 <para>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	35 <example>
795 41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	36 log_format compression '$remote_addr - $remote_user [$time_local] '
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	37 '"$request" $status $bytes_sent '
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	38 '"$http_referer" "$http_user_agent" "$gzip_ratio"';
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	39
795 41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	40 access_log /spool/logs/nginx-access.log compression buffer=32k;
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	41 </example>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	42 </para>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	43
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	44 </section>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	45
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	46
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	47 <section id="directives" name="Directives">
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	48
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	49 <directive name="access_log">
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	50 <syntax>
364 bb51d3e17dd0 Style fixed. Ruslan Ermilov <ru@nginx.com> parents: 351 diff changeset	51 <value>path</value>
bb51d3e17dd0 Style fixed. Ruslan Ermilov <ru@nginx.com> parents: 351 diff changeset	52 [<value>format</value>
795 41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	53 [<literal>buffer</literal>=<value>size</value>]
1694 080b36ad8d76 Reduced syntax clutter in the access_log directive. Maxim Dounin <mdounin@mdounin.ru> parents: 1285 diff changeset	54 [<literal>gzip[=<value>level</value>]</literal>]
1168 384bb0349a8a Documented the "if" parameter of the "access_log" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	55 [<literal>flush</literal>=<value>time</value>]
384bb0349a8a Documented the "if" parameter of the "access_log" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	56 [<literal>if</literal>=<value>condition</value>]]</syntax>
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	57 <syntax><literal>off</literal></syntax>
443 1b2264bdd433 Fixed default for the access_log directive. Ruslan Ermilov <ru@nginx.com> parents: 430 diff changeset	58 <default>logs/access.log combined</default>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	59 <context>http</context>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	60 <context>server</context>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	61 <context>location</context>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	62 <context>if in location</context>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	63 <context>limit_except</context>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	64
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	65 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	66 Sets the path, format, and configuration for a buffered log write.
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	67 Several logs can be specified on the same level.
1285 4e89518a5999 Moved syslog configuration details into the separate documents. Ruslan Ermilov <ru@nginx.com> parents: 1205 diff changeset	68 Logging to <link doc="../syslog.xml">syslog</link>
4e89518a5999 Moved syslog configuration details into the separate documents. Ruslan Ermilov <ru@nginx.com> parents: 1205 diff changeset	69 can be configured by specifying
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 939 diff changeset	70 the “<literal>syslog:</literal>” prefix in the first parameter.
364 bb51d3e17dd0 Style fixed. Ruslan Ermilov <ru@nginx.com> parents: 351 diff changeset	71 The special value <literal>off</literal> cancels all
bb51d3e17dd0 Style fixed. Ruslan Ermilov <ru@nginx.com> parents: 351 diff changeset	72 <literal>access_log</literal> directives on the current level.
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	73 If the format is not specified then the predefined
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	74 “<literal>combined</literal>” format is used.
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	75 </para>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	76
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	77 <para>
840 9dab69f2b71d Documented nginx 1.2.7 changes. Ruslan Ermilov <ru@nginx.com> parents: 826 diff changeset	78 If either the <literal>buffer</literal> or <literal>gzip</literal>
9dab69f2b71d Documented nginx 1.2.7 changes. Ruslan Ermilov <ru@nginx.com> parents: 826 diff changeset	79 (1.3.10, 1.2.7)
795 41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	80 parameter is used, writes to log will be buffered.
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	81 <note>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	82 The buffer size must not exceed the size of an atomic write to a disk file.
657 56fa3cab4ceb Completely dropped FreeBSD version information when talking about Ruslan Ermilov <ru@nginx.com> parents: 656 diff changeset	83 For FreeBSD this size is unlimited.
795 41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	84 </note>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	85 </para>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	86
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	87 <para>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	88 When buffering is enabled, the data will be written to the file:
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	89 <list type="bullet">
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	90
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	91 <listitem>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	92 if the next log line does not fit into the buffer;
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	93 </listitem>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	94
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	95 <listitem>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	96 if the buffered data is older than specified by the <literal>flush</literal>
840 9dab69f2b71d Documented nginx 1.2.7 changes. Ruslan Ermilov <ru@nginx.com> parents: 826 diff changeset	97 parameter (1.3.10, 1.2.7);
795 41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	98 </listitem>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	99
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	100 <listitem>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	101 when a worker process is <link doc="../control.xml">re-opening</link> log
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	102 files or is shutting down.
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	103 </listitem>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	104
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	105 </list>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	106 </para>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	107
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	108 <para>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	109 If the <literal>gzip</literal> parameter is used, then the buffered data will
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	110 be compressed before writing to the file.
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	111 The compression level can be set between 1 (fastest, less compression)
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	112 and 9 (slowest, best compression).
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	113 By default, the buffer size is equal to 64K bytes, and the compression level
795 41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	114 is set to 1.
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	115 Since the data is compressed in atomic blocks, the log file can be decompressed
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	116 or read by “<literal>zcat</literal>” at any time.
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	117 </para>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	118
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	119 <para>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	120 Example:
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	121 <example>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	122 access_log /path/to/log.gz combined gzip flush=5m;
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	123 </example>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	124 </para>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	125
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	126 <para>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	127 <note>
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	128 For gzip compression to work, nginx must be built with the zlib library.
41363f013cc9 Documented the recently added "gzip" and "flush" parameters of the "access_log" Valentin Bartenev <vbart@nginx.com> parents: 779 diff changeset	129 </note>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	130 </para>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	131
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	132 <para>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	133 The file path can contain variables (0.7.6+),
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	134 but such logs have some constraints:
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	135 <list type="bullet">
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	136
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	137 <listitem>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	138 the <link doc="../ngx_core_module.xml" id="user"/>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	139 whose credentials are used by worker processes should
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	140 have permissions to create files in a directory with
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	141 such logs;
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	142 </listitem>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	143
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	144 <listitem>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	145 buffered writes do not work;
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	146 </listitem>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	147
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	148 <listitem>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	149 the file is opened and closed for each log write.
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	150 However, since the descriptors of frequently used files can be stored
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	151 in a <link id="open_log_file_cache">cache</link>, writing to the old file
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	152 can continue during the time specified by the <link id="open_log_file_cache"/>
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	153 directive’s <literal>valid</literal> parameter
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	154 </listitem>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	155
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	156 <listitem>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	157 during each log write the existence of the request’s
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	158 <link doc="ngx_http_core_module.xml" id="root">root directory</link>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	159 is checked, and if it does not exist the log is not
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	160 created.
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	161 It is thus a good idea to specify both
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	162 <link doc="ngx_http_core_module.xml" id="root"/>
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	163 and <literal>access_log</literal> on the same level:
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	164 <example>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	165 server {
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	166 root /spool/vhost/data/$host;
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	167 access_log /spool/vhost/logs/$host;
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	168 ...
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	169 </example>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	170 </listitem>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	171
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	172 </list>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	173 </para>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	174
953 aded7086e84f Commercial version documentation. Ruslan Ermilov <ru@nginx.com> parents: 939 diff changeset	175 <para>
1168 384bb0349a8a Documented the "if" parameter of the "access_log" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	176 The <literal>if</literal> parameter (1.7.0) enables conditional logging.
384bb0349a8a Documented the "if" parameter of the "access_log" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	177 A request will not be logged if the <value>condition</value> evaluates to “0”
384bb0349a8a Documented the "if" parameter of the "access_log" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	178 or an empty string.
384bb0349a8a Documented the "if" parameter of the "access_log" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	179 In the following example, the requests with response codes 2xx and 3xx
384bb0349a8a Documented the "if" parameter of the "access_log" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	180 will not be logged:
384bb0349a8a Documented the "if" parameter of the "access_log" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	181 <example>
384bb0349a8a Documented the "if" parameter of the "access_log" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	182 map $status $loggable {
384bb0349a8a Documented the "if" parameter of the "access_log" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	183 ~^[23] 0;
384bb0349a8a Documented the "if" parameter of the "access_log" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	184 default 1;
384bb0349a8a Documented the "if" parameter of the "access_log" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	185 }
384bb0349a8a Documented the "if" parameter of the "access_log" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	186
384bb0349a8a Documented the "if" parameter of the "access_log" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	187 access_log /path/to/access.log combined if=$loggable;
384bb0349a8a Documented the "if" parameter of the "access_log" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	188 </example>
384bb0349a8a Documented the "if" parameter of the "access_log" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	189 </para>
384bb0349a8a Documented the "if" parameter of the "access_log" directive. Yaroslav Zhuravlev <yar@nginx.com> parents: 1155 diff changeset	190
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	191 </directive>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	192
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	193
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	194 <directive name="log_format">
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	195 <syntax>
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	196 <value>name</value>
2111 dab82d534f0f Documented the "none" escape mode of the "log_format" directive. Vladimir Homutov <vl@nginx.com> parents: 1884 diff changeset	197 [<literal>escape</literal>=<literal>default</literal>\|<literal>json</literal>\|<literal>none</literal>]
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	198 <value>string</value> ...</syntax>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	199 <default>combined "..."</default>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	200 <context>http</context>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	201
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	202 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	203 Specifies log format.
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	204 </para>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	205
1874 33f742032155 Documented support for json escaping in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 1694 diff changeset	206 <para id="log_format_escape">
33f742032155 Documented support for json escaping in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 1694 diff changeset	207 The <literal>escape</literal> parameter (1.11.8) allows setting
1884 0b339643b08f Changed <value> to <literal> in log_fomrat. Yaroslav Zhuravlev <yar@nginx.com> parents: 1874 diff changeset	208 <literal>json</literal> or <literal>default</literal> characters escaping
0b339643b08f Changed <value> to <literal> in log_fomrat. Yaroslav Zhuravlev <yar@nginx.com> parents: 1874 diff changeset	209 in variables, by default, <literal>default</literal> escaping is used.
2161 64004f50b9dd Clarified the log_format "escape=none" description. Sergey Kandaurov <pluknet@nginx.com> parents: 2111 diff changeset	210 The <literal>none</literal> value (1.13.10) disables escaping.
1874 33f742032155 Documented support for json escaping in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 1694 diff changeset	211 </para>
33f742032155 Documented support for json escaping in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 1694 diff changeset	212
2540 b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	213 <para id="log_format_escape_default">
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	214 For <literal>default</literal> escaping,
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	215 characters “<literal>"</literal>”, “<literal>\</literal>”,
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	216 and other characters with values less than 32 (0.7.0) or above 126 (1.1.6)
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	217 are escaped as “<literal>\xXX</literal>”.
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	218 If the variable value is not found,
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	219 a hyphen (“<literal>-</literal>”) will be logged.
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	220 </para>
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	221
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	222 <para id="log_format_escape_json">
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	223 For <literal>json</literal> escaping,
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	224 all characters not allowed
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	225 in JSON <link url="https://tools.ietf.org/html/rfc8259#section-7">strings</link>
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	226 will be escaped:
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	227 characters “<literal>"</literal>” and
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	228 “<literal>\</literal>” are escaped as
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	229 “<literal>\"</literal>” and “<literal>\\</literal>”,
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	230 characters with values less than 32 are escaped as
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	231 “<literal>\n</literal>”,
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	232 “<literal>\r</literal>”,
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	233 “<literal>\t</literal>”,
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	234 “<literal>\b</literal>”,
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	235 “<literal>\f</literal>”, or
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	236 “<literal>\u00XX</literal>”.
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	237
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	238 </para>
b686736680e3 Documented escaping rules in log_format. Yaroslav Zhuravlev <yar@nginx.com> parents: 2161 diff changeset	239
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	240 <para>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	241 The log format can contain common variables, and variables that
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	242 exist only at the time of a log write:
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	243 <list type="tag">
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	244
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	245 <tag-name id="var_bytes_sent"><var>$bytes_sent</var></tag-name>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	246 <tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	247 the number of bytes sent to a client
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	248 </tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	249
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	250 <tag-name id="var_connection"><var>$connection</var></tag-name>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	251 <tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	252 connection serial number
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	253 </tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	254
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	255 <tag-name id="var_connection_requests"><var>$connection_requests</var>
07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	256 </tag-name>
452 e9a2a856d76b Documented the $connection_requests variable. Ruslan Ermilov <ru@nginx.com> parents: 451 diff changeset	257 <tag-desc>
769 d71e56d56ada Documented variables relocations between http log and core modules. Vladimir Homutov <vl@nginx.com> parents: 657 diff changeset	258 the current number of requests made through a connection (1.1.18)
452 e9a2a856d76b Documented the $connection_requests variable. Ruslan Ermilov <ru@nginx.com> parents: 451 diff changeset	259 </tag-desc>
e9a2a856d76b Documented the $connection_requests variable. Ruslan Ermilov <ru@nginx.com> parents: 451 diff changeset	260
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	261 <tag-name id="var_msec"><var>$msec</var></tag-name>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	262 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	263 time in seconds with a milliseconds resolution at the time of the log write
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	264 </tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	265
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	266 <tag-name id="var_pipe"><var>$pipe</var></tag-name>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	267 <tag-desc>
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	268 “<literal>p</literal>” if request was pipelined, “<literal>.</literal>”
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	269 otherwise
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	270 </tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	271
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	272 <tag-name id="var_request_length"><var>$request_length</var></tag-name>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	273 <tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	274 request length (including request line, header, and request body)
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	275 </tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	276
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	277 <tag-name id="var_request_time"><var>$request_time</var></tag-name>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	278 <tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	279 request processing time in seconds with a milliseconds resolution;
451 6351ab788157 Documented $request_time more precisely. Ruslan Ermilov <ru@nginx.com> parents: 443 diff changeset	280 time elapsed between the first bytes were read from the client and
6351ab788157 Documented $request_time more precisely. Ruslan Ermilov <ru@nginx.com> parents: 443 diff changeset	281 the log write after the last bytes were sent to the client
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	282 </tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	283
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	284 <tag-name id="var_status"><var>$status</var></tag-name>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	285 <tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	286 response status
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	287 </tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	288
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	289 <tag-name id="var_time_iso8601"><var>$time_iso8601</var></tag-name>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	290 <tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	291 local time in the ISO 8601 standard format
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	292 </tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	293
1155 07402a11fd8d Assigned IDs to tags describing variables. Vladimir Homutov <vl@nginx.com> parents: 1128 diff changeset	294 <tag-name id="var_time_local"><var>$time_local</var></tag-name>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	295 <tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	296 local time in the Common Log Format
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	297 </tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	298
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	299 </list>
826 ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	300
ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	301 <note>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	302 In the modern nginx versions variables
826 ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	303 <link doc="ngx_http_core_module.xml" id="var_status">$status</link>
ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	304 (1.3.2, 1.2.2),
ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	305 <link doc="ngx_http_core_module.xml" id="var_bytes_sent">$bytes_sent</link>
ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	306 (1.3.8, 1.2.5),
ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	307 <link doc="ngx_http_core_module.xml" id="var_connection">$connection</link>
ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	308 (1.3.8, 1.2.5),
ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	309 <link doc="ngx_http_core_module.xml" id="var_connection_requests">$connection_requests</link>
ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	310 (1.3.8, 1.2.5),
ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	311 <link doc="ngx_http_core_module.xml" id="var_msec">$msec</link>
ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	312 (1.3.9, 1.2.6),
ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	313 <link doc="ngx_http_core_module.xml" id="var_request_time">$request_time</link>
ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	314 (1.3.9, 1.2.6),
ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	315 <link doc="ngx_http_core_module.xml" id="var_pipe">$pipe</link>
840 9dab69f2b71d Documented nginx 1.2.7 changes. Ruslan Ermilov <ru@nginx.com> parents: 826 diff changeset	316 (1.3.12, 1.2.7),
826 ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	317 <link doc="ngx_http_core_module.xml" id="var_request_length">$request_length</link>
840 9dab69f2b71d Documented nginx 1.2.7 changes. Ruslan Ermilov <ru@nginx.com> parents: 826 diff changeset	318 (1.3.12, 1.2.7),
826 ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	319 <link doc="ngx_http_core_module.xml" id="var_time_iso8601">$time_iso8601</link>
840 9dab69f2b71d Documented nginx 1.2.7 changes. Ruslan Ermilov <ru@nginx.com> parents: 826 diff changeset	320 (1.3.12, 1.2.7),
826 ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	321 and
ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	322 <link doc="ngx_http_core_module.xml" id="var_time_local">$time_local</link>
840 9dab69f2b71d Documented nginx 1.2.7 changes. Ruslan Ermilov <ru@nginx.com> parents: 826 diff changeset	323 (1.3.12, 1.2.7)
826 ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	324 are also available as common variables.
ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	325 </note>
ddd22f571529 Variables $pipe, $request_length, $time_iso8601, and $time_local. Ruslan Ermilov <ru@nginx.com> parents: 795 diff changeset	326
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	327 </para>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	328
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	329 <para>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	330 Header lines sent to a client have the prefix
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	331 “<literal>sent_http_</literal>”, for example,
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	332 <var>$sent_http_content_range</var>.
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	333 </para>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	334
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	335 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	336 The configuration always includes the predefined
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	337 “<literal>combined</literal>” format:
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	338 <example>
351 a4fa80755eab Consistently strip initial offset in examples. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	339 log_format combined '$remote_addr - $remote_user [$time_local] '
a4fa80755eab Consistently strip initial offset in examples. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	340 '"$request" $status $body_bytes_sent '
a4fa80755eab Consistently strip initial offset in examples. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	341 '"$http_referer" "$http_user_agent"';
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	342 </example>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	343 </para>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	344
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	345 </directive>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	346
364 bb51d3e17dd0 Style fixed. Ruslan Ermilov <ru@nginx.com> parents: 351 diff changeset	347
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	348 <directive name="open_log_file_cache">
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	349
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	350 <syntax>
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	351 <literal>max</literal>=<value>N</value>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	352 [<literal>inactive</literal>=<value>time</value>]
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	353 [<literal>min_uses</literal>=<value>N</value>]
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	354 [<literal>valid</literal>=<value>time</value>]</syntax>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	355 <syntax><literal>off</literal></syntax>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	356 <default>off</default>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	357 <context>http</context>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	358 <context>server</context>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	359 <context>location</context>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	360
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	361 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	362 Defines a cache that stores the file descriptors of frequently used logs
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	363 whose names contain variables.
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	364 The directive has the following parameters:
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	365 <list type="tag">
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	366
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	367 <tag-name><literal>max</literal></tag-name>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	368 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	369 sets the maximum number of descriptors in a cache;
95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	370 if the cache becomes full the least recently used (LRU)
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	371 descriptors are closed
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	372 </tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	373
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	374 <tag-name><literal>inactive</literal></tag-name>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	375 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	376 sets the time after which the cached descriptor is closed
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	377 if there were no access during this time;
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	378 by default, 10 seconds
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	379 </tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	380
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	381 <tag-name><literal>min_uses</literal></tag-name>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	382 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	383 sets the minimum number of file uses during the time
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	384 defined by the <literal>inactive</literal> parameter
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	385 to let the descriptor stay open in a cache;
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	386 by default, 1
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	387 </tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	388
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	389 <tag-name><literal>valid</literal></tag-name>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	390 <tag-desc>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	391 sets the time after which it should be checked that the file
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	392 still exists with the same name; by default, 60 seconds
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	393 </tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	394
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 270 diff changeset	395 <tag-name><literal>off</literal></tag-name>
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	396 <tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	397 disables caching
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	398 </tag-desc>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	399
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	400 </list>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	401 </para>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	402
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	403 <para>
966 95c3c3bbf1ce Text review. Egor Nikitin <yegor.nikitin@gmail.com> parents: 956 diff changeset	404 Usage example:
224 7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	405 <example>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	406 open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	407 </example>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	408 </para>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	409
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	410 </directive>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	411
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	412 </section>
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	413
7f36795d99a2 Updated ngx_http_log_module documentation including translation into English. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	414 </module>

Mercurial > hg > nginx-site

annotate xml/en/docs/http/ngx_http_log_module.xml @ 2540:b686736680e3