changeset 795:41363f013cc9

Documented the recently added "gzip" and "flush" parameters of the "access_log" directive.
author Valentin Bartenev <vbart@nginx.com>
date Tue, 25 Dec 2012 15:23:24 +0000
parents e77512b1ce11
children a2f75649204c
files xml/en/docs/http/ngx_http_log_module.xml xml/ru/docs/http/ngx_http_log_module.xml
diffstat 2 files changed, 126 insertions(+), 14 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_log_module.xml
+++ b/xml/en/docs/http/ngx_http_log_module.xml
@@ -10,7 +10,7 @@
 <module name="Module ngx_http_log_module"
         link="/en/docs/http/ngx_http_log_module.html"
         lang="en"
-        rev="6">
+        rev="7">
 
 <section id="summary">
 
@@ -33,11 +33,11 @@ redirect</link> happens during request p
 
 <para>
 <example>
-log_format gzip '$remote_addr - $remote_user [$time_local] '
-                '"$request" $status $bytes_sent '
-                '"$http_referer" "$http_user_agent" "$gzip_ratio"';
+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 gzip buffer=32k;
+access_log /spool/logs/nginx-access.log compression buffer=32k;
 </example>
 </para>
 
@@ -50,7 +50,14 @@ access_log /spool/logs/nginx-access.log 
 <syntax>
     <value>path</value>
     [<value>format</value>
-    [<literal>buffer</literal>=<value>size</value>]]</syntax>
+    [<literal>buffer</literal>=<value>size</value>
+    [<literal>flush</literal>=<value>time</value>]]]</syntax>
+<syntax>
+    <value>path</value>
+    <value>format</value>
+    <literal>gzip[=<value>level</value>]</literal>
+    [<literal>buffer</literal>=<value>size</value>]
+    [<literal>flush</literal>=<value>time</value>]</syntax>
 <syntax><literal>off</literal></syntax>
 <default>logs/access.log combined</default>
 <context>http</context>
@@ -60,7 +67,7 @@ access_log /spool/logs/nginx-access.log 
 <context>limit_except</context>
 
 <para>
-Sets the path, format, and buffer size for the buffered log writes.
+Sets the path, format, and configuration of 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.
@@ -69,8 +76,57 @@ If format is not specified then the pred
 </para>
 
 <para>
+If either the <literal>buffer</literal> or <literal>gzip</literal> (1.3.10)
+parameter is used, writes to log will be buffered.
+<note>
 The buffer size must not exceed the size of the 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);
+</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>
--- a/xml/ru/docs/http/ngx_http_log_module.xml
+++ b/xml/ru/docs/http/ngx_http_log_module.xml
@@ -10,7 +10,7 @@
 <module name="Модуль ngx_http_log_module"
         link="/ru/docs/http/ngx_http_log_module.html"
         lang="ru"
-        rev="6">
+        rev="7">
 
 <section id="summary">
 
@@ -34,11 +34,11 @@
 
 <para>
 <example>
-log_format gzip '$remote_addr - $remote_user [$time_local] '
-                '"$request" $status $bytes_sent '
-                '"$http_referer" "$http_user_agent" "$gzip_ratio"';
+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 gzip buffer=32k;
+access_log /spool/logs/nginx-access.log compression buffer=32k;
 </example>
 </para>
 
@@ -51,7 +51,14 @@ access_log /spool/logs/nginx-access.log 
 <syntax>
     <value>путь</value>
     [<value>формат</value>
-    [<literal>buffer</literal>=<value>размер</value>]]</syntax>
+    [<literal>buffer</literal>=<value>размер</value>
+    [<literal>flush</literal>=<value>время</value>]]]</syntax>
+<syntax>
+    <value>путь</value>
+    <value>формат</value>
+    <literal>gzip[=<value>степень</value>]</literal>
+    [<literal>buffer</literal>=<value>размер</value>]
+    [<literal>flush</literal>=<value>время</value>]</syntax>
 <syntax><literal>off</literal></syntax>
 <default>logs/access.log combined</default>
 <context>http</context>
@@ -61,7 +68,7 @@ access_log /spool/logs/nginx-access.log 
 <context>limit_except</context>
 
 <para>
-Задаёт путь, формат и размер буфера для буферизованной записи в лог.
+Задаёт путь, формат и настройки буферизованной записи в лог.
 На одном уровне может использоваться несколько логов.
 Специальное значение <literal>off</literal> отменяет все директивы
 <literal>access_log</literal> для текущего уровня.
@@ -70,8 +77,57 @@ access_log /spool/logs/nginx-access.log 
 </para>
 
 <para>
+Если задан размер буфера с помощью параметра <literal>buffer</literal> или
+указан параметр <literal>gzip</literal> (1.3.10), то запись будет
+буферизованной.
+<note>
 Размер буфера должен быть не больше размера атомарной записи в дисковый файл.
 Для FreeBSD этот размер неограничен.
+</note>
+</para>
+
+<para>
+При включённой буферизации данные записываются в файл:
+<list type="bullet">
+
+<listitem>
+если очередная строка лога не помещается в буфер;
+</listitem>
+
+<listitem>
+если данные в буфере находятся дольше интервала времени, заданного
+параметром <literal>flush</literal> (1.3.10);
+</listitem>
+
+<listitem>
+при <link doc="../control.xml">переоткрытии</link> лог-файла или
+завершении рабочего процесса.
+</listitem>
+
+</list>
+</para>
+
+<para>
+Если задан параметр <literal>gzip</literal>, то буфер будет сжиматься перед
+записью в файл.
+Степень сжатия может быть задана в диапазоне от 1 (быстрее, но хуже сжатие)
+до 9 (медленнее, но лучше сжатие).
+По умолчанию используется буфер размером 64К байт и степень сжатия 1.
+Данные сжимаются атомарными блоками, и в любой момент времени лог-файл может
+быть распакован или прочитан с помощью утилиты “<literal>zcat</literal>”.
+</para>
+
+<para>
+Пример:
+<example>
+access_log /path/to/log.gz combined gzip flush=5m;
+</example>
+</para>
+
+<para>
+<note>
+Для поддержки gzip-сжатия логов nginx должен быть собран с библиотекой zlib.
+</note>
 </para>
 
 <para>