Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_log_module.xml @ 966:95c3c3bbf1ce

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Text review.
author Egor Nikitin <yegor.nikitin@gmail.com>
date Wed, 14 Aug 2013 12:03:41 +0400
parents 488a3f738db0
children 379cb572a7ec
comparison
equal deleted inserted replaced
965:fadccc156188 966:95c3c3bbf1ce
18 The <literal>ngx_http_log_module</literal> module writes request logs 18 The <literal>ngx_http_log_module</literal> module writes request logs
19 in the specified format. 19 in the specified format.
20 </para> 20 </para>
21 21
22 <para> 22 <para>
23 Requests are logged in a context of a location where processing ends. 23 Requests are logged in the context of a location where processing ends.
24 This may be different from the original location, if an 24 It may be different from the original location, if an
25 <link doc="ngx_http_core_module.xml" id="internal">internal 25 <link doc="ngx_http_core_module.xml" id="internal">internal
26 redirect</link> happens during request processing. 26 redirect</link> happens during request processing.
27 </para> 27 </para>
28 28
29 </section> 29 </section>
68 <context>location</context> 68 <context>location</context>
69 <context>if in location</context> 69 <context>if in location</context>
70 <context>limit_except</context> 70 <context>limit_except</context>
71 71
72 <para> 72 <para>
73 Sets the path, format, and configuration of the buffered log writes. 73 Sets the path, format, and configuration for a buffered log write.
74 Several logs can be specified on the same level. 74 Several logs can be specified on the same level.
75 Logging to syslog can be configured by specifying 75 Logging to syslog can be configured by specifying
76 the “<literal>syslog:</literal>” prefix in the first parameter. 76 the “<literal>syslog:</literal>” prefix in the first parameter.
77 The special value <literal>off</literal> cancels all 77 The special value <literal>off</literal> cancels all
78 <literal>access_log</literal> directives on the current level. 78 <literal>access_log</literal> directives on the current level.
79 If format is not specified then the predefined format 79 If the format is not specified then the predefined
80 “<literal>combined</literal>” is used. 80 “<literal>combined</literal>” format is used.
81 </para> 81 </para>
82 82
83 <para> 83 <para>
84 If either the <literal>buffer</literal> or <literal>gzip</literal> 84 If either the <literal>buffer</literal> or <literal>gzip</literal>
85 (1.3.10, 1.2.7) 85 (1.3.10, 1.2.7)
86 parameter is used, writes to log will be buffered. 86 parameter is used, writes to log will be buffered.
87 <note> 87 <note>
88 The buffer size must not exceed the size of the atomic write to a disk file. 88 The buffer size must not exceed the size of an atomic write to a disk file.
89 For FreeBSD this size is unlimited. 89 For FreeBSD this size is unlimited.
90 </note> 90 </note>
91 </para> 91 </para>
92 92
93 <para> 93 <para>
114 <para> 114 <para>
115 If the <literal>gzip</literal> parameter is used, then the buffered data will 115 If the <literal>gzip</literal> parameter is used, then the buffered data will
116 be compressed before writing to the file. 116 be compressed before writing to the file.
117 The compression level can be set between 1 (fastest, less compression) 117 The compression level can be set between 1 (fastest, less compression)
118 and 9 (slowest, best compression). 118 and 9 (slowest, best compression).
119 By default the buffer size is equal to 64K bytes, and the compression level 119 By default, the buffer size is equal to 64K bytes, and the compression level
120 is set to 1. 120 is set to 1.
121 Since the data is compressed in atomic blocks, the log file can be decompressed 121 Since the data is compressed in atomic blocks, the log file can be decompressed
122 or read by “<literal>zcat</literal>” at any time. 122 or read by “<literal>zcat</literal>” at any time.
123 </para> 123 </para>
124 124
150 <listitem> 150 <listitem>
151 buffered writes do not work; 151 buffered writes do not work;
152 </listitem> 152 </listitem>
153 153
154 <listitem> 154 <listitem>
155 a file is opened and closed for each log write. 155 the file is opened and closed for each log write.
156 However, since the descriptors of frequently used files can be stored 156 However, since the descriptors of frequently used files can be stored
157 in a <link id="open_log_file_cache">cache</link>, writes during the 157 in a <link id="open_log_file_cache">cache</link>, writing to the old file
158 time specified by the <literal>valid</literal> parameter of the 158 can continue during the time specified by the <link id="open_log_file_cache"/>
159 <link id="open_log_file_cache"/> directive can continue to be made 159 directive’s <literal>valid</literal> parameter
160 to the old file.
161 </listitem> 160 </listitem>
162 161
163 <listitem> 162 <listitem>
164 during each log write the existence of the request’s 163 during each log write the existence of the request’s
165 <link doc="ngx_http_core_module.xml" id="root">root directory</link> 164 <link doc="ngx_http_core_module.xml" id="root">root directory</link>
258 <value>string</value> ...</syntax> 257 <value>string</value> ...</syntax>
259 <default>combined "..."</default> 258 <default>combined "..."</default>
260 <context>http</context> 259 <context>http</context>
261 260
262 <para> 261 <para>
263 Specifies format of a log. 262 Specifies log format.
264 </para> 263 </para>
265 264
266 <para> 265 <para>
267 The log format can contain common variables, and variables that 266 The log format can contain common variables, and variables that
268 exist only at the time of a log write: 267 exist only at the time of a log write:
283 the current number of requests made through a connection (1.1.18) 282 the current number of requests made through a connection (1.1.18)
284 </tag-desc> 283 </tag-desc>
285 284
286 <tag-name><var>$msec</var></tag-name> 285 <tag-name><var>$msec</var></tag-name>
287 <tag-desc> 286 <tag-desc>
288 time in seconds with a milliseconds resolution at the time of log write 287 time in seconds with a milliseconds resolution at the time of the log write
289 </tag-desc> 288 </tag-desc>
290 289
291 <tag-name><var>$pipe</var></tag-name> 290 <tag-name><var>$pipe</var></tag-name>
292 <tag-desc> 291 <tag-desc>
293 “<literal>p</literal>” if request was pipelined, “<literal>.</literal>” 292 “<literal>p</literal>” if request was pipelined, “<literal>.</literal>”
322 </tag-desc> 321 </tag-desc>
323 322
324 </list> 323 </list>
325 324
326 <note> 325 <note>
327 In modern versions of nginx variables 326 In the modern nginx versions variables
328 <link doc="ngx_http_core_module.xml" id="var_status">$status</link> 327 <link doc="ngx_http_core_module.xml" id="var_status">$status</link>
329 (1.3.2, 1.2.2), 328 (1.3.2, 1.2.2),
330 <link doc="ngx_http_core_module.xml" id="var_bytes_sent">$bytes_sent</link> 329 <link doc="ngx_http_core_module.xml" id="var_bytes_sent">$bytes_sent</link>
331 (1.3.8, 1.2.5), 330 (1.3.8, 1.2.5),
332 <link doc="ngx_http_core_module.xml" id="var_connection">$connection</link> 331 <link doc="ngx_http_core_module.xml" id="var_connection">$connection</link>
356 “<literal>sent_http_</literal>”, for example, 355 “<literal>sent_http_</literal>”, for example,
357 <var>$sent_http_content_range</var>. 356 <var>$sent_http_content_range</var>.
358 </para> 357 </para>
359 358
360 <para> 359 <para>
361 The configuration always includes the predefined format 360 The configuration always includes the predefined
362 “<literal>combined</literal>”: 361 “<literal>combined</literal>” format:
363 <example> 362 <example>
364 log_format combined '$remote_addr - $remote_user [$time_local] ' 363 log_format combined '$remote_addr - $remote_user [$time_local] '
365 '"$request" $status $body_bytes_sent ' 364 '"$request" $status $body_bytes_sent '
366 '"$http_referer" "$http_user_agent"'; 365 '"$http_referer" "$http_user_agent"';
367 </example> 366 </example>
382 <context>http</context> 381 <context>http</context>
383 <context>server</context> 382 <context>server</context>
384 <context>location</context> 383 <context>location</context>
385 384
386 <para> 385 <para>
387 Defines a cache that stores file descriptors of frequently used logs 386 Defines a cache that stores the file descriptors of frequently used logs
388 whose names contain variables. 387 whose names contain variables.
389 The directive has the following parameters: 388 The directive has the following parameters:
390 <list type="tag"> 389 <list type="tag">
391 390
392 <tag-name><literal>max</literal></tag-name> 391 <tag-name><literal>max</literal></tag-name>
393 <tag-desc> 392 <tag-desc>
394 sets a maximum number of descriptors in a cache; 393 sets the maximum number of descriptors in a cache;
395 if cache becomes full the least recently used (LRU) 394 if the cache becomes full the least recently used (LRU)
396 descriptors are closed 395 descriptors are closed
397 </tag-desc> 396 </tag-desc>
398 397
399 <tag-name><literal>inactive</literal></tag-name> 398 <tag-name><literal>inactive</literal></tag-name>
400 <tag-desc> 399 <tag-desc>
401 sets a time after which the cached descriptor is closed 400 sets the time after which the cached descriptor is closed
402 if there were no access during this time; 401 if there were no access during this time;
403 by default, 10 seconds 402 by default, 10 seconds
404 </tag-desc> 403 </tag-desc>
405 404
406 <tag-name><literal>min_uses</literal></tag-name> 405 <tag-name><literal>min_uses</literal></tag-name>
407 <tag-desc> 406 <tag-desc>
408 sets a minimum number of file uses during the time 407 sets the minimum number of file uses during the time
409 defined by the <literal>inactive</literal> parameter 408 defined by the <literal>inactive</literal> parameter
410 after which the descriptor will stay open in a cache; 409 to let the descriptor stay open in a cache;
411 by default, 1 410 by default, 1
412 </tag-desc> 411 </tag-desc>
413 412
414 <tag-name><literal>valid</literal></tag-name> 413 <tag-name><literal>valid</literal></tag-name>
415 <tag-desc> 414 <tag-desc>
416 sets a time after which it should be checked that the file 415 sets the time after which it should be checked that the file
417 still exists with the same name; by default, 60 seconds 416 still exists with the same name; by default, 60 seconds
418 </tag-desc> 417 </tag-desc>
419 418
420 <tag-name><literal>off</literal></tag-name> 419 <tag-name><literal>off</literal></tag-name>
421 <tag-desc> 420 <tag-desc>
424 423
425 </list> 424 </list>
426 </para> 425 </para>
427 426
428 <para> 427 <para>
429 Example usage: 428 Usage example:
430 <example> 429 <example>
431 open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2; 430 open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;
432 </example> 431 </example>
433 </para> 432 </para>
434 433