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