Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_log_module.xml @ 682:9d09ba854aeb
- Changed the link to WordPress.com success story
author | Andrey Alexeev <andrew@nginx.com> |
---|---|
date | Mon, 17 Sep 2012 16:22:48 +0000 |
parents | 56fa3cab4ceb |
children | d71e56d56ada |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) Igor Sysoev Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Module ngx_http_log_module" link="/en/docs/http/ngx_http_log_module.html" lang="en" rev="3"> <section id="summary"> <para> The <literal>ngx_http_log_module</literal> module writes request logs in the specified format. </para> <para> Requests are logged in a context of a location where processing ends. This may be different from the original location, if an <link doc="ngx_http_core_module.xml" id="internal">internal redirect</link> happens during request processing. </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> <value>path</value> [<value>format</value> [<literal>buffer</literal>=<value>size</value>]]</syntax> <syntax><literal>off</literal></syntax> <default>logs/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 <literal>off</literal> cancels all <literal>access_log</literal> directives on the current level. If format is not specified then the predefined format “<literal>combined</literal>” is used. </para> <para> The buffer size must not exceed the size of the atomic write to a disk file. For FreeBSD 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 <literal>valid</literal> 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 <literal>access_log</literal> 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> <value>name</value> <value>string</value> ...</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 “<literal>%B</literal>” parameter of the <literal>mod_log_config</literal> 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>$connection_requests</var></tag-name> <tag-desc> the current number of requests made through a connection </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> “<literal>p</literal>” if request was pipelined, “<literal>.</literal>” 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 between the first bytes were read from the client and the log write after the last bytes were sent to the client </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 “<literal>sent_http_</literal>”, for example, <var>$sent_http_content_range</var>. </para> <para> The configuration always includes the predefined format “<literal>combined</literal>”: <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> <literal>max</literal>=<value>N</value> [<literal>inactive</literal>=<value>time</value>] [<literal>min_uses</literal>=<value>N</value>] [<literal>valid</literal>=<value>time</value>]</syntax> <syntax><literal>off</literal></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><literal>max</literal></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><literal>inactive</literal></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><literal>min_uses</literal></tag-name> <tag-desc> sets a minimum number of file uses during the time defined by the <literal>inactive</literal> parameter after which the descriptor will stay open in a cache; by default, 1 </tag-desc> <tag-name><literal>valid</literal></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><literal>off</literal></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>