Mercurial > hg > nginx-site

comparison xml/en/docs/stream/ngx_stream_log_module.xml @ 1776:8d0372178e00

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
comparison
equal deleted inserted replaced
1775:a469e77d446f 1776:8d0372178e00
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Nginx, Inc.
5 -->
6
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
8
9 <module name="Module ngx_stream_log_module"
10 link="/en/docs/stream/ngx_stream_log_module.html"
11 lang="en"
12 rev="1">
13
14 <section id="summary">
15
16 <para>
17 The <literal>ngx_stream_log_module</literal> module writes session logs
18 in the specified format.
19 </para>
20
21 </section>
22
23
24 <section id="example" name="Example Configuration">
25
26 <para>
27 <example>
28 log_format basic '$remote_addr [$time_local] '
29 '$protocol $status $bytes_sent $bytes_received '
30 '$session_time';
31
32 access_log /spool/logs/nginx-access.log detailed buffer=32k;
33 </example>
34 </para>
35
36 </section>
37
38
39 <section id="directives" name="Directives">
40
41 <directive name="access_log">
42 <syntax>
43 <value>path</value>
44 <value>format</value>
45 [<literal>buffer</literal>=<value>size</value>]
46 [<literal>gzip[=<value>level</value>]</literal>]
47 [<literal>flush</literal>=<value>time</value>]
48 [<literal>if</literal>=<value>condition</value>]</syntax>
49 <syntax><literal>off</literal></syntax>
50 <default>off</default>
51 <context>stream</context>
52 <context>server</context>
53
54 <para>
55 Sets the path, <link id="log_format">format</link>,
56 and configuration for a buffered log write.
57 Several logs can be specified on the same level.
58 Logging to <link doc="../syslog.xml">syslog</link>
59 can be configured by specifying
60 the “<literal>syslog:</literal>” prefix in the first parameter.
61 The special value <literal>off</literal> cancels all
62 <literal>access_log</literal> directives on the current level.
63 </para>
64
65 <para>
66 If either the <literal>buffer</literal> or <literal>gzip</literal>
67 parameter is used, writes to log will be buffered.
68 <note>
69 The buffer size must not exceed the size of an atomic write to a disk file.
70 For FreeBSD this size is unlimited.
71 </note>
72 </para>
73
74 <para>
75 When buffering is enabled, the data will be written to the file:
76 <list type="bullet">
77
78 <listitem>
79 if the next log line does not fit into the buffer;
80 </listitem>
81
82 <listitem>
83 if the buffered data is older than specified by the <literal>flush</literal>
84 parameter;
85 </listitem>
86
87 <listitem>
88 when a worker process is <link doc="../control.xml">re-opening</link> log
89 files or is shutting down.
90 </listitem>
91
92 </list>
93 </para>
94
95 <para>
96 If the <literal>gzip</literal> parameter is used, then the buffered data will
97 be compressed before writing to the file.
98 The compression level can be set between 1 (fastest, less compression)
99 and 9 (slowest, best compression).
100 By default, the buffer size is equal to 64K bytes, and the compression level
101 is set to 1.
102 Since the data is compressed in atomic blocks, the log file can be decompressed
103 or read by “<literal>zcat</literal>” at any time.
104 </para>
105
106 <para>
107 Example:
108 <example>
109 access_log /path/to/log.gz basic gzip flush=5m;
110 </example>
111 </para>
112
113 <para>
114 <note>
115 For gzip compression to work, nginx must be built with the zlib library.
116 </note>
117 </para>
118
119 <para>
120 The file path can contain variables,
121 but such logs have some constraints:
122 <list type="bullet">
123
124 <listitem>
125 the <link doc="../ngx_core_module.xml" id="user"/>
126 whose credentials are used by worker processes should
127 have permissions to create files in a directory with
128 such logs;
129 </listitem>
130
131 <listitem>
132 buffered writes do not work;
133 </listitem>
134
135 <listitem>
136 the file is opened and closed for each log write.
137 However, since the descriptors of frequently used files can be stored
138 in a <link id="open_log_file_cache">cache</link>, writing to the old file
139 can continue during the time specified by the <link id="open_log_file_cache"/>
140 directive’s <literal>valid</literal> parameter
141 </listitem>
142
143 </list>
144 </para>
145
146 <para>
147 The <literal>if</literal> parameter enables conditional logging.
148 A session will not be logged if the <value>condition</value> evaluates to “0”
149 or an empty string.
150 </para>
151
152 </directive>
153
154
155 <directive name="log_format">
156 <syntax>
157 <value>name</value>
158 <value>string</value> ...</syntax>
159 <default></default>
160 <context>stream</context>
161
162 <para>
163 Specifies the log format, for example:
164 <example>
165 log_format proxy '$remote_addr [$time_local] '
166 '$protocol $status $bytes_sent $bytes_received'
167 '$session_time "$upstream_addr"'
168 '"$upstream_bytes_sent" "$upstream_bytes_received" "$upstream_connection_time" ';
169 </example>
170 </para>
171
172 </directive>
173
174
175 <directive name="open_log_file_cache">
176
177 <syntax>
178 <literal>max</literal>=<value>N</value>
179 [<literal>inactive</literal>=<value>time</value>]
180 [<literal>min_uses</literal>=<value>N</value>]
181 [<literal>valid</literal>=<value>time</value>]</syntax>
182 <syntax><literal>off</literal></syntax>
183 <default>off</default>
184 <context>stream</context>
185 <context>server</context>
186
187 <para>
188 Defines a cache that stores the file descriptors of frequently used logs
189 whose names contain variables.
190 The directive has the following parameters:
191 <list type="tag">
192
193 <tag-name><literal>max</literal></tag-name>
194 <tag-desc>
195 sets the maximum number of descriptors in a cache;
196 if the cache becomes full the least recently used (LRU)
197 descriptors are closed
198 </tag-desc>
199
200 <tag-name><literal>inactive</literal></tag-name>
201 <tag-desc>
202 sets the time after which the cached descriptor is closed
203 if there were no access during this time;
204 by default, 10 seconds
205 </tag-desc>
206
207 <tag-name><literal>min_uses</literal></tag-name>
208 <tag-desc>
209 sets the minimum number of file uses during the time
210 defined by the <literal>inactive</literal> parameter
211 to let the descriptor stay open in a cache;
212 by default, 1
213 </tag-desc>
214
215 <tag-name><literal>valid</literal></tag-name>
216 <tag-desc>
217 sets the time after which it should be checked that the file
218 still exists with the same name; by default, 60 seconds
219 </tag-desc>
220
221 <tag-name><literal>off</literal></tag-name>
222 <tag-desc>
223 disables caching
224 </tag-desc>
225
226 </list>
227 </para>
228
229 <para>
230 Usage example:
231 <example>
232 open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;
233 </example>
234 </para>
235
236 </directive>
237
238 </section>
239
240 </module>