Mercurial > hg > nginx-site
changeset 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 | 09b8c8b2b865 |
children | 46ef98b7513f |
files | xml/en/GNUmakefile xml/en/docs/http/ngx_http_log_module.xml xml/en/docs/index.xml xml/en/index.xml xml/ru/docs/http/ngx_http_log_module.xml xml/ru/index.xml |
diffstat | 6 files changed, 417 insertions(+), 98 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/GNUmakefile +++ b/xml/en/GNUmakefile @@ -49,6 +49,7 @@ REFS = \ http/ngx_http_index_module \ http/ngx_http_limit_conn_module \ http/ngx_http_limit_req_module \ + http/ngx_http_log_module \ http/ngx_http_mp4_module \ http/ngx_http_random_index_module \
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>
--- a/xml/en/docs/index.xml +++ b/xml/en/docs/index.xml @@ -92,6 +92,11 @@ ngx_http_limit_req_module</a> </item> <item> +<a href="/en/docs/http/ngx_http_log_module.xml"> +ngx_http_log_module</a> +</item> + +<item> <a href="/en/docs/http/ngx_http_mp4_module.xml"> ngx_http_mp4_module</a> </item>
--- a/xml/en/index.xml +++ b/xml/en/index.xml @@ -101,7 +101,10 @@ executable</link> without interruption o </item> <item> -Access log formats, buffered log writing, and +<link doc="docs/http/ngx_http_log_module.xml" id="log_format">Access +log formats</link>, +<link doc="docs/http/ngx_http_log_module.xml" id="access_log">buffered +log writing</link>, and <link doc="docs/control.xml" id="logs">fast log rotation</link>; </item>
--- a/xml/ru/docs/http/ngx_http_log_module.xml +++ b/xml/ru/docs/http/ngx_http_log_module.xml @@ -2,47 +2,57 @@ <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> -<module name="Директивы модуля ngx_http_log_module" +<module name="Модуль ngx_http_log_module" link="/ru/docs/http/ngx_http_log_module.html" lang="ru"> <section id="summary"> <para> -Модуль ngx_http_log_module записывает логи запросов в указанном формате. +Модуль <code>ngx_http_log_module</code> записывает логи запросов +в указанном формате. </para> </section> -<section name="Пример конфигурации" id="example"> +<section id="example" name="Пример конфигурации"> <para> <example> - log_format gzip '$remote_addr - $remote_user [$time_local] ' - '"$request" $status $bytes_sent ' - '"$http_referer" "$http_user_agent" "$gzip_ratio"'; + 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; + access_log /spool/logs/nginx-access.log gzip buffer=32k; </example> </para> </section> -<section name="Директивы" id="directives"> +<section id="directives" name="Директивы"> <directive name="access_log"> -<syntax><value>путь [формат [buffer=размер]]|off</value> -</syntax> +<syntax> + <argument>путь</argument> + [<argument>формат</argument> + [<parameter>buffer</parameter>=<argument>размер</argument>]]</syntax> +<syntax><value>off</value></syntax> <default>log/access.log combined</default> -<context>http, server, location, if в location, limit_except</context> +<context>http</context> +<context>server</context> +<context>location</context> +<context>if в location</context> +<context>limit_except</context> <para> -Директива access_log задаёт путь, формат и размер буфера для буферизированной -записи в лог. На одном уровне может использоваться несколько логов. -Параметр "off" отменяет все директивы access_log для текущего уровня. -Если формат не указан, то используется предопределённый формат "combined". +Задаёт путь, формат и размер буфера для буферизованной записи в лог. +На одном уровне может использоваться несколько логов. +Специальное значение <value>off</value> отменяет все директивы +<code>access_log</code> для текущего уровня. +Если формат не указан, то используется предопределённый формат +“<code>combined</code>”. </para> <para> @@ -56,7 +66,8 @@ <list type="bullet"> <listitem> -пользователь, с правами которого работают рабочие процессы, должен +<link doc="../ngx_core_module.xml" id="user">пользователь</link>, +с правами которого работают рабочие процессы, должен иметь права на создание файлов в каталоге с такими логами; </listitem> @@ -66,22 +77,23 @@ <listitem> файл открывается для каждой записи в лог и сразу же после записи закрывается. -Но дескрипторы часто используемых файлов могут храниться в -<link id="open_log_file_cache"/>. -При вращении логов нужно иметь в виду, что в течение времени, заданного -параметром valid директивы <link id="open_log_file_cache"/>, +Следует однако иметь в виду, что поскольку дескрипторы часто используемых файлов +могут храниться в <link id="open_log_file_cache">кэше</link>, +то при вращении логов в течение времени, заданного параметром +<parameter>valid</parameter> директивы <link id="open_log_file_cache"/>, запись может продолжаться в старый файл. </listitem> <listitem> -при каждой записи в лог проверяется существование каталога root'а для -запроса — если этот каталог не существует, то лог не создаётся. +при каждой записи в лог проверяется существование +<link doc="ngx_http_core_module.xml" id="root">корневого каталога</link> +для запроса — если этот каталог не существует, то лог не создаётся. Поэтому <link doc="ngx_http_core_module.xml" id="root"/> -и access_log нужно описывать на одном уровне: +и <code>access_log</code> нужно описывать на одном уровне: <example> server { - root /spool/vhost/data/$host; - access_log /spool/vhost/logs/$host; + root /spool/vhost/data/$host; + access_log /spool/vhost/logs/$host; ... </example> </listitem> @@ -93,71 +105,91 @@ server { <directive name="log_format"> -<syntax><value>название строка [строка ...]</value> +<syntax> +<argument>название строка ...</argument> </syntax> -<default>combined "..." </default> +<default>combined "..."</default> <context>http</context> <para> -Директива log_format описывает формат лога. +Задаёт формат лога. </para> <para> Кроме общих переменных в формате можно использовать переменные, существующие только на момент записи в лог: -<list type="bullet"> +<list type="tag"> -<listitem> -$body_bytes_sent, число байт, переданное клиенту за вычетом заголовка ответа, -переменная совместима с параметром %B модуля Apache mod_log_config; -</listitem> +<tag-name><var>$body_bytes_sent</var></tag-name> +<tag-desc> +число байт, переданных клиенту, за вычетом заголовка ответа; +переменная совместима с параметром “<code>%B</code>” модуля Apache +<code>mod_log_config</code> +</tag-desc> -<listitem> -$bytes_sent, число байт, переданное клиенту; -</listitem> +<tag-name><var>$bytes_sent</var></tag-name> +<tag-desc> +число байт, переданных клиенту +</tag-desc> -<listitem> -$connection, номер соединения; -</listitem> +<tag-name><var>$connection</var></tag-name> +<tag-desc> +порядковый номер соединения +</tag-desc> -<listitem> -$msec, время в секундах с точностью до миллисекунд на момент записи в лог; -</listitem> +<tag-name><var>$msec</var></tag-name> +<tag-desc> +время в секундах с точностью до миллисекунд на момент записи в лог +</tag-desc> -<listitem> -$pipe, "p" если запрос был pipelined; -</listitem> +<tag-name><var>$pipe</var></tag-name> +<tag-desc> +“<code>p</code>” если запрос был pipelined, иначе “<code>.</code>” +</tag-desc> -<listitem> -$request_length, длина тела запроса; -</listitem> +<tag-name><var>$request_length</var></tag-name> +<tag-desc> +длина запроса (включая строку запроса, заголовок и тело запроса) +</tag-desc> -<listitem> -$request_time, время обработки запроса в секундах с точностью до миллисекунд; -</listitem> +<tag-name><var>$request_time</var></tag-name> +<tag-desc> +время обработки запроса в секундах с точностью до миллисекунд; +время, прошедшее с момента чтения первых байт от клиента до +момента отправки последних байт клиенту и записи в лог +</tag-desc> -<listitem> -$status, статус ответа; -</listitem> +<tag-name><var>$status</var></tag-name> +<tag-desc> +статус ответа +</tag-desc> -<listitem> -$time_local, локальное время в common log format. -</listitem> +<tag-name><var>$time_iso8601</var></tag-name> +<tag-desc> +локальное время в формате по стандарту ISO 8601 +</tag-desc> + +<tag-name><var>$time_local</var></tag-name> +<tag-desc> +локальное время в Common Log Format +</tag-desc> </list> </para> <para> -Строки заголовка, переданные клиенту, начинаются с префикса "sent_http_", -например, $sent_http_content_range. +Строки заголовка, переданные клиенту, начинаются с префикса +“<code>sent_http_</code>”, например, +<var>$sent_http_content_range</var>. </para> <para> -В конфигурации всегда существует предопределённый формат "combined": +В конфигурации всегда существует предопределённый формат +“<code>combined</code>”: <example> - log_format combined '$remote_addr - $remote_user [$time_local] ' - '"$request" $status $body_bytes_sent ' - '"$http_referer" "$http_user_agent"'; + log_format combined '$remote_addr - $remote_user [$time_local] ' + '"$request" $status $body_bytes_sent ' + '"$http_referer" "$http_user_agent"'; </example> </para> @@ -165,49 +197,56 @@ server { <directive name="open_log_file_cache"> -<syntax><value>max=N [inactive=время]|off</value> -</syntax> +<syntax> +<parameter>max</parameter>=<argument>N</argument> +[<parameter>inactive</parameter>=<argument>время</argument>] +[<parameter>min_uses</parameter>=<argument>N</argument>] +[<parameter>valid</parameter>=<argument>время</argument>]</syntax> +<syntax><value>off</value></syntax> <default>off</default> -<context>http, server, location</context> - -<para> -Директива задаёт кэш, в котором хранятся дескрипторы файлов часто используемых -логов, имена которых заданы переменными. -</para> +<context>http</context> +<context>server</context> +<context>location</context> <para> +Задаёт кэш, в котором хранятся дескрипторы файлов часто используемых +логов, имена которых заданы с использованием переменных. Параметры директивы: -<list type="bullet"> +<list type="tag"> -<listitem> -max — задаёт маскимальное число дескрипторов в кэше; -при переполнении кэша наиболее давно не используемые дескрипторы закрываются -(LRU); -</listitem> +<tag-name><parameter>max</parameter></tag-name> +<tag-desc> +задаёт максимальное число дескрипторов в кэше; +при переполнении кэша наиболее давно не используемые (LRU) +дескрипторы закрываются +</tag-desc> -<listitem> -inactive — задаёт время, после которого дескриптор кэша закрывается, +<tag-name><parameter>inactive</parameter></tag-name> +<tag-desc> +задаёт время, после которого закэшированный дескриптор закрывается, если к нему не было обращений в течение этого времени; -по умолчанию 10 секунд; -</listitem> +по умолчанию 10 секунд +</tag-desc> -<listitem> -min_uses — задаёт минимальное число использований файла в течение -времени, заданного параметром inactive в директиве -<link id="open_log_file_cache"/>, после которого дескриптор файла -будет оставаться окрытым в кэше; -по умолчанию 1 использование; -</listitem> +<tag-name><parameter>min_uses</parameter></tag-name> +<tag-desc> +задаёт минимальное число использований файла в течение +времени, заданного параметром <parameter>inactive</parameter>, +после которого дескриптор файла будет оставаться открытым в кэше; +по умолчанию 1 +</tag-desc> -<listitem> -valid — задаёт, через какое время нужно проверять, что файл ещё +<tag-name><parameter>valid</parameter></tag-name> +<tag-desc> +задаёт, через какое время нужно проверять, что файл ещё существует под тем же именем; -по умолчанию 60 секунд; -</listitem> +по умолчанию 60 секунд +</tag-desc> -<listitem> -off — запрещает кэш. -</listitem> +<tag-name><value>off</value></tag-name> +<tag-desc> +запрещает кэш +</tag-desc> </list> </para> @@ -215,7 +254,7 @@ off — запрещает кэш. <para> Пример использования: <example> -open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2; +open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2; </example> </para>
--- a/xml/ru/index.xml +++ b/xml/ru/index.xml @@ -119,7 +119,10 @@ chunked ответы, </item> <item> -<link doc="docs/http/ngx_http_log_module.xml">Настройка форматов логов</link>, +<link doc="docs/http/ngx_http_log_module.xml" id="log_format">Настройка +форматов логов</link>, +<link doc="docs/http/ngx_http_log_module.xml" id="access_log">буферизованная +запись в лог</link>, <link doc="docs/control.xml" id="logs">быстрая ротация логов</link>; </item>