and is compiled in by default in Apache 1.2. mod_log_config replaces
mod_log_common in Apache 1.2. Prior to version 1.2, mod_log_config was
an optional module. It provides for logging of the requests made to
-the server, using a user-specified format.
+the server, using the Common Log Format or a user-specified format.
<h2>Summary</h2>
-The argument to the <A HREF="#logformat">LogFormat</A> is a string, which can
-include literal characters copied into the log files, and `%' directives as
-follows:
+
+Three directives are provided by this module: <code>TransferLog</code>
+to create a log file, <code>LogFormat</code> to set a custom format,
+and <code>CustomLog</code> to define a log file and format in one go.
+The <code>TransferLog</code> and <code>CustomLog</code> directives can
+be use multiple times in each server to cause each request to be
+logged to multiple files.
+<P>
+
+<h3>Compatibility notes</h3>
+
+<ul>
+<li>This module is based on mod_log_config distributed with
+previous Apache releases, now updated to handle multiple logs.
+There is now no need to re-configure Apache to get use
+configuration log formats.
+
+<li>The module also implements the <code>CookieLog</code> directive,
+used to log user-tracking information created by <a
+href="mod_usertrack.html">mod_usertrack</a>. The use of
+<code>CookieLog</code> is deprecated, and a <code>CustomLog</code>
+should be defined to log user-tracking information instead.
+
+</ul>
+
+<h2>Log File Formats</h2>
+
+Unless told otherwise with <tt>LogFormat</tt> the log files created by
+<tt>TransferLog</tt> will be in standard "Common Log Format"
+(CLF). The contents of each line in a CLF file are explained
+below. Alternatively, the log file can be customised (and if multiple
+log files are used, each can have a different format). Custom formats
+are set with <code>LogFormat</code> and <code>CustomLog</code>.
+
+<h3>Common Log Format</h3>
+
+The Common Log Format (CLF) file contains a separate line for each
+request. A line is composed of several tokens separated by spaces:
+
+<blockquote>
+host ident authuser date request status bytes
+</blockquote>
+If a token does not have a value then it is represented by a hyphen (-).
+The meanings and values of these tokens are as follows:
+<dl>
+<dt>host
+<dd>The fully-qualified domain name of the client, or its IP number if the
+name is not available.
+<dt>ident
+<dd>If <A HREF="core.html#identitycheck">IdentityCheck</A> is enabled and the
+client machine runs identd, then this is the identity information reported
+by the client.
+<dt>authuser
+<dd>If the request was for an password protected document, then this is
+the userid used in the request.
+<dt>date
+<dd>The date and time of the request, in the following format:
+<dl><dd><blockquote><code> date = [day/month/year:hour:minute:second zone] <br>
+day = 2*digit<br>
+month = 3*letter<br>
+year = 4*digit<br>
+hour = 2*digit<br>
+minute = 2*digit<br>
+second = 2*digit<br>
+zone = (`+' | `-') 4*digit</code></blockquote></dl>
+<dt>request
+<dd>The request line from the client, enclosed in double quotes
+(<code>"</code>).
+<dt>status
+<dd>The three digit status code returned to the client.
+<dt>bytes
+<dd>The number of bytes in the object returned to the client, not including
+any headers.
+</dl>
+
+<h3>Custom Log Formats</h3>
+
+The format argument to the <code>LogFormat</code> and
+<code>CustomLog</code> is a string. This string is logged to the log
+file for each request. It can contain literal characters copied into
+the log files, and `%' directives which are replaced in the log file
+by the values as follows:
<PRE>
+%...b: Bytes sent.
+%...f: Filename
%...h: Remote host
%...l: Remote logname (from identd, if supplied)
-%...u: Remote user (from auth; may be bogus if return
- status (%s) is 401)
-%...t: Time, in common log format time format
+%...p: The port request was received on
+%...P: The process ID of the child that serviced the request
%...r: First line of request
%...s: Status. For requests that got internally redirected,
this is status of the <b>original</b> request --- %...>s
for the last.
-%...b: Bytes sent.
+%...t: Time, in common log format time format
+%...T: The time taken to serve the request, in seconds
+%...u: Remote user (from auth; may be bogus if return
+ status (%s) is 401)
+%...U: The URL path requested
+%...v: The name of the server (i.e. which virtual host)
%...{Foobar}i: The contents of Foobar: header line(s) in the request
sent to the client.
%...{Foobar}o: The contents of Foobar: header line(s) in the reply.
+%...{Foobar}n: The contents of note "Foobar" from another module
</PRE>
The `...' can be nothing at all (e.g. <code>"%h %u %r %s %b"</code>), or it can
<P>
-The default LogFormat reproduces CLF; see below.
-
-<P>
-
-The way this is supposed to work with virtual hosts is as follows:
-a virtual host can have its own LogFormat, or its own TransferLog.
-If it doesn't have its own LogFormat, it inherits from the main
-server. If it doesn't have its own TransferLog, it writes to the
-same descriptor (meaning the same process for `| ...').
-
-<P>
+Note that the common log format is defined by the string <code>"%h %l
+%u %t \"%r\" %s %b"</code>, which can be used as the basis for
+extending for format if desired (e.g. to add extra fields at the end).
-That means that you can do things like:
-
-<blockquote><code>
-<VirtualHost hosta.com><br>
-LogFormat "hosta ..."<br>
-...<br>
-</VirtualHost><br>
-<br>
-<VirtualHost hosta.com><br>
-LogFormat "hostb ..."<br>
-...<br>
-</VirtualHost></code></blockquote>
-
-... to have different virtual servers write into the same log file,
-but have some indication which host they came from, though a %v
-directive may well be a better way to handle this. Look for more
-changes to come to this format.<p>
+<h2>Using Multiple Log Files</h3>
+The <code>TransferLog</code> and <code>CustomLog</code> directives can
+be given more than once to log requests to multiple log files. Each
+request will be logged to all the log files defined by either of these
+directives.
+<h3>Use with Virtual Hosts</h3>
+If a <VirtualHost> section does not contain any
+<tt>TransferLog</tt> or <tt>CustomLog</tt> directives, the
+logs defined for the main server will be used. If it does
+contain one or more of these directives, requests serviced by
+this virtual host will only be logged in the log files defined
+within its definition, not in any of the main server's log files.
+See the examples below.
+<p>
<h2>Directives</h2>
<strong>Status:</strong> Base<br>
<strong>Module:</strong> mod_log_config<p>
-The TransferLog directive sets the name of the file to which the server will
-log the incoming requests. <em>File-pipe</em> is one
+The TransferLog directive adds a log file in Common Log Format.
+<em>File-pipe</em> is one
of
<dl><dt>A filename
<dd>A filename relative to the <A HREF="core.html#serverroot">ServerRoot</A>.
<STRONG>Status:</STRONG> Base<BR>
<STRONG>Module:</STRONG> mod_log_config<P>
-CustomLog combines TransferLog and LogFormat -- the format specified
-to this directive is logged to the file or pipe specified.<P>
+The first argument is the filename to log to. This is used
+exactly like the argument to <tt>TransferLog</tt>, that is,
+it is either a full path, or relative to the current
+server root. <p>
+
+The format argument specifies a format for each line of the log file.
+The options available for the format are exactly the same as for
+the argument of the <tt>LogFormat</tt> directive. If the format
+includes any spaces (which it will do in almost all cases) it
+should be enclosed in double quotes.
<!--#include virtual="footer.html" -->
</BODY>
projects / apache / commitdiff