Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_log_module.xml @ 2455:a81518fa3802
Removed obsolete note from Russian njs Reference.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Thu, 31 Oct 2019 15:34:18 +0300 |
parents | 64004f50b9dd |
children | b686736680e3 |
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="19"> <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 the context of a location where processing ends. It 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 compression '$remote_addr - $remote_user [$time_local] ' '"$request" $status $bytes_sent ' '"$http_referer" "$http_user_agent" "$gzip_ratio"'; access_log /spool/logs/nginx-access.log compression 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>] [<literal>gzip[=<value>level</value>]</literal>] [<literal>flush</literal>=<value>time</value>] [<literal>if</literal>=<value>condition</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 configuration for a buffered log write. Several logs can be specified on the same level. Logging to <link doc="../syslog.xml">syslog</link> can be configured by specifying the “<literal>syslog:</literal>” prefix in the first parameter. The special value <literal>off</literal> cancels all <literal>access_log</literal> directives on the current level. If the format is not specified then the predefined “<literal>combined</literal>” format is used. </para> <para> If either the <literal>buffer</literal> or <literal>gzip</literal> (1.3.10, 1.2.7) parameter is used, writes to log will be buffered. <note> The buffer size must not exceed the size of an atomic write to a disk file. For FreeBSD this size is unlimited. </note> </para> <para> When buffering is enabled, the data will be written to the file: <list type="bullet"> <listitem> if the next log line does not fit into the buffer; </listitem> <listitem> if the buffered data is older than specified by the <literal>flush</literal> parameter (1.3.10, 1.2.7); </listitem> <listitem> when a worker process is <link doc="../control.xml">re-opening</link> log files or is shutting down. </listitem> </list> </para> <para> If the <literal>gzip</literal> parameter is used, then the buffered data will be compressed before writing to the file. The compression level can be set between 1 (fastest, less compression) and 9 (slowest, best compression). By default, the buffer size is equal to 64K bytes, and the compression level is set to 1. Since the data is compressed in atomic blocks, the log file can be decompressed or read by “<literal>zcat</literal>” at any time. </para> <para> Example: <example> access_log /path/to/log.gz combined gzip flush=5m; </example> </para> <para> <note> For gzip compression to work, nginx must be built with the zlib library. </note> </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> the 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>, writing to the old file can continue during the time specified by the <link id="open_log_file_cache"/> directive’s <literal>valid</literal> parameter </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> <para> The <literal>if</literal> parameter (1.7.0) enables conditional logging. A request will not be logged if the <value>condition</value> evaluates to “0” or an empty string. In the following example, the requests with response codes 2xx and 3xx will not be logged: <example> map $status $loggable { ~^[23] 0; default 1; } access_log /path/to/access.log combined if=$loggable; </example> </para> </directive> <directive name="log_format"> <syntax> <value>name</value> [<literal>escape</literal>=<literal>default</literal>|<literal>json</literal>|<literal>none</literal>] <value>string</value> ...</syntax> <default>combined "..."</default> <context>http</context> <para> Specifies log format. </para> <para id="log_format_escape"> The <literal>escape</literal> parameter (1.11.8) allows setting <literal>json</literal> or <literal>default</literal> characters escaping in variables, by default, <literal>default</literal> escaping is used. The <literal>none</literal> value (1.13.10) disables escaping. </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 id="var_bytes_sent"><var>$bytes_sent</var></tag-name> <tag-desc> the number of bytes sent to a client </tag-desc> <tag-name id="var_connection"><var>$connection</var></tag-name> <tag-desc> connection serial number </tag-desc> <tag-name id="var_connection_requests"><var>$connection_requests</var> </tag-name> <tag-desc> the current number of requests made through a connection (1.1.18) </tag-desc> <tag-name id="var_msec"><var>$msec</var></tag-name> <tag-desc> time in seconds with a milliseconds resolution at the time of the log write </tag-desc> <tag-name id="var_pipe"><var>$pipe</var></tag-name> <tag-desc> “<literal>p</literal>” if request was pipelined, “<literal>.</literal>” otherwise </tag-desc> <tag-name id="var_request_length"><var>$request_length</var></tag-name> <tag-desc> request length (including request line, header, and request body) </tag-desc> <tag-name id="var_request_time"><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 id="var_status"><var>$status</var></tag-name> <tag-desc> response status </tag-desc> <tag-name id="var_time_iso8601"><var>$time_iso8601</var></tag-name> <tag-desc> local time in the ISO 8601 standard format </tag-desc> <tag-name id="var_time_local"><var>$time_local</var></tag-name> <tag-desc> local time in the Common Log Format </tag-desc> </list> <note> In the modern nginx versions variables <link doc="ngx_http_core_module.xml" id="var_status">$status</link> (1.3.2, 1.2.2), <link doc="ngx_http_core_module.xml" id="var_bytes_sent">$bytes_sent</link> (1.3.8, 1.2.5), <link doc="ngx_http_core_module.xml" id="var_connection">$connection</link> (1.3.8, 1.2.5), <link doc="ngx_http_core_module.xml" id="var_connection_requests">$connection_requests</link> (1.3.8, 1.2.5), <link doc="ngx_http_core_module.xml" id="var_msec">$msec</link> (1.3.9, 1.2.6), <link doc="ngx_http_core_module.xml" id="var_request_time">$request_time</link> (1.3.9, 1.2.6), <link doc="ngx_http_core_module.xml" id="var_pipe">$pipe</link> (1.3.12, 1.2.7), <link doc="ngx_http_core_module.xml" id="var_request_length">$request_length</link> (1.3.12, 1.2.7), <link doc="ngx_http_core_module.xml" id="var_time_iso8601">$time_iso8601</link> (1.3.12, 1.2.7), and <link doc="ngx_http_core_module.xml" id="var_time_local">$time_local</link> (1.3.12, 1.2.7) are also available as common variables. </note> </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 “<literal>combined</literal>” format: <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 the 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 the maximum number of descriptors in a cache; if the cache becomes full the least recently used (LRU) descriptors are closed </tag-desc> <tag-name><literal>inactive</literal></tag-name> <tag-desc> sets the 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 the minimum number of file uses during the time defined by the <literal>inactive</literal> parameter to let the descriptor stay open in a cache; by default, 1 </tag-desc> <tag-name><literal>valid</literal></tag-name> <tag-desc> sets the 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> Usage example: <example> open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2; </example> </para> </directive> </section> </module>