Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_log_module.xml @ 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 | |
children | 945d7299c26c |
comparison
equal
deleted
inserted
replaced
223:09b8c8b2b865 | 224:7f36795d99a2 |
---|---|
1 <?xml version="1.0"?> | |
2 | |
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> | |
4 | |
5 <module name="Module ngx_http_log_module" | |
6 link="/en/docs/http/ngx_http_log_module.html" | |
7 lang="en"> | |
8 | |
9 <section id="summary"> | |
10 | |
11 <para> | |
12 The <code>ngx_http_log_module</code> module writes request logs | |
13 in the specified format. | |
14 </para> | |
15 | |
16 </section> | |
17 | |
18 | |
19 <section id="example" name="Example Configuration"> | |
20 | |
21 <para> | |
22 <example> | |
23 log_format gzip '$remote_addr - $remote_user [$time_local] ' | |
24 '"$request" $status $bytes_sent ' | |
25 '"$http_referer" "$http_user_agent" "$gzip_ratio"'; | |
26 | |
27 access_log /spool/logs/nginx-access.log gzip buffer=32k; | |
28 </example> | |
29 </para> | |
30 | |
31 </section> | |
32 | |
33 | |
34 <section id="directives" name="Directives"> | |
35 | |
36 <directive name="access_log"> | |
37 <syntax> | |
38 <argument>path</argument> | |
39 [<argument>format</argument> | |
40 [<parameter>buffer</parameter>=<argument>size</argument>]]</syntax> | |
41 <syntax><value>off</value></syntax> | |
42 <default>log/access.log combined</default> | |
43 <context>http</context> | |
44 <context>server</context> | |
45 <context>location</context> | |
46 <context>if in location</context> | |
47 <context>limit_except</context> | |
48 | |
49 <para> | |
50 Sets the path, format, and buffer size for the buffered log writes. | |
51 Several logs can be specified on the same level. | |
52 The special value <value>off</value> cancels all <code>access_log</code> | |
53 directives on the current level. | |
54 If format is not specified then the predefined format | |
55 “<code>combined</code>” is used. | |
56 </para> | |
57 | |
58 <para> | |
59 The buffer size must not exceed the size of the atomic write to a disk file. | |
60 For FreeBSD 3.0-6.0 this size is unlimited. | |
61 </para> | |
62 | |
63 <para> | |
64 The file path can contain variables (0.7.6+), | |
65 but such logs have some constraints: | |
66 <list type="bullet"> | |
67 | |
68 <listitem> | |
69 the <link doc="../ngx_core_module.xml" id="user"/> | |
70 whose credentials are used by worker processes should | |
71 have permissions to create files in a directory with | |
72 such logs; | |
73 </listitem> | |
74 | |
75 <listitem> | |
76 buffered writes do not work; | |
77 </listitem> | |
78 | |
79 <listitem> | |
80 a file is opened and closed for each log write. | |
81 However, since the descriptors of frequently used files can be stored | |
82 in a <link id="open_log_file_cache">cache</link>, writes during the | |
83 time specified by the <parameter>valid</parameter> parameter of the | |
84 <link id="open_log_file_cache"/> directive can continue to be made | |
85 to the old file. | |
86 </listitem> | |
87 | |
88 <listitem> | |
89 during each log write the existence of the request’s | |
90 <link doc="ngx_http_core_module.xml" id="root">root directory</link> | |
91 is checked, and if it does not exist the log is not | |
92 created. | |
93 It is thus a good idea to specify both | |
94 <link doc="ngx_http_core_module.xml" id="root"/> | |
95 and <code>access_log</code> on the same level: | |
96 <example> | |
97 server { | |
98 root /spool/vhost/data/$host; | |
99 access_log /spool/vhost/logs/$host; | |
100 ... | |
101 </example> | |
102 </listitem> | |
103 | |
104 </list> | |
105 </para> | |
106 | |
107 </directive> | |
108 | |
109 | |
110 <directive name="log_format"> | |
111 <syntax> | |
112 <argument>name string ...</argument> | |
113 </syntax> | |
114 <default>combined "..."</default> | |
115 <context>http</context> | |
116 | |
117 <para> | |
118 Specifies format of a log. | |
119 </para> | |
120 | |
121 <para> | |
122 The log format can contain common variables, and variables that | |
123 exist only at the time of a log write: | |
124 <list type="tag"> | |
125 | |
126 <tag-name><var>$body_bytes_sent</var></tag-name> | |
127 <tag-desc> | |
128 the number of bytes sent to a client not counting the response header; | |
129 this variable is compatible with the “<code>%B</code>” parameter of the | |
130 <code>mod_log_config</code> | |
131 Apache module | |
132 </tag-desc> | |
133 | |
134 <tag-name><var>$bytes_sent</var></tag-name> | |
135 <tag-desc> | |
136 the number of bytes sent to a client | |
137 </tag-desc> | |
138 | |
139 <tag-name><var>$connection</var></tag-name> | |
140 <tag-desc> | |
141 connection serial number | |
142 </tag-desc> | |
143 | |
144 <tag-name><var>$msec</var></tag-name> | |
145 <tag-desc> | |
146 time in seconds with a milliseconds resolution at the time of log write | |
147 </tag-desc> | |
148 | |
149 <tag-name><var>$pipe</var></tag-name> | |
150 <tag-desc> | |
151 “<code>p</code>” if request was pipelined, “<code>.</code>” otherwise | |
152 </tag-desc> | |
153 | |
154 <tag-name><var>$request_length</var></tag-name> | |
155 <tag-desc> | |
156 request length (including request line, header, and request body) | |
157 </tag-desc> | |
158 | |
159 <tag-name><var>$request_time</var></tag-name> | |
160 <tag-desc> | |
161 request processing time in seconds with a milliseconds resolution; | |
162 time elapsed since first bytes were read from the client till | |
163 last bytes were sent to client and logging happened | |
164 </tag-desc> | |
165 | |
166 <tag-name><var>$status</var></tag-name> | |
167 <tag-desc> | |
168 response status | |
169 </tag-desc> | |
170 | |
171 <tag-name><var>$time_iso8601</var></tag-name> | |
172 <tag-desc> | |
173 local time in the ISO 8601 standard format | |
174 </tag-desc> | |
175 | |
176 <tag-name><var>$time_local</var></tag-name> | |
177 <tag-desc> | |
178 local time in the Common Log Format | |
179 </tag-desc> | |
180 | |
181 </list> | |
182 </para> | |
183 | |
184 <para> | |
185 Header lines sent to a client have the prefix | |
186 “<code>sent_http_</code>”, for example, | |
187 <var>$sent_http_content_range</var>. | |
188 </para> | |
189 | |
190 <para> | |
191 The configuration always includes the predefined format | |
192 “<code>combined</code>”: | |
193 <example> | |
194 log_format combined '$remote_addr - $remote_user [$time_local] ' | |
195 '"$request" $status $body_bytes_sent ' | |
196 '"$http_referer" "$http_user_agent"'; | |
197 </example> | |
198 </para> | |
199 | |
200 </directive> | |
201 | |
202 <directive name="open_log_file_cache"> | |
203 | |
204 <syntax> | |
205 <parameter>max</parameter>=<argument>N</argument> | |
206 [<parameter>inactive</parameter>=<argument>time</argument>] | |
207 [<parameter>min_uses</parameter>=<argument>N</argument>] | |
208 [<parameter>valid</parameter>=<argument>time</argument>]</syntax> | |
209 <syntax><value>off</value></syntax> | |
210 <default>off</default> | |
211 <context>http</context> | |
212 <context>server</context> | |
213 <context>location</context> | |
214 | |
215 <para> | |
216 Defines a cache that stores file descriptors of frequently used logs | |
217 whose names contain variables. | |
218 The directive has the following parameters: | |
219 <list type="tag"> | |
220 | |
221 <tag-name><parameter>max</parameter></tag-name> | |
222 <tag-desc> | |
223 sets a maximum number of descriptors in a cache; | |
224 if cache becomes full the least recently used (LRU) | |
225 descriptors are closed | |
226 </tag-desc> | |
227 | |
228 <tag-name><parameter>inactive</parameter></tag-name> | |
229 <tag-desc> | |
230 sets a time after which the cached descriptor is closed | |
231 if there were no access during this time; | |
232 by default, 10 seconds | |
233 </tag-desc> | |
234 | |
235 <tag-name><parameter>min_uses</parameter></tag-name> | |
236 <tag-desc> | |
237 sets a minimum number of file uses during the time | |
238 defined by the <parameter>inactive</parameter> parameter | |
239 after which the descriptor will stay open in a cache; | |
240 by default, 1 | |
241 </tag-desc> | |
242 | |
243 <tag-name><parameter>valid</parameter></tag-name> | |
244 <tag-desc> | |
245 sets a time after which it should be checked that the file | |
246 still exists with the same name; by default, 60 seconds | |
247 </tag-desc> | |
248 | |
249 <tag-name><value>off</value></tag-name> | |
250 <tag-desc> | |
251 disables caching | |
252 </tag-desc> | |
253 | |
254 </list> | |
255 </para> | |
256 | |
257 <para> | |
258 Example usage: | |
259 <example> | |
260 open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2; | |
261 </example> | |
262 </para> | |
263 | |
264 </directive> | |
265 | |
266 </section> | |
267 | |
268 </module> |