1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- 4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 5 This file is generated from xml source: DO NOT EDIT 6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 7 --> 8<title>Log Files - Apache HTTP Server</title> 9<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> 10<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> 11<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" /> 12<script src="/style/scripts/prettify.min.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body id="manual-page"><div id="page-header"> 17<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p> 18<p class="apache">Apache HTTP Server Version 2.4</p> 19<img alt="" src="/images/feather.gif" /></div> 20<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 21<div id="path"> 22<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="./">Version 2.4</a></div><div id="page-content"><div id="preamble"><h1>Log Files</h1> 23<div class="toplang"> 24<p><span>Available Languages: </span><a href="/en/logs.html" title="English"> en </a> | 25<a href="/fr/logs.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 26<a href="/ja/logs.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> | 27<a href="/ko/logs.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> | 28<a href="/tr/logs.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p> 29</div> 30 31 <p>In order to effectively manage a web server, it is necessary 32 to get feedback about the activity and performance of the 33 server as well as any problems that may be occurring. The Apache HTTP Server 34 provides very comprehensive and flexible logging 35 capabilities. This document describes how to configure its 36 logging capabilities, and how to understand what the logs 37 contain.</p> 38 </div> 39<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#overview">Overview</a></li> 40<li><img alt="" src="/images/down.gif" /> <a href="#security">Security Warning</a></li> 41<li><img alt="" src="/images/down.gif" /> <a href="#errorlog">Error Log</a></li> 42<li><img alt="" src="/images/down.gif" /> <a href="#permodule">Per-module logging</a></li> 43<li><img alt="" src="/images/down.gif" /> <a href="#accesslog">Access Log</a></li> 44<li><img alt="" src="/images/down.gif" /> <a href="#rotation">Log Rotation</a></li> 45<li><img alt="" src="/images/down.gif" /> <a href="#piped">Piped Logs</a></li> 46<li><img alt="" src="/images/down.gif" /> <a href="#virtualhost">Virtual Hosts</a></li> 47<li><img alt="" src="/images/down.gif" /> <a href="#other">Other Log Files</a></li> 48</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 49<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 50<div class="section"> 51<h2><a name="overview" id="overview">Overview</a></h2> 52 53 54 <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="/mod/mod_log_config.html">mod_log_config</a></code></li><li><code class="module"><a href="/mod/mod_log_forensic.html">mod_log_forensic</a></code></li><li><code class="module"><a href="/mod/mod_logio.html">mod_logio</a></code></li><li><code class="module"><a href="/mod/mod_cgi.html">mod_cgi</a></code></li></ul></td><td /></tr></table> 55 56 <p> 57 The Apache HTTP Server provides a variety of different mechanisms for 58 logging everything that happens on your server, from the initial 59 request, through the URL mapping process, to the final resolution of 60 the connection, including any errors that may have occurred in the 61 process. In addition to this, third-party modules may provide logging 62 capabilities, or inject entries into the existing log files, and 63 applications such as CGI programs, or PHP scripts, or other handlers, 64 may send messages to the server error log. 65 </p> 66 67 <p> 68 In this document we discuss the logging modules that are a standard 69 part of the http server. 70 </p> 71 72 </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 73<div class="section"> 74<h2><a name="security" id="security">Security Warning</a></h2> 75 76 77 <p>Anyone who can write to the directory where Apache httpd is 78 writing a log file can almost certainly gain access to the uid 79 that the server is started as, which is normally root. Do 80 <em>NOT</em> give people write access to the directory the logs 81 are stored in without being aware of the consequences; see the 82 <a href="misc/security_tips.html">security tips</a> document 83 for details.</p> 84 85 <p>In addition, log files may contain information supplied 86 directly by the client, without escaping. Therefore, it is 87 possible for malicious clients to insert control-characters in 88 the log files, so care must be taken in dealing with raw 89 logs.</p> 90 </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 91<div class="section"> 92<h2><a name="errorlog" id="errorlog">Error Log</a></h2> 93 94 95 <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="/mod/core.html">core</a></code></li></ul></td><td><ul><li><code class="directive"><a href="/mod/core.html#errorlog">ErrorLog</a></code></li><li><code class="directive"><a href="/mod/core.html#errorlogformat">ErrorLogFormat</a></code></li><li><code class="directive"><a href="/mod/core.html#loglevel">LogLevel</a></code></li></ul></td></tr></table> 96 97 <p>The server error log, whose name and location is set by the 98 <code class="directive"><a href="/mod/core.html#errorlog">ErrorLog</a></code> directive, is the 99 most important log file. This is the place where Apache httpd 100 will send diagnostic information and record any errors that it 101 encounters in processing requests. It is the first place to 102 look when a problem occurs with starting the server or with the 103 operation of the server, since it will often contain details of 104 what went wrong and how to fix it.</p> 105 106 <p>The error log is usually written to a file (typically 107 <code>error_log</code> on Unix systems and 108 <code>error.log</code> on Windows and OS/2). On Unix systems it 109 is also possible to have the server send errors to 110 <code>syslog</code> or <a href="#piped">pipe them to a 111 program</a>.</p> 112 113 <p>The format of the error log is defined by the <code class="directive"><a href="/mod/core.html#errorlogformat">ErrorLogFormat</a></code> directive, with which you 114 can customize what values are logged. A default is format defined 115 if you don't specify one. A typical log message follows:</p> 116 117 <div class="example"><p><code> 118 [Fri Sep 09 10:42:29.902022 2011] [core:error] [pid 35708:tid 4328636416] 119 [client 72.15.99.187] File does not exist: /usr/local/apache2/htdocs/favicon.ico 120 </code></p></div> 121 122 <p>The first item in the log entry is the date and time of the 123 message. The next is the module producing the message (core, in this 124 case) and the severity level of that message. This is followed by 125 the process ID and, if appropriate, the thread ID, of the process 126 that experienced the condition. Next, we have the client address 127 that made the request. And finally is the detailed error message, 128 which in this case indicates a request for a file that did not 129 exist.</p> 130 131 <p>A very wide variety of different messages can appear in the 132 error log. Most look similar to the example above. The error 133 log will also contain debugging output from CGI scripts. Any 134 information written to <code>stderr</code> by a CGI script will 135 be copied directly to the error log.</p> 136 137 <p>Putting a <code>%L</code> token in both the error log and the access 138 log will produce a log entry ID with which you can correlate the entry 139 in the error log with the entry in the access log. If 140 <code class="module"><a href="/mod/mod_unique_id.html">mod_unique_id</a></code> is loaded, its unique request ID will be 141 used as the log entry ID, too.</p> 142 143 <p>During testing, it is often useful to continuously monitor 144 the error log for any problems. On Unix systems, you can 145 accomplish this using:</p> 146 147 <div class="example"><p><code> 148 tail -f error_log 149 </code></p></div> 150 </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 151<div class="section"> 152<h2><a name="permodule" id="permodule">Per-module logging</a></h2> 153 154 155 <p>The <code class="directive"><a href="/mod/core.html#loglevel">LogLevel</a></code> directive 156 allows you to specify a log severity level on a per-module basis. In 157 this way, if you are troubleshooting a problem with just one 158 particular module, you can turn up its logging volume without also 159 getting the details of other modules that you're not interested in. 160 This is particularly useful for modules such as 161 <code class="module"><a href="/mod/mod_proxy.html">mod_proxy</a></code> or <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code> where you 162 want to know details about what it's trying to do.</p> 163 164 <p>Do this by specifying the name of the module in your 165 <code class="directive">LogLevel</code> directive:</p> 166 167 <pre class="prettyprint lang-config">LogLevel info rewrite:trace5</pre> 168 169 170 <p>This sets the main <code class="directive">LogLevel</code> to info, but 171 turns it up to <code>trace5</code> for 172 <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>.</p> 173 174 <div class="note">This replaces the per-module logging directives, such as 175 <code>RewriteLog</code>, that were present in earlier versions of 176 the server.</div> 177 </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 178<div class="section"> 179<h2><a name="accesslog" id="accesslog">Access Log</a></h2> 180 181 182 <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="/mod/mod_log_config.html">mod_log_config</a></code></li><li><code class="module"><a href="/mod/mod_setenvif.html">mod_setenvif</a></code></li></ul></td><td><ul><li><code class="directive"><a href="/mod/mod_log_config.html#customlog">CustomLog</a></code></li><li><code class="directive"><a href="/mod/mod_log_config.html#logformat">LogFormat</a></code></li><li><code class="directive"><a href="/mod/mod_setenvif.html#setenvif">SetEnvIf</a></code></li></ul></td></tr></table> 183 184 <p>The server access log records all requests processed by the 185 server. The location and content of the access log are 186 controlled by the <code class="directive"><a href="/mod/mod_log_config.html#customlog">CustomLog</a></code> 187 directive. The <code class="directive"><a href="/mod/mod_log_config.html#logformat">LogFormat</a></code> 188 directive can be used to simplify the selection of 189 the contents of the logs. This section describes how to configure the server 190 to record information in the access log.</p> 191 192 <p>Of course, storing the information in the access log is only 193 the start of log management. The next step is to analyze this 194 information to produce useful statistics. Log analysis in 195 general is beyond the scope of this document, and not really 196 part of the job of the web server itself. For more information 197 about this topic, and for applications which perform log 198 analysis, check the <a href="http://dmoz.org/Computers/Software/Internet/Site_Management/Log_analysis/"> 199 Open Directory</a> or <a href="http://dir.yahoo.com/Computers_and_Internet/Software/Internet/World_Wide_Web/Servers/Log_Analysis_Tools/"> 200 Yahoo</a>.</p> 201 202 <p>Various versions of Apache httpd have used other modules and 203 directives to control access logging, including 204 mod_log_referer, mod_log_agent, and the 205 <code>TransferLog</code> directive. The <code class="directive"><a href="/mod/mod_log_config.html#customlog">CustomLog</a></code> directive now subsumes 206 the functionality of all the older directives.</p> 207 208 <p>The format of the access log is highly configurable. The format 209 is specified using a format string that looks much like a C-style 210 printf(1) format string. Some examples are presented in the next 211 sections. For a complete list of the possible contents of the 212 format string, see the <code class="module"><a href="/mod/mod_log_config.html">mod_log_config</a></code> <a href="mod/mod_log_config.html#formats">format strings</a>.</p> 213 214 <h3><a name="common" id="common">Common Log Format</a></h3> 215 216 217 <p>A typical configuration for the access log might look as 218 follows.</p> 219 220 <pre class="prettyprint lang-config">LogFormat "%h %l %u %t \"%r\" %>s %b" common 221CustomLog logs/access_log common</pre> 222 223 224 <p>This defines the <em>nickname</em> <code>common</code> and 225 associates it with a particular log format string. The format 226 string consists of percent directives, each of which tell the 227 server to log a particular piece of information. Literal 228 characters may also be placed in the format string and will be 229 copied directly into the log output. The quote character 230 (<code>"</code>) must be escaped by placing a backslash before 231 it to prevent it from being interpreted as the end of the 232 format string. The format string may also contain the special 233 control characters "<code>\n</code>" for new-line and 234 "<code>\t</code>" for tab.</p> 235 236 <p>The <code class="directive"><a href="/mod/mod_log_config.html#customlog">CustomLog</a></code> 237 directive sets up a new log file using the defined 238 <em>nickname</em>. The filename for the access log is relative to 239 the <code class="directive"><a href="/mod/core.html#serverroot">ServerRoot</a></code> unless it 240 begins with a slash.</p> 241 242 <p>The above configuration will write log entries in a format 243 known as the Common Log Format (CLF). This standard format can 244 be produced by many different web servers and read by many log 245 analysis programs. The log file entries produced in CLF will 246 look something like this:</p> 247 248 <div class="example"><p><code> 249 127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET 250 /apache_pb.gif HTTP/1.0" 200 2326 251 </code></p></div> 252 253 <p>Each part of this log entry is described below.</p> 254 255 <dl> 256 <dt><code>127.0.0.1</code> (<code>%h</code>)</dt> 257 258 <dd>This is the IP address of the client (remote host) which 259 made the request to the server. If <code class="directive"><a href="/mod/core.html#hostnamelookups">HostnameLookups</a></code> is 260 set to <code>On</code>, then the server will try to determine 261 the hostname and log it in place of the IP address. However, 262 this configuration is not recommended since it can 263 significantly slow the server. Instead, it is best to use a 264 log post-processor such as <code class="program"><a href="/programs/logresolve.html">logresolve</a></code> to determine 265 the hostnames. The IP address reported here is not 266 necessarily the address of the machine at which the user is 267 sitting. If a proxy server exists between the user and the 268 server, this address will be the address of the proxy, rather 269 than the originating machine.</dd> 270 271 <dt><code>-</code> (<code>%l</code>)</dt> 272 273 <dd>The "hyphen" in the output indicates that the requested 274 piece of information is not available. In this case, the 275 information that is not available is the RFC 1413 identity of 276 the client determined by <code>identd</code> on the clients 277 machine. This information is highly unreliable and should 278 almost never be used except on tightly controlled internal 279 networks. Apache httpd will not even attempt to determine 280 this information unless <code class="directive"><a href="/mod/mod_ident.html#identitycheck">IdentityCheck</a></code> is set 281 to <code>On</code>.</dd> 282 283 <dt><code>frank</code> (<code>%u</code>)</dt> 284 285 <dd>This is the userid of the person requesting the document 286 as determined by HTTP authentication. The same value is 287 typically provided to CGI scripts in the 288 <code>REMOTE_USER</code> environment variable. If the status 289 code for the request (see below) is 401, then this value 290 should not be trusted because the user is not yet 291 authenticated. If the document is not password protected, 292 this part will be "<code>-</code>" just like the previous 293 one.</dd> 294 295 <dt><code>[10/Oct/2000:13:55:36 -0700]</code> 296 (<code>%t</code>)</dt> 297 298 <dd> 299 The time that the request was received. 300 The format is: 301 302 <p class="indent"> 303 <code>[day/month/year:hour:minute:second zone]<br /> 304 day = 2*digit<br /> 305 month = 3*letter<br /> 306 year = 4*digit<br /> 307 hour = 2*digit<br /> 308 minute = 2*digit<br /> 309 second = 2*digit<br /> 310 zone = (`+' | `-') 4*digit</code> 311 </p> 312 <p>It is possible to have the time displayed in another format 313 by specifying <code>%{format}t</code> in the log format 314 string, where <code>format</code> is either as in 315 <code>strftime(3)</code> from the C standard library, 316 or one of the supported special tokens. For details see 317 the <code class="module"><a href="/mod/mod_log_config.html">mod_log_config</a></code> <a href="mod/mod_log_config.html#formats">format strings</a>.</p> 318 </dd> 319 320 <dt><code>"GET /apache_pb.gif HTTP/1.0"</code> 321 (<code>\"%r\"</code>)</dt> 322 323 <dd>The request line from the client is given in double 324 quotes. The request line contains a great deal of useful 325 information. First, the method used by the client is 326 <code>GET</code>. Second, the client requested the resource 327 <code>/apache_pb.gif</code>, and third, the client used the 328 protocol <code>HTTP/1.0</code>. It is also possible to log 329 one or more parts of the request line independently. For 330 example, the format string "<code>%m %U%q %H</code>" will log 331 the method, path, query-string, and protocol, resulting in 332 exactly the same output as "<code>%r</code>".</dd> 333 334 <dt><code>200</code> (<code>%>s</code>)</dt> 335 336 <dd>This is the status code that the server sends back to the 337 client. This information is very valuable, because it reveals 338 whether the request resulted in a successful response (codes 339 beginning in 2), a redirection (codes beginning in 3), an 340 error caused by the client (codes beginning in 4), or an 341 error in the server (codes beginning in 5). The full list of 342 possible status codes can be found in the <a href="http://www.w3.org/Protocols/rfc2616/rfc2616.txt">HTTP 343 specification</a> (RFC2616 section 10).</dd> 344 345 <dt><code>2326</code> (<code>%b</code>)</dt> 346 347 <dd>The last part indicates the size of the object returned 348 to the client, not including the response headers. If no 349 content was returned to the client, this value will be 350 "<code>-</code>". To log "<code>0</code>" for no content, use 351 <code>%B</code> instead.</dd> 352 </dl> 353 354 355 <h3><a name="combined" id="combined">Combined Log Format</a></h3> 356 357 358 <p>Another commonly used format string is called the Combined 359 Log Format. It can be used as follows.</p> 360 361 <pre class="prettyprint lang-config">LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" combined 362CustomLog log/access_log combined</pre> 363 364 365 <p>This format is exactly the same as the Common Log Format, 366 with the addition of two more fields. Each of the additional 367 fields uses the percent-directive 368 <code>%{<em>header</em>}i</code>, where <em>header</em> can be 369 any HTTP request header. The access log under this format will 370 look like:</p> 371 372 <div class="example"><p><code> 373 127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET 374 /apache_pb.gif HTTP/1.0" 200 2326 375 "http://www.example.com/start.html" "Mozilla/4.08 [en] 376 (Win98; I ;Nav)" 377 </code></p></div> 378 379 <p>The additional fields are:</p> 380 381 <dl> 382 <dt><code>"http://www.example.com/start.html"</code> 383 (<code>\"%{Referer}i\"</code>)</dt> 384 385 <dd>The "Referer" (sic) HTTP request header. This gives the 386 site that the client reports having been referred from. (This 387 should be the page that links to or includes 388 <code>/apache_pb.gif</code>).</dd> 389 390 <dt><code>"Mozilla/4.08 [en] (Win98; I ;Nav)"</code> 391 (<code>\"%{User-agent}i\"</code>)</dt> 392 393 <dd>The User-Agent HTTP request header. This is the 394 identifying information that the client browser reports about 395 itself.</dd> 396 </dl> 397 398 399 <h3><a name="multiple" id="multiple">Multiple Access Logs</a></h3> 400 401 402 <p>Multiple access logs can be created simply by specifying 403 multiple <code class="directive"><a href="/mod/mod_log_config.html#customlog">CustomLog</a></code> 404 directives in the configuration 405 file. For example, the following directives will create three 406 access logs. The first contains the basic CLF information, 407 while the second and third contain referer and browser 408 information. The last two <code class="directive"><a href="/mod/mod_log_config.html#customlog">CustomLog</a></code> lines show how 409 to mimic the effects of the <code>ReferLog</code> and <code>AgentLog</code> directives.</p> 410 411 <pre class="prettyprint lang-config">LogFormat "%h %l %u %t \"%r\" %>s %b" common 412CustomLog logs/access_log common 413CustomLog logs/referer_log "%{Referer}i -> %U" 414CustomLog logs/agent_log "%{User-agent}i"</pre> 415 416 417 <p>This example also shows that it is not necessary to define a 418 nickname with the <code class="directive"><a href="/mod/mod_log_config.html#logformat">LogFormat</a></code> directive. Instead, 419 the log format can be specified directly in the <code class="directive"><a href="/mod/mod_log_config.html#customlog">CustomLog</a></code> directive.</p> 420 421 422 <h3><a name="conditional" id="conditional">Conditional Logs</a></h3> 423 424 425 <p>There are times when it is convenient to exclude certain 426 entries from the access logs based on characteristics of the 427 client request. This is easily accomplished with the help of <a href="env.html">environment variables</a>. First, an 428 environment variable must be set to indicate that the request 429 meets certain conditions. This is usually accomplished with 430 <code class="directive"><a href="/mod/mod_setenvif.html#setenvif">SetEnvIf</a></code>. Then the 431 <code>env=</code> clause of the <code class="directive"><a href="/mod/mod_log_config.html#customlog">CustomLog</a></code> directive is used to 432 include or exclude requests where the environment variable is 433 set. Some examples:</p> 434 435 <pre class="prettyprint lang-config"># Mark requests from the loop-back interface 436SetEnvIf Remote_Addr "127\.0\.0\.1" dontlog 437# Mark requests for the robots.txt file 438SetEnvIf Request_URI "^/robots\.txt$" dontlog 439# Log what remains 440CustomLog logs/access_log common env=!dontlog</pre> 441 442 443 <p>As another example, consider logging requests from 444 english-speakers to one log file, and non-english speakers to a 445 different log file.</p> 446 447 <pre class="prettyprint lang-config"> SetEnvIf Accept-Language "en" english<br /> 448 CustomLog logs/english_log common env=english<br /> 449 CustomLog logs/non_english_log common env=!english</pre> 450 451 452 <p>In a caching scenario one would want to know about 453 the efficiency of the cache. A very simple method to 454 find this out would be:</p> 455 456 <pre class="prettyprint lang-config">SetEnv CACHE_MISS 1 457LogFormat "%h %l %u %t "%r " %>s %b %{CACHE_MISS}e" common-cache 458CustomLog logs/access_log common-cache</pre> 459 460 461 <p><code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> will run before 462 <code class="module"><a href="/mod/mod_env.html">mod_env</a></code> and, when successful, will deliver the 463 content without it. In that case a cache hit will log 464 <code>-</code>, while a cache miss will log <code>1</code>.</p> 465 466 <p>In addition to the <code>env=</code> syntax, <code class="directive"><a href="/mod/mod_log_config.html#logformat">LogFormat</a></code> supports logging values 467 conditional upon the HTTP response code:</p> 468 469 <pre class="prettyprint lang-config">LogFormat "%400,501{User-agent}i" browserlog 470LogFormat "%!200,304,302{Referer}i" refererlog</pre> 471 472 473 <p>In the first example, the <code>User-agent</code> will be 474 logged if the HTTP status code is 400 or 501. In other cases, a 475 literal "-" will be logged instead. Likewise, in the second 476 example, the <code>Referer</code> will be logged if the HTTP 477 status code is <strong>not</strong> 200, 204, or 302. (Note the 478 "!" before the status codes.</p> 479 480 <p>Although we have just shown that conditional logging is very 481 powerful and flexible, it is not the only way to control the 482 contents of the logs. Log files are more useful when they 483 contain a complete record of server activity. It is often 484 easier to simply post-process the log files to remove requests 485 that you do not want to consider.</p> 486 487 </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 488<div class="section"> 489<h2><a name="rotation" id="rotation">Log Rotation</a></h2> 490 491 492 <p>On even a moderately busy server, the quantity of 493 information stored in the log files is very large. The access 494 log file typically grows 1 MB or more per 10,000 requests. It 495 will consequently be necessary to periodically rotate the log 496 files by moving or deleting the existing logs. This cannot be 497 done while the server is running, because Apache httpd will continue 498 writing to the old log file as long as it holds the file open. 499 Instead, the server must be <a href="stopping.html">restarted</a> after the log files are 500 moved or deleted so that it will open new log files.</p> 501 502 <p>By using a <em>graceful</em> restart, the server can be 503 instructed to open new log files without losing any existing or 504 pending connections from clients. However, in order to 505 accomplish this, the server must continue to write to the old 506 log files while it finishes serving old requests. It is 507 therefore necessary to wait for some time after the restart 508 before doing any processing on the log files. A typical 509 scenario that simply rotates the logs and compresses the old 510 logs to save space is:</p> 511 512 <div class="example"><p><code> 513 mv access_log access_log.old<br /> 514 mv error_log error_log.old<br /> 515 apachectl graceful<br /> 516 sleep 600<br /> 517 gzip access_log.old error_log.old 518 </code></p></div> 519 520 <p>Another way to perform log rotation is using <a href="#piped">piped logs</a> as discussed in the next 521 section.</p> 522 </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 523<div class="section"> 524<h2><a name="piped" id="piped">Piped Logs</a></h2> 525 526 527 <p>Apache httpd is capable of writing error and access log 528 files through a pipe to another process, rather than directly 529 to a file. This capability dramatically increases the 530 flexibility of logging, without adding code to the main server. 531 In order to write logs to a pipe, simply replace the filename 532 with the pipe character "<code>|</code>", followed by the name 533 of the executable which should accept log entries on its 534 standard input. The server will start the piped-log process when 535 the server starts, and will restart it if it crashes while the 536 server is running. (This last feature is why we can refer to 537 this technique as "reliable piped logging".)</p> 538 539 <p>Piped log processes are spawned by the parent Apache httpd 540 process, and inherit the userid of that process. This means 541 that piped log programs usually run as root. It is therefore 542 very important to keep the programs simple and secure.</p> 543 544 <p>One important use of piped logs is to allow log rotation 545 without having to restart the server. The Apache HTTP Server 546 includes a simple program called <code class="program"><a href="/programs/rotatelogs.html">rotatelogs</a></code> 547 for this purpose. For example, to rotate the logs every 24 hours, you 548 can use:</p> 549 550 <pre class="prettyprint lang-config">CustomLog "|/usr/local/apache/bin/rotatelogs /var/log/access_log 86400" common</pre> 551 552 553 <p>Notice that quotes are used to enclose the entire command 554 that will be called for the pipe. Although these examples are 555 for the access log, the same technique can be used for the 556 error log.</p> 557 558 <p>A similar but much more flexible log rotation program 559 called <a href="http://www.cronolog.org/">cronolog</a> 560 is available at an external site.</p> 561 562 <p>As with conditional logging, piped logs are a very powerful 563 tool, but they should not be used where a simpler solution like 564 off-line post-processing is available.</p> 565 566 <p>By default the piped log process is spawned without invoking 567 a shell. Use "<code>|$</code>" instead of "<code>|</code>" 568 to spawn using a shell (usually with <code>/bin/sh -c</code>):</p> 569 570 <pre class="prettyprint lang-config"># Invoke "rotatelogs" using a shell 571CustomLog "|$/usr/local/apache/bin/rotatelogs /var/log/access_log 86400" common</pre> 572 573 574 <p>This was the default behaviour for Apache 2.2. 575 Depending on the shell specifics this might lead to 576 an additional shell process for the lifetime of the logging 577 pipe program and signal handling problems during restart. 578 For compatibility reasons with Apache 2.2 the notation 579 "<code>||</code>" is also supported and equivalent to using 580 "<code>|</code>".</p> 581 </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 582<div class="section"> 583<h2><a name="virtualhost" id="virtualhost">Virtual Hosts</a></h2> 584 585 586 <p>When running a server with many <a href="vhosts/">virtual 587 hosts</a>, there are several options for dealing with log 588 files. First, it is possible to use logs exactly as in a 589 single-host server. Simply by placing the logging directives 590 outside the <code class="directive"><a href="/mod/core.html#virtualhost"><VirtualHost></a></code> sections in the 591 main server context, it is possible to log all requests in the 592 same access log and error log. This technique does not allow 593 for easy collection of statistics on individual virtual 594 hosts.</p> 595 596 <p>If <code class="directive"><a href="/mod/mod_log_config.html#customlog">CustomLog</a></code> 597 or <code class="directive"><a href="/mod/core.html#errorlog">ErrorLog</a></code> 598 directives are placed inside a 599 <code class="directive"><a href="/mod/core.html#virtualhost"><VirtualHost></a></code> 600 section, all requests or errors for that virtual host will be 601 logged only to the specified file. Any virtual host which does 602 not have logging directives will still have its requests sent 603 to the main server logs. This technique is very useful for a 604 small number of virtual hosts, but if the number of hosts is 605 very large, it can be complicated to manage. In addition, it 606 can often create problems with <a href="vhosts/fd-limits.html">insufficient file 607 descriptors</a>.</p> 608 609 <p>For the access log, there is a very good compromise. By 610 adding information on the virtual host to the log format 611 string, it is possible to log all hosts to the same log, and 612 later split the log into individual files. For example, 613 consider the following directives.</p> 614 615 <pre class="prettyprint lang-config">LogFormat "%v %l %u %t \"%r\" %>s %b" comonvhost 616CustomLog logs/access_log comonvhost</pre> 617 618 619 <p>The <code>%v</code> is used to log the name of the virtual 620 host that is serving the request. Then a program like <a href="programs/other.html">split-logfile</a> can be used to 621 post-process the access log in order to split it into one file 622 per virtual host.</p> 623 </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 624<div class="section"> 625<h2><a name="other" id="other">Other Log Files</a></h2> 626 627 628 <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="/mod/mod_logio.html">mod_logio</a></code></li><li><code class="module"><a href="/mod/mod_log_config.html">mod_log_config</a></code></li><li><code class="module"><a href="/mod/mod_log_forensic.html">mod_log_forensic</a></code></li><li><code class="module"><a href="/mod/mod_cgi.html">mod_cgi</a></code></li></ul></td><td><ul><li><code class="directive"><a href="/mod/mod_log_config.html#logformat">LogFormat</a></code></li><li><code class="directive"><a href="/mod/mod_log_config.html#bufferedlogs">BufferedLogs</a></code></li><li><code class="directive"><a href="/mod/mod_log_forensic.html#forensiclog">ForensicLog</a></code></li><li><code class="directive"><a href="/mod/mpm_common.html#pidfile">PidFile</a></code></li><li><code class="directive"><a href="/mod/mod_cgi.html#scriptlog">ScriptLog</a></code></li><li><code class="directive"><a href="/mod/mod_cgi.html#scriptlogbuffer">ScriptLogBuffer</a></code></li><li><code class="directive"><a href="/mod/mod_cgi.html#scriptloglength">ScriptLogLength</a></code></li></ul></td></tr></table> 629 630 <h3>Logging actual bytes sent and received</h3> 631 632 633 <p><code class="module"><a href="/mod/mod_logio.html">mod_logio</a></code> adds in two additional 634 <code class="directive"><a href="/mod/mod_log_config.html#logformat">LogFormat</a></code> fields 635 (%I and %O) that log the actual number of bytes received and sent 636 on the network.</p> 637 638 639 <h3>Forensic Logging</h3> 640 641 642 <p><code class="module"><a href="/mod/mod_log_forensic.html">mod_log_forensic</a></code> provides for forensic logging of 643 client requests. Logging is done before and after processing a 644 request, so the forensic log contains two log lines for each 645 request. The forensic logger is very strict with no customizations. 646 It can be an invaluable debugging and security tool.</p> 647 648 649 <h3><a name="pidfile" id="pidfile">PID File</a></h3> 650 651 652 <p>On startup, Apache httpd saves the process id of the parent 653 httpd process to the file <code>logs/httpd.pid</code>. This 654 filename can be changed with the <code class="directive"><a href="/mod/mpm_common.html#pidfile">PidFile</a></code> directive. The 655 process-id is for use by the administrator in restarting and 656 terminating the daemon by sending signals to the parent 657 process; on Windows, use the -k command line option instead. 658 For more information see the <a href="stopping.html">Stopping 659 and Restarting</a> page.</p> 660 661 662 <h3><a name="scriptlog" id="scriptlog">Script Log</a></h3> 663 664 665 <p>In order to aid in debugging, the 666 <code class="directive"><a href="/mod/mod_cgi.html#scriptlog">ScriptLog</a></code> directive 667 allows you to record the input to and output from CGI scripts. 668 This should only be used in testing - not for live servers. 669 More information is available in the <a href="mod/mod_cgi.html">mod_cgi</a> documentation.</p> 670 671 672 </div></div> 673<div class="bottomlang"> 674<p><span>Available Languages: </span><a href="/en/logs.html" title="English"> en </a> | 675<a href="/fr/logs.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 676<a href="/ja/logs.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> | 677<a href="/ko/logs.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> | 678<a href="/tr/logs.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p> 679</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> 680<script type="text/javascript"><!--//--><![CDATA[//><!-- 681var comments_shortname = 'httpd'; 682var comments_identifier = 'http://httpd.apache.org/docs/2.4/logs.html'; 683(function(w, d) { 684 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 685 d.write('<div id="comments_thread"><\/div>'); 686 var s = d.createElement('script'); 687 s.type = 'text/javascript'; 688 s.async = true; 689 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 690 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 691 } 692 else { 693 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 694 } 695})(window, document); 696//--><!]]></script></div><div id="footer"> 697<p class="apache">Copyright 2014 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> 698<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- 699if (typeof(prettyPrint) !== 'undefined') { 700 prettyPrint(); 701} 702//--><!]]></script> 703</body></html>
