# HG changeset patch
# User Ruslan Ermilov <ru@nginx.com>
# Date 1323156325 0
# Node ID 7f36795d99a2eab19e02c9aa17e4db7ebd95f536
# Parent  09b8c8b2b865e21f73e37afc7860807d7894cfde
Updated ngx_http_log_module documentation including translation into English.

diff -r 09b8c8b2b865 -r 7f36795d99a2 xml/en/GNUmakefile
--- a/xml/en/GNUmakefile	Tue Dec 06 07:19:07 2011 +0000
+++ b/xml/en/GNUmakefile	Tue Dec 06 07:25:25 2011 +0000
@@ -49,6 +49,7 @@
 		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			\
 
diff -r 09b8c8b2b865 -r 7f36795d99a2 xml/en/docs/http/ngx_http_log_module.xml
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/xml/en/docs/http/ngx_http_log_module.xml	Tue Dec 06 07:25:25 2011 +0000
@@ -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>
diff -r 09b8c8b2b865 -r 7f36795d99a2 xml/en/docs/index.xml
--- a/xml/en/docs/index.xml	Tue Dec 06 07:19:07 2011 +0000
+++ b/xml/en/docs/index.xml	Tue Dec 06 07:25:25 2011 +0000
@@ -92,6 +92,11 @@
 </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>
diff -r 09b8c8b2b865 -r 7f36795d99a2 xml/en/index.xml
--- a/xml/en/index.xml	Tue Dec 06 07:19:07 2011 +0000
+++ b/xml/en/index.xml	Tue Dec 06 07:25:25 2011 +0000
@@ -101,7 +101,10 @@
 </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>
 
diff -r 09b8c8b2b865 -r 7f36795d99a2 xml/ru/docs/http/ngx_http_log_module.xml
--- a/xml/ru/docs/http/ngx_http_log_module.xml	Tue Dec 06 07:19:07 2011 +0000
+++ b/xml/ru/docs/http/ngx_http_log_module.xml	Tue Dec 06 07:25:25 2011 +0000
@@ -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 @@
 
 
 <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 @@
 
 <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 @@
 <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>
 
diff -r 09b8c8b2b865 -r 7f36795d99a2 xml/ru/index.xml
--- a/xml/ru/index.xml	Tue Dec 06 07:19:07 2011 +0000
+++ b/xml/ru/index.xml	Tue Dec 06 07:25:25 2011 +0000
@@ -119,7 +119,10 @@
 </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>