mod_log_config

Overview

mod_log_config module allows to customize logs for different modules, requests etc.

Quick start

Example configuration to enable custom logging 

# Comment out to stop logging!
SetEnv log_enable

# The following directives define some format nicknames for use with a CustomLog directive.
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %I %O" combined
LogFormat "%h %l %u %t \"%r\" %>s %b" common

# The location and format of the access logfile (Common Logfile Format).
CustomLog "c:/inetpub/logs/common-access.log" common env=log_enable

Related articles and topics

Custom log formats

The format argument to the LogFormat and CustomLog directives is a string. This string is used to specify the log record appearance for each request. It can contain literal characters copied into the log files and the C-style control characters "\n" and "\t" to represent new-lines and tabs. Literal quotes and back-slashes should be escaped with back-slashes.

The characteristics of the request itself are logged by placing "%" directives in the format string, which are replaced in the log file by the values as follows:

Format String Description
%% The percent sign
%a Remote IP-address
%A Local IP-address
%b Size of response in bytes, excluding HTTP headers. In CLF format, i.e. a '-' rather than a 0 when no bytes are sent
%B Size of response in bytes, excluding HTTP headers
%{Foobar}C The contents of cookie Foobar in the request sent to the server
%D The time taken to serve the request, in microseconds
%{FOOBAR}e The contents of the environment variable FOOBAR
%f Filename
%h Remote host
%H The request protocol
%{Foobar}i The contents of Foobar: header line(s) in the request sent to the server
%m The request method
%{Foobar}n The contents of note Foobar from another module
%{Foobar}o The contents of Foobar: header line(s) in the reply
%p The canonical port of the server serving the request
%{format}p The canonical port of the server serving the request or the server's actual port or the client's actual port. Valid formats are canonical, local, or remote
%P The process ID of the child that serviced the request
%{format}P The process ID or thread id of the child that serviced the request. Valid formats are pid, tid, and hextid. hextid requires APR 1.2.0 or higher
%q The query string (prepended with a ? if a query string exists, otherwise an empty string)
%r First line of request
%s Status. For requests that got internally redirected, this is the status of the *original* request --- %>s for the last
%t Time the request was received (standard English format)
%{format}t The time, in the form given by format, which should be in strftime(3) format. (potentially localized)
%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, not including any query string
%v The canonical ServerName of the server serving the request
%V The server name according to the UseCanonicalName setting
%I Bytes received, including request and headers, cannot be zero. You need to enable mod_logio to use this
%O Bytes sent, including headers, cannot be zero. You need to enable mod_logio to use this

Modifiers

Logging may be configured dependent on the response status code. This is done by placing a comma-separated list of status codes immediately after the "%".

Example 

# log User-agent value for 400 and 501 errors only
"%400,501{User-agent}i"

For other status codes, the literal string "-" will be logged. The status code list may be preceded by a "!" to indicate negation.

Example 

# log Referer for all requests that do not return one of the three specified codes
"%!200,304,302{Referer}i"

The modifiers "<" and ">" can be used for requests that have been nternally redirected to choose whether the original or final (respectively) request should be consulted. By default, the % directives %s, %U, %T, %D, and %r look at the original request while all others look at the final request. So for example, %>s can be used to record the final status of the request and %<u can be used to record the original authenticated user on a request that is internally redirected to an unauthenticated resource.

Examples of commonly used formats 

#Common Log Format (CLF)
"%h %l %u %t \"%r\" %>s %b"

#Common Log Format with Virtual Host
"%v %h %l %u %t \"%r\" %>s %b"

#NCSA extended/combined log format
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""

#Referer log format
"%{Referer}i -> %U"

#Agent (Browser) log format
"%{User-agent}i"

Directives

Name Context Description
CustomLog S V D .h specifies the file name and format of log file
LogFormat S V D .h sets the format for the log file
TransferLog S V D .h defines the location of the log file

CustomLog

CustomLog directive defines the format of the log file and conditions the request must meet to get logged (optional).

Syntax 

CustomLog file format|nickname [env=[!]environment-variable]

Description

  • file — file name relative to the server root
  • The second argument specifies what will be written to the log file. You may specify either a nickname set in the previous LogFormat directive, or an explicit format string as described in the log formats section.

    Example 

    # CustomLog with format nickname
LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common

# CustomLog with explicit format string
CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b"
  • The third argument is optional and decides whether the request must be logged or not based on the presence or absence of a particular variable in the server environment. If the specified environment variable is set (or not set) for the request, current request will be logged.

    Environment variables can be set on a per-request basis using mod_setenvif and/or mod_rewrite modules. For example, if you want to record requests for all GIF images on your server in a separate logfile but not in your main log, you can use the following code:

    Example 

    SetEnvIf Request_URI \.gif$ gif-image
CustomLog gif-requests.log common env=gif-image
CustomLog nongif-requests.log common env=!gif-image

LogFormat

LogFormat directive sets the format for the specific log file.

Syntax 

LogFormat format|nickname [nickname]

Default 

LogFormat "%h %l %u %t \"%r\" %>s %b"

Description

LogFormat directive may have one of the following two formats. The first implies only one argument - log format that will be used by the logs defined in subsequent TransferLog directives. The argument may set an explicit format (see custom log formats section above) or a nickname to refer to a log format defined in a previous LogFormat directive as described below.

The second format of LogFormat directive associates an explicit format with a nickname. This nickname can then be used in subsequent LogFormat or CustomLog directives instead of repeating the entire format string. LogFormat directive that defines a nickname only defines the nickname, it doesn't set the format and make it default. Therefore, it will not affect subsequent TransferLog directives.

Note LogFormat cannot use one nickname to define another nickname; nickname should not contain percent signs (%).

Example 

LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common

TransferLog

TransferLog directive has exactly the same arguments and effect as the CustomLog directive, with the exception that it does not allow explicit specification of the log format or application of conditions. Instead, the log format is determined by the closest previous LogFormat directive which does not define a nickname. Common Log Format is used if no other format has been specified.

Optional parameters of the directive:

  • archiveAboveSize - Size in kilobytes above which log files will be automatically archived.
  • maxArchiveFiles - Maximum number of archive files that should be kept. Default: 9
  • archiveNumbering - Way file archives are numbered. Possible values:
    • Rolling - Rolling style numbering (the most recent is always #0 then #1, ..., #N.
    • Sequence - Sequence style numbering. The most recent archive has the highest number.
    • Date - Date style numbering. The date is formatted according to the value of archiveDateFormat.
  • archiveEvery - Indicates whether to automatically archive log files every time the specified time passes. Possible values:
    • Day - Archive daily.
    • Hour - Archive every hour.
    • Minute - Archive every minute.
    • Month - Archive every month.
    • None - Don't archive based on time.
    • Year - Archive every year.

Syntax 

TransferLog file

Example 

LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
TransferLog c:\inetpub\logs\access.log archiveEvery Minute archiveNumbering Sequence