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

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
line wrap: on
line diff
new file mode 100644
--- /dev/null
+++ b/xml/en/docs/http/ngx_http_log_module.xml
@@ -0,0 +1,268 @@
+<?xml version="1.0"?>
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Module ngx_http_log_module"
+        link="/en/docs/http/ngx_http_log_module.html"
+        lang="en">
+
+<section id="summary">
+
+<para>
+The <code>ngx_http_log_module</code> module writes request logs
+in the specified format.
+</para>
+
+</section>
+
+
+<section id="example" name="Example Configuration">
+
+<para>
+<example>
+    log_format gzip '$remote_addr - $remote_user [$time_local] '
+                    '"$request" $status $bytes_sent '
+                    '"$http_referer" "$http_user_agent" "$gzip_ratio"';
+
+    access_log /spool/logs/nginx-access.log gzip buffer=32k;
+</example>
+</para>
+
+</section>
+
+
+<section id="directives" name="Directives">
+
+<directive name="access_log">
+<syntax>
+  <argument>path</argument>
+  [<argument>format</argument>
+  [<parameter>buffer</parameter>=<argument>size</argument>]]</syntax>
+<syntax><value>off</value></syntax>
+<default>log/access.log combined</default>
+<context>http</context>
+<context>server</context>
+<context>location</context>
+<context>if in location</context>
+<context>limit_except</context>
+
+<para>
+Sets the path, format, and buffer size for the buffered log writes.
+Several logs can be specified on the same level.
+The special value <value>off</value> cancels all <code>access_log</code>
+directives on the current level.
+If format is not specified then the predefined format
+“<code>combined</code>” is used.
+</para>
+
+<para>
+The buffer size must not exceed the size of the atomic write to a disk file.
+For FreeBSD 3.0-6.0 this size is unlimited.
+</para>
+
+<para>
+The file path can contain variables (0.7.6+),
+but such logs have some constraints:
+<list type="bullet">
+
+<listitem>
+the <link doc="../ngx_core_module.xml" id="user"/>
+whose credentials are used by worker processes should
+have permissions to create files in a directory with
+such logs;
+</listitem>
+
+<listitem>
+buffered writes do not work;
+</listitem>
+
+<listitem>
+a file is opened and closed for each log write.
+However, since the descriptors of frequently used files can be stored
+in a <link id="open_log_file_cache">cache</link>, writes during the
+time specified by the <parameter>valid</parameter> parameter of the
+<link id="open_log_file_cache"/> directive can continue to be made
+to the old file.
+</listitem>
+
+<listitem>
+during each log write the existence of the request’s
+<link doc="ngx_http_core_module.xml" id="root">root directory</link>
+is checked, and if it does not exist the log is not
+created.
+It is thus a good idea to specify both
+<link doc="ngx_http_core_module.xml" id="root"/>
+and <code>access_log</code> on the same level:
+<example>
+server {
+    root       /spool/vhost/data/$host;
+    access_log /spool/vhost/logs/$host;
+    ...
+</example>
+</listitem>
+
+</list>
+</para>
+
+</directive>
+
+
+<directive name="log_format">
+<syntax>
+<argument>name string ...</argument>
+</syntax>
+<default>combined "..."</default>
+<context>http</context>
+
+<para>
+Specifies format of a log.
+</para>
+
+<para>
+The log format can contain common variables, and variables that
+exist only at the time of a log write:
+<list type="tag">
+
+<tag-name><var>$body_bytes_sent</var></tag-name>
+<tag-desc>
+the number of bytes sent to a client not counting the response header;
+this variable is compatible with the “<code>%B</code>” parameter of the
+<code>mod_log_config</code>
+Apache module
+</tag-desc>
+
+<tag-name><var>$bytes_sent</var></tag-name>
+<tag-desc>
+the number of bytes sent to a client
+</tag-desc>
+
+<tag-name><var>$connection</var></tag-name>
+<tag-desc>
+connection serial number
+</tag-desc>
+
+<tag-name><var>$msec</var></tag-name>
+<tag-desc>
+time in seconds with a milliseconds resolution at the time of log write
+</tag-desc>
+
+<tag-name><var>$pipe</var></tag-name>
+<tag-desc>
+“<code>p</code>” if request was pipelined, “<code>.</code>” otherwise
+</tag-desc>
+
+<tag-name><var>$request_length</var></tag-name>
+<tag-desc>
+request length (including request line, header, and request body)
+</tag-desc>
+
+<tag-name><var>$request_time</var></tag-name>
+<tag-desc>
+request processing time in seconds with a milliseconds resolution;
+time elapsed since first bytes were read from the client till
+last bytes were sent to client and logging happened
+</tag-desc>
+
+<tag-name><var>$status</var></tag-name>
+<tag-desc>
+response status
+</tag-desc>
+
+<tag-name><var>$time_iso8601</var></tag-name>
+<tag-desc>
+local time in the ISO 8601 standard format
+</tag-desc>
+
+<tag-name><var>$time_local</var></tag-name>
+<tag-desc>
+local time in the Common Log Format
+</tag-desc>
+
+</list>
+</para>
+
+<para>
+Header lines sent to a client have the prefix
+“<code>sent_http_</code>”, for example,
+<var>$sent_http_content_range</var>.
+</para>
+
+<para>
+The configuration always includes the predefined format
+“<code>combined</code>”:
+<example>
+    log_format combined '$remote_addr - $remote_user [$time_local] '
+                        '"$request" $status $body_bytes_sent '
+                        '"$http_referer" "$http_user_agent"';
+</example>
+</para>
+
+</directive>
+
+<directive name="open_log_file_cache">
+
+<syntax>
+<parameter>max</parameter>=<argument>N</argument>
+[<parameter>inactive</parameter>=<argument>time</argument>]
+[<parameter>min_uses</parameter>=<argument>N</argument>]
+[<parameter>valid</parameter>=<argument>time</argument>]</syntax>
+<syntax><value>off</value></syntax>
+<default>off</default>
+<context>http</context>
+<context>server</context>
+<context>location</context>
+
+<para>
+Defines a cache that stores file descriptors of frequently used logs
+whose names contain variables.
+The directive has the following parameters:
+<list type="tag">
+
+<tag-name><parameter>max</parameter></tag-name>
+<tag-desc>
+sets a maximum number of descriptors in a cache;
+if cache becomes full the least recently used (LRU)
+descriptors are closed
+</tag-desc>
+
+<tag-name><parameter>inactive</parameter></tag-name>
+<tag-desc>
+sets a time after which the cached descriptor is closed
+if there were no access during this time;
+by default, 10 seconds
+</tag-desc>
+
+<tag-name><parameter>min_uses</parameter></tag-name>
+<tag-desc>
+sets a minimum number of file uses during the time
+defined by the <parameter>inactive</parameter> parameter
+after which the descriptor will stay open in a cache;
+by default, 1
+</tag-desc>
+
+<tag-name><parameter>valid</parameter></tag-name>
+<tag-desc>
+sets a time after which it should be checked that the file
+still exists with the same name; by default, 60 seconds
+</tag-desc>
+
+<tag-name><value>off</value></tag-name>
+<tag-desc>
+disables caching
+</tag-desc>
+
+</list>
+</para>
+
+<para>
+Example usage:
+<example>
+open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;
+</example>
+</para>
+
+</directive>
+
+</section>
+
+</module>