8 Logging

Pound can send its diagnostic messages to standard error, syslog, or to both.

Upon startup, while the configuration file is being parsed, the diagnostics goes to the standard error. Once it switches to the operation mode and starts serving requests, diagnostic output is switched to syslog. The syslog facility to use is configured via the LogFacility configuration directive. By default, ‘daemon’ is used.

When running in foreground mode, the -e command line option instructs pound to use standard error for logging, thus overriding the settings from the configuration file.

Normally, pound is not very loquacious in logging: only errors are reported. Logging of each incoming request can be configured using the LogLevel directive. It can be used either in listener scope, in which case it affects only this particular listener, or in global scope, where it affects all listeners that don’t configure it on their own. The value of this directive can be either an integer number in range 0 through 5 (inclusive), or a quoted string. Numeric value requests one of the built-in log formats. String value refers either to a built-in format name, or to a user-defined format name.

The built-in formats are:

0

null

No request logging at all.

1

regular

For each request, its source address, request line and response status are logged.

2

extended

In addition to the above, the selected service and backend are shown.

3

vhost_combined

Detailed request logging using Apache-style Combined log format.

4

combined

Same as above, but without virtual host information.

5

detailed

Same as ‘combined’, with additional information about the selected service and backend.

If the string argument to LogLevel is not one of the above, it must refer to the name of a custom format, defined earlier using the LogFormat statement. This statement takes two string arguments: the name to be assigned to the new format, and its definition.

Format definition is a character string composed of ordinary characters (not ‘%’), which are copied unchanged to the resulting log message, and conversion specifications, each of which are replaced by a corresponding piece of information about the request or reply.

Conversion specifications are single characters prefixed with a percent sign. Depending on the specification, an optional conversion argument in curly brackets may appear between ‘%’ and conversion character.

The following conversion characters are defined:

Format specifier: %%

Replaced with the percent sign.

Format specifier: %a

Originator IP address of the request. If the request contains X-Forwarded-For header and TrustedIP ACL is defined, the value of the header is consulted to obtain the IP address. The value must be a comma-delimited list of intermediate user-agent IP addresses. To determine the actual user-agent IP, the list is traversed from right to left, until an IP is found that is not listed in TrustedIP ACL.

If X-Forwarded-For is not present, or TrustedIP is not defined, or the above algorithm does not return an IP address, %a expands to the actual remote IP address the request came from (same as %h).

The TrustedIP ACL can be defined in global scope, or in ListenHTTP (ListenHTTPS) section, or in Service section. Most-specific ACL overrides least-specific ones, that is a TrustedIP defined in Service will be used, if it is defined. If not, the one defined in listener will be used, etc. The syntax of the TrustedIP statement is the same as that of ACL, i.e.

TrustedIP "name"

refers to the named ACL name (which must be defined earlier, see ACL), and

TrustedIP
  "cidr0"
  "cidr1"
  ...
End

defines the list of trusted IPs in place.

If needed, the ForwardedHeader statement may be used to declare the name of the header to use instead of X-Forwarded-For. As TrustedIP, this statement can appear in global, listener, or in service scope.

Format specifier: %A

Local IP address of the listener.

Format specifier: %B

Size of response in bytes, excluding headers.

Format specifier: %b

Same as ‘%B’, but in CLF format, i.e. a dash is used when response size is zero.

Format specifier: %D

The time taken to serve the request, in microseconds.

Format specifier: %h

Client IP address of the request.

Format specifier: %H

The request protocol.

Format specifier: %{hdr}i

The contents of ‘hdr:’ header line in the request. Changes made by header modification directives affect this.

Format specifier: %{hdr}I

Same as ‘%i’, except that if no such header is present in the request, a dash is substituted.

Format specifier: %{obj}L

Location of the pound object that is involved in handling the request. Valid values for obj are: ‘listener’, ‘service’, and ‘backend’.

The location gives position in the configuration file where the object was defined, and is formatted as

name:ln1.col1-ln2.col2

where name is the configuration file name, ln1 and col1 are line and column where the object definition begins, ln2 and col2 are line and column where it ends. Line and column numbers start with 1.

Format specifier: %m

The request method.

Format specifier: %{obj}N

Name of pound object that is involved in handling the request. Valid values for obj are: ‘listener’, ‘service’, and ‘backend’.

Format specifier: %P

Thread ID of the serving thread.

Format specifier: %q

The query string (prepended with a ‘?’) if it exists, otherwise an empty string.

Format specifier: %r

First line of request.

Format specifier: %s

Response status code.

Format specifier: %>s

First line of the response.

Format specifier: %t

Time the request was received, in the format ‘[18/Sep/2011:19:18:28 -0400]’. The last number indicates the timezone offset from UTC.

Format specifier: %{format}t

Time the request was received, in the format specified by the argument (see Time and Date Formats). If the format starts with ‘begin:’ (default) the time is taken at the beginning of the request processing. If it starts with ‘end:’, it is the time after the response from the backend has been sent back to the requester. In addition to strftime formats, the following specifications are recognized:

sec

Number of seconds since the Epoch.

msec

Number of milliseconds since the Epoch.

usec

Number of microseconds since the Epoch.

msec_frac

Millisecond fraction of the time.

usec_frac

Microsecond fraction of the time.

Format specifier: %T

The time taken to process the request, in seconds.

Format specifier: %{unit}T

The time taken to process the request, in a time unit given by unit. Valid units are ‘ms’ for milliseconds, ‘us’ for microseconds, ‘s’ for seconds, and ‘f’ for seconds with fractional part. Using ‘s’ gives the same result as ‘%T’ without any format; using ‘us’ gives the same result as ‘%D’.

Format specifier: %u

Remote user if the request was authenticated.

Format specifier: %U

The URL path requested. This is affected by request modification directives.

Format specifier: %v

The listener name.

The table below describes the built-in formats in terms of format definitions:

0

null

""

1

regular

"%a %r - %>s"

2

extended

"%a %r - %>s (%{Host}i/%{service}N -> %{backend}N) %{f}T sec"

3

vhost_combined

"%{Host}I %a - %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\""

4

combined

"%a - %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\""

5

detailed

(Split in two lines for readability)

"%{Host}I %a - %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\"
(%{service}N -> %{backend}N) %{f}T sec"