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 and exceptional conditions are reported. Messages concerning
pound itself are reported to syslog facility err.
Messages that describe exceptional conditions detected when serving
requests are reported to facility notice. These latter have
the following format:
pound: (tid): client-ip: "request": message or pound: (tid): eNNN: client-ip: "request": message
where:
Thread identifier.
Optional three-digit HTTP status code.
IP address of the client.
HTTP request being served.
Message text.
If the condition being reported concerns the backend, then the IP address of the backend is included as well, e.g.11:
pound: (7fcb33924640): 192.0.20.3 => 10.0.0.1:8081:
"POST /upload HTTP/1.1": error writing to backend
The ‘=>’ marker between IP addresses indicates flow direction:
from pound to backend. If an error occurs while
transferring response from backend to client, it is indicated by
‘<=’, as in:
pound: (7fcb33924640): 192.0.20.3 <= 10.0.0.1:8081:
"POST /upload HTTP/1.1": response read error
Additionally, pound can be instructed to log each processed
request. These access logs are emitted for each processed
request after a response was sent back to the client, and go to
the syslog facility info.
Such additional logging is configured using two directives:
LogLevel and LogFormat. The LogLevel directive
can appear 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:
No request logging at all.
For each request, its source address, request line and response status are logged.
In addition to the above, the selected service and backend are shown.
Detailed request logging using Apache-style Combined log format.
Same as above, but without virtual host information.
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.
The 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:
Replaced with the percent sign.
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),
TrustedIP "cidr0" "cidr1" ... End
defines the list of trusted IPs in place, and
TrustedIP -file "filename" TrustedIP -filewatch "filename"
reads CIDR definitions from file filename (See File-based Conditions, for a discussion of the difference between -file and -filewatch).
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.
Local IP address of the listener.
Size of response in bytes, excluding headers.
Same as ‘%B’, but in CLF format, i.e. a dash is used when response size is zero.
The time taken to serve the request, in microseconds.
Client IP address of the request.
The request protocol.
The contents of ‘hdr:’ header line in the request. Changes made by header modification directives affect this.
Same as ‘%i’, except that if no such header is present in the request, a dash is substituted.
Single dash. This specifier is reserved for future use.
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.
The request method.
Name of pound object that is involved in handling the
request. Valid values for obj are: ‘listener’,
‘service’, and ‘backend’.
Port number of the listener serving the request.
Thread ID of the serving thread.
The query string (prepended with a ‘?’) if it exists, otherwise an empty string.
First line of request.
Response status code.
First line of the response.
Time the request was received, in the format ‘[18/Sep/2011:19:18:28 -0400]’. The last number indicates the timezone offset from UTC.
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:
Number of seconds since the Epoch.
Number of milliseconds since the Epoch.
Number of microseconds since the Epoch.
Millisecond fraction of the time.
Microsecond fraction of the time.
The time taken to process the request, in seconds.
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’.
Remote user if the request was authenticated.
The URL path requested. This is affected by request modification directives.
Hostname used in the request (from the ‘Host’ header, without port number).
The table below describes the built-in formats in terms of format definitions:
""
"%a %r - %>s"
"%a %r - %>s (%{Host}i/%{service}N -> %{backend}N) %{f}T sec"
"%v:%p %a %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\""
"%a %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\""
(Split in two lines for readability)
"%v:%p %a %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\"
(%{service}N -> %{backend}N) %{f}T sec"