The Valve Component
Table of Contents
Introduction
A Valve element represents a component that will be inserted into the request processing pipeline for the associated Catalina container (Engine, Host, or Context). Individual Valves have distinct processing capabilities, and are described individually below.
The description below uses the variable name $CATALINA_BASE to refer the base directory against which most relative paths are resolved. If you have not configured Tomcat for multiple instances by setting a CATALINA_BASE directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, the directory into which you have installed Tomcat.
Access Logging
Access logging is performed by valves that implement org.apache.catalina.AccessLog interface.
Access Log Valve
Introduction
The Access Log Valve creates log files in the
same format as those created by standard web servers. These logs
can later be analyzed by standard log analysis tools to track page
hit counts, user session activity, and so on. This Valve
uses self-contained logic to write its log files, which can be
automatically rolled over at midnight each day. (The essential
requirement for access logging is to handle a large continuous
stream of data with low overhead. This Valve does not
use Apache Commons Logging, thus avoiding additional overhead and
potentially complex configuration).
This Valve may be associated with any Catalina container
(Context, Host, or Engine), and
will record ALL requests processed by that container.
Some requests may be handled by Tomcat before they are passed to a
container. These include redirects from /foo to /foo/ and the rejection of
invalid requests. Where Tomcat can identify the Context that
would have handled the request, the request/response will be logged in the
AccessLog(s) associated Context, Host
and Engine. Where Tomcat cannot identify the
Context that would have handled the request, e.g. in cases
where the URL is invalid, Tomcat will look first in the Engine,
then the default Host for the Engine and finally
the ROOT (or default) Context for the default Host
for an AccessLog implementation. Tomcat will use the first
AccessLog implementation found to log those requests that are
rejected before they are passed to a container.
The output file will be placed in the directory given by the
directory attribute. The name of the file is composed
by concatenation of the configured prefix, timestamp and
suffix. The format of the timestamp in the file name can be
set using the fileDateFormat attribute. This timestamp will
be omitted if the file rotation is switched off by setting
rotatable to false.
Warning: If multiple AccessLogValve instances are used, they should be configured to use different output files.
If sendfile is used, the response bytes will be written asynchronously in a separate thread and the access log valve will not know how many bytes were actually written. In this case, the number of bytes that was passed to the sendfile thread for writing will be recorded in the access log valve.
Attributes
The Access Log Valve supports the following configuration attributes:
| Attribute | Description |
|---|---|
buffered |
Flag to determine if logging will be buffered.
If set to |
className |
Java class name of the implementation to use. This MUST be set to org.apache.catalina.valves.AccessLogValve to use the default access log valve. |
condition |
The same as |
conditionIf |
Turns on conditional logging. If set, requests will be
logged only if |
conditionUnless |
Turns on conditional logging. If set, requests will be
logged only if |
directory |
Absolute or relative pathname of a directory in which log files created by this valve will be placed. If a relative path is specified, it is interpreted as relative to $CATALINA_BASE. If no directory attribute is specified, the default value is "logs" (relative to $CATALINA_BASE). |
encoding |
Character set used to write the log file. An empty string means to use the system default character set. Default value: use the system default character set. |
fileDateFormat |
Allows a customized timestamp in the access log file name.
The file is rotated whenever the formatted timestamp changes.
The default value is |
ipv6Canonical |
Flag to determine if IPv6 addresses should be represented in canonical
representation format as defined by RFC 5952. If set to |
locale |
The locale used to format timestamps in the access log
lines. Any timestamps configured using an
explicit SimpleDateFormat pattern ( |
maxDays |
The maximum number of days rotated access logs will be retained for
before being deleted. If not specified, the default value of
|
maxLogMessageBufferSize |
Log message buffers are usually recycled and re-used. To prevent
excessive memory usage, if a buffer grows beyond this size it will be
discarded. The default is |
pattern |
A formatting layout identifying the various information fields
from the request and response to be logged, or the word
|
prefix |
The prefix added to the start of each log file's name. If not specified, the default value is "access_log". |
renameOnRotate |
By default for a rotatable log the active access log file name
will contain the current timestamp in |
requestAttributesEnabled |
Set to |
resolveHosts |
This attribute is no longer supported. Use the connector
attribute If you have |
rotatable |
Flag to determine if log rotation should occur.
If set to |
suffix |
The suffix added to the end of each log file's name. If not specified, the default value is "" (a zero-length string), meaning that no suffix will be added. |
Values for the pattern attribute are made up of literal
text strings, combined with pattern identifiers prefixed by the "%"
character to cause replacement by the corresponding variable value from
the current request and response. The following pattern codes are
supported:
- %a - Remote IP address
- %A - Local IP address
- %b - Bytes sent, excluding HTTP headers, or '-' if zero
- %B - Bytes sent, excluding HTTP headers
- %h - Remote host name (or IP address if
enableLookupsfor the connector is false) - %H - Request protocol
- %l - Remote logical username from identd (always returns '-')
- %m - Request method (GET, POST, etc.)
- %p - Local port on which this request was received.
See also
%{xxx}pbelow. - %q - Query string (prepended with a '?' if it exists)
- %r - First line of the request (method and request URI)
- %s - HTTP status code of the response
- %S - User session ID
- %t - Date and time, in Common Log Format
- %u - Remote user that was authenticated (if any), else '-'
- %U - Requested URL path
- %v - Local server name
- %D - Time taken to process the request in millis. Note: In httpd %D is microseconds. Behaviour will be aligned to httpd in Tomcat 10 onwards.
- %T - Time taken to process the request, in seconds. Note: This value has millisecond resolution whereas in httpd it has second resolution. Behaviour will be align to httpd in Tomcat 10 onwards.
- %F - Time taken to commit the response, in millis
- %I - Current request thread name (can compare later with stacktraces)
- %X - Connection status when response is completed:
X= Connection aborted before the response completed.+= Connection may be kept alive after the response is sent.-= Connection will be closed after the response is sent.
There is also support to write information incoming or outgoing
headers, cookies, session or request attributes and special
timestamp formats.
It is modeled after the
Apache HTTP Server log configuration
syntax. Each of them can be used multiple times with different xxx keys:
%{xxx}iwrite value of incoming header with namexxx%{xxx}owrite value of outgoing header with namexxx%{xxx}cwrite value of cookie with namexxx%{xxx}rwrite value of ServletRequest attribute with namexxx%{xxx}swrite value of HttpSession attribute with namexxx%{xxx}pwrite local (server) port (xxx==local) or remote (client) port (xxx=remote)%{xxx}twrite timestamp at the end of the request formatted using the enhanced SimpleDateFormat patternxxx
All formats supported by SimpleDateFormat are allowed in %{xxx}t.
In addition the following extensions have been added:
sec- number of seconds since the epochmsec- number of milliseconds since the epochmsec_frac- millisecond fraction
These formats cannot be mixed with SimpleDateFormat formats in the same format token.
Furthermore one can define whether to log the timestamp for the request start time or the response finish time:
beginor prefixbegin:chooses the request start timeendor prefixend:chooses the response finish time
By adding multiple %{xxx}t tokens to the pattern, one can
also log both timestamps.
The shorthand pattern pattern="common"
corresponds to the Common Log Format defined by
'%h %l %u %t "%r" %s %b'.
The shorthand pattern pattern="combined"
appends the values of the Referer and User-Agent
headers, each in double quotes, to the common pattern.
When Tomcat is operating behind a reverse proxy, the client information logged by the Access Log Valve may represent the reverse proxy, the browser or some combination of the two depending on the configuration of Tomcat and the reverse proxy. For Tomcat configuration options see Proxies Support and the Proxy How-To. For reverse proxies that use mod_jk, see the generic proxy documentation. For other reverse proxies, consult their documentation.
Extended Access Log Valve
Introduction
The Extended Access Log Valve extends the
Access Log Valve class, and so
uses the same self-contained logging logic. This means it
implements many of the same file handling attributes. The main
difference to the standard AccessLogValve is that
ExtendedAccessLogValve creates log files which
conform to the Working Draft for the
Extended Log File Format
defined by the W3C.
Attributes
The Extended Access Log Valve supports all
configuration attributes of the standard
Access Log Valve. Only the
values used for className and pattern differ.
| Attribute | Description |
|---|---|
className |
Java class name of the implementation to use. This MUST be set to org.apache.catalina.valves.ExtendedAccessLogValve to use the extended access log valve. |
pattern |
A formatting layout identifying the various information fields from the request and response to be logged. See below for more information on configuring this attribute. |
Values for the pattern attribute are made up of
format tokens. Some of the tokens need an additional prefix. Possible
prefixes are c for "client", s for "server",
cs for "client to server", sc for
"server to client" or x for "application specific".
Furthermore some tokens are completed by an additional selector.
See the W3C specification
for more information about the format.
The following format tokens are supported:
- bytes - Bytes sent, excluding HTTP headers, or '-' if zero
- c-dns - Remote host name (or IP address if
enableLookupsfor the connector is false) - c-ip - Remote IP address
- cs-method - Request method (GET, POST, etc.)
- cs-uri - Request URI
- cs-uri-query - Query string (prepended with a '?' if it exists)
- cs-uri-stem - Requested URL path
- date - The date in yyyy-mm-dd format for GMT
- s-dns - Local host name
- s-ip - Local IP address
- sc-status - HTTP status code of the response
- time - Time the request was served in HH:mm:ss format for GMT
- time-taken - Time (in seconds as floating point) taken to serve the request
- x-threadname - Current request thread name (can compare later with stacktraces)
For any of the x-H(XXX) the following method will be called from the
HttpServletRequest object:
x-H(authType): getAuthTypex-H(characterEncoding): getCharacterEncodingx-H(contentLength): getContentLengthx-H(locale): getLocalex-H(protocol): getProtocolx-H(remoteUser): getRemoteUserx-H(requestedSessionId): getRequestedSessionIdx-H(requestedSessionIdFromCookie): isRequestedSessionIdFromCookiex-H(requestedSessionIdValid): isRequestedSessionIdValidx-H(scheme): getSchemex-H(secure): isSecure
There is also support to write information about headers cookies, context, request or session attributes and request parameters.
cs(XXX)for incoming request headers with name XXXsc(XXX)for outgoing response headers with name XXXx-A(XXX)for the servlet context attribute with name XXXx-C(XXX)for the first cookie with name XXXx-O(XXX)for a concatenation of all outgoing response headers with name XXXx-P(XXX)for the URL encoded (using UTF-8) request parameter with name XXXx-R(XXX)for the request attribute with name XXXx-S(XXX)for the session attribute with name XXX
Access Control
Remote Address Valve
Introduction
The Remote Address Valve allows you to compare the IP address of the client that submitted this request against one or more regular expressions, and either allow the request to continue or refuse to process the request from this client. A Remote Address Valve can be associated with any Catalina container (
