Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_log_module.xml @ 224:7f36795d99a2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated ngx_http_log_module documentation including translation into English.
author Ruslan Ermilov <ru@nginx.com>
date Tue, 06 Dec 2011 07:25:25 +0000
parents
children 945d7299c26c
comparison
equal deleted inserted replaced
223:09b8c8b2b865 224:7f36795d99a2
1 <?xml version="1.0"?>
2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4
5 <module name="Module ngx_http_log_module"
6 link="/en/docs/http/ngx_http_log_module.html"
7 lang="en">
8
9 <section id="summary">
10
11 <para>
12 The <code>ngx_http_log_module</code> module writes request logs
13 in the specified format.
14 </para>
15
16 </section>
17
18
19 <section id="example" name="Example Configuration">
20
21 <para>
22 <example>
23 log_format gzip '$remote_addr - $remote_user [$time_local] '
24 '"$request" $status $bytes_sent '
25 '"$http_referer" "$http_user_agent" "$gzip_ratio"';
26
27 access_log /spool/logs/nginx-access.log gzip buffer=32k;
28 </example>
29 </para>
30
31 </section>
32
33
34 <section id="directives" name="Directives">
35
36 <directive name="access_log">
37 <syntax>
38 <argument>path</argument>
39 [<argument>format</argument>
40 [<parameter>buffer</parameter>=<argument>size</argument>]]</syntax>
41 <syntax><value>off</value></syntax>
42 <default>log/access.log combined</default>
43 <context>http</context>
44 <context>server</context>
45 <context>location</context>
46 <context>if in location</context>
47 <context>limit_except</context>
48
49 <para>
50 Sets the path, format, and buffer size for the buffered log writes.
51 Several logs can be specified on the same level.
52 The special value <value>off</value> cancels all <code>access_log</code>
53 directives on the current level.
54 If format is not specified then the predefined format
55 “<code>combined</code>” is used.
56 </para>
57
58 <para>
59 The buffer size must not exceed the size of the atomic write to a disk file.
60 For FreeBSD 3.0-6.0 this size is unlimited.
61 </para>
62
63 <para>
64 The file path can contain variables (0.7.6+),
65 but such logs have some constraints:
66 <list type="bullet">
67
68 <listitem>
69 the <link doc="../ngx_core_module.xml" id="user"/>
70 whose credentials are used by worker processes should
71 have permissions to create files in a directory with
72 such logs;
73 </listitem>
74
75 <listitem>
76 buffered writes do not work;
77 </listitem>
78
79 <listitem>
80 a file is opened and closed for each log write.
81 However, since the descriptors of frequently used files can be stored
82 in a <link id="open_log_file_cache">cache</link>, writes during the
83 time specified by the <parameter>valid</parameter> parameter of the
84 <link id="open_log_file_cache"/> directive can continue to be made
85 to the old file.
86 </listitem>
87
88 <listitem>
89 during each log write the existence of the request’s
90 <link doc="ngx_http_core_module.xml" id="root">root directory</link>
91 is checked, and if it does not exist the log is not
92 created.
93 It is thus a good idea to specify both
94 <link doc="ngx_http_core_module.xml" id="root"/>
95 and <code>access_log</code> on the same level:
96 <example>
97 server {
98 root /spool/vhost/data/$host;
99 access_log /spool/vhost/logs/$host;
100 ...
101 </example>
102 </listitem>
103
104 </list>
105 </para>
106
107 </directive>
108
109
110 <directive name="log_format">
111 <syntax>
112 <argument>name string ...</argument>
113 </syntax>
114 <default>combined "..."</default>
115 <context>http</context>
116
117 <para>
118 Specifies format of a log.
119 </para>
120
121 <para>
122 The log format can contain common variables, and variables that
123 exist only at the time of a log write:
124 <list type="tag">
125
126 <tag-name><var>$body_bytes_sent</var></tag-name>
127 <tag-desc>
128 the number of bytes sent to a client not counting the response header;
129 this variable is compatible with the “<code>%B</code>” parameter of the
130 <code>mod_log_config</code>
131 Apache module
132 </tag-desc>
133
134 <tag-name><var>$bytes_sent</var></tag-name>
135 <tag-desc>
136 the number of bytes sent to a client
137 </tag-desc>
138
139 <tag-name><var>$connection</var></tag-name>
140 <tag-desc>
141 connection serial number
142 </tag-desc>
143
144 <tag-name><var>$msec</var></tag-name>
145 <tag-desc>
146 time in seconds with a milliseconds resolution at the time of log write
147 </tag-desc>
148
149 <tag-name><var>$pipe</var></tag-name>
150 <tag-desc>
151 “<code>p</code>” if request was pipelined, “<code>.</code>” otherwise
152 </tag-desc>
153
154 <tag-name><var>$request_length</var></tag-name>
155 <tag-desc>
156 request length (including request line, header, and request body)
157 </tag-desc>
158
159 <tag-name><var>$request_time</var></tag-name>
160 <tag-desc>
161 request processing time in seconds with a milliseconds resolution;
162 time elapsed since first bytes were read from the client till
163 last bytes were sent to client and logging happened
164 </tag-desc>
165
166 <tag-name><var>$status</var></tag-name>
167 <tag-desc>
168 response status
169 </tag-desc>
170
171 <tag-name><var>$time_iso8601</var></tag-name>
172 <tag-desc>
173 local time in the ISO 8601 standard format
174 </tag-desc>
175
176 <tag-name><var>$time_local</var></tag-name>
177 <tag-desc>
178 local time in the Common Log Format
179 </tag-desc>
180
181 </list>
182 </para>
183
184 <para>
185 Header lines sent to a client have the prefix
186 “<code>sent_http_</code>”, for example,
187 <var>$sent_http_content_range</var>.
188 </para>
189
190 <para>
191 The configuration always includes the predefined format
192 “<code>combined</code>”:
193 <example>
194 log_format combined '$remote_addr - $remote_user [$time_local] '
195 '"$request" $status $body_bytes_sent '
196 '"$http_referer" "$http_user_agent"';
197 </example>
198 </para>
199
200 </directive>
201
202 <directive name="open_log_file_cache">
203
204 <syntax>
205 <parameter>max</parameter>=<argument>N</argument>
206 [<parameter>inactive</parameter>=<argument>time</argument>]
207 [<parameter>min_uses</parameter>=<argument>N</argument>]
208 [<parameter>valid</parameter>=<argument>time</argument>]</syntax>
209 <syntax><value>off</value></syntax>
210 <default>off</default>
211 <context>http</context>
212 <context>server</context>
213 <context>location</context>
214
215 <para>
216 Defines a cache that stores file descriptors of frequently used logs
217 whose names contain variables.
218 The directive has the following parameters:
219 <list type="tag">
220
221 <tag-name><parameter>max</parameter></tag-name>
222 <tag-desc>
223 sets a maximum number of descriptors in a cache;
224 if cache becomes full the least recently used (LRU)
225 descriptors are closed
226 </tag-desc>
227
228 <tag-name><parameter>inactive</parameter></tag-name>
229 <tag-desc>
230 sets a time after which the cached descriptor is closed
231 if there were no access during this time;
232 by default, 10 seconds
233 </tag-desc>
234
235 <tag-name><parameter>min_uses</parameter></tag-name>
236 <tag-desc>
237 sets a minimum number of file uses during the time
238 defined by the <parameter>inactive</parameter> parameter
239 after which the descriptor will stay open in a cache;
240 by default, 1
241 </tag-desc>
242
243 <tag-name><parameter>valid</parameter></tag-name>
244 <tag-desc>
245 sets a time after which it should be checked that the file
246 still exists with the same name; by default, 60 seconds
247 </tag-desc>
248
249 <tag-name><value>off</value></tag-name>
250 <tag-desc>
251 disables caching
252 </tag-desc>
253
254 </list>
255 </para>
256
257 <para>
258 Example usage:
259 <example>
260 open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;
261 </example>
262 </para>
263
264 </directive>
265
266 </section>
267
268 </module>