Document the Common Log Format

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>&quot;</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>

&lt;VirtualHost hosta.com&gt;<br>

LogFormat "hosta ..."<br>

...<br>

&lt;/VirtualHost&gt;<br>

<br>

&lt;VirtualHost hosta.com&gt;<br>

LogFormat "hostb ..."<br>

...<br>

&lt;/VirtualHost&gt;</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>