From 16263e935f5895a99a4fe61a2effe272678ec12e Mon Sep 17 00:00:00 2001 From: rjung Date: Mon, 11 Jul 2011 22:08:30 +0000 Subject: [PATCH] A little bit of docs is better than nothing ... git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@1145381 13f79535-47bb-0310-9956-ffa450edef68 --- webapps/docs/changelog.xml | 3 + webapps/docs/config/valve.xml | 183 +++++++++++++++++++++++++++++++++++++++++- 2 files changed, 183 insertions(+), 3 deletions(-) diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml index 0400137b3..d614a686a 100644 --- a/webapps/docs/changelog.xml +++ b/webapps/docs/changelog.xml @@ -142,6 +142,9 @@ improve the <c:if> example to make failures more obvious. Based on suggestions by Charles. (markt) + + Document ExtendedAccessLogValve. (rjung) + diff --git a/webapps/docs/config/valve.xml b/webapps/docs/config/valve.xml index a4cf4ee67..8eb9d73a1 100644 --- a/webapps/docs/config/valve.xml +++ b/webapps/docs/config/valve.xml @@ -128,9 +128,7 @@ from the request and response to be logged, or the word common or combined to select a standard format. See below for more information on configuring - this attribute. Note that the optimized access does only support - common and combined as the value for this - attribute.

+ this attribute.

@@ -279,6 +277,185 @@ +
+ + + +

The Extended Access Log Valve is a variant of + the Access Log Valve. It is not a real extension of the standard + Access Log valve, instead it supports the so-called + Extended Log File Format + defined by the W3C. The main difference to the standard + AccessLogValve are the supported pattern values.

+ + + + + +

The Extended Access Log Valve supports the following + configuration attributes:

+ + + + +

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.

+ + + +

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).

+ + + +

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. +

+ + + +

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.

+ + + +

The prefix added to the start of each log file's name. If not + specified, the default value is "access_log.". To specify no prefix, + use a zero-length string.

+ + + +

Set to true to check for the existance of request + attributes (typically set by the RemoteIpValve and similar) that should + be used to override the values returned by the request for remote + address, remote host, server port and protocol. If the attributes are + not set, or this attribute is set to false then the values + from the request will be used. If not set, the default value of + false will be used.

+ + + +

Set to true to convert the IP address of the remote + host into the corresponding host name via a DNS lookup. Set to + false to skip this lookup, and report the remote IP + address instead.

+ + + +

The suffix added to the end of each log file's name. If not + specified, the default value is "". To specify no suffix, + use a zero-length string.

+ + + +

Flag to determine if log rotation should occur. + If set to false, then this file is never rotated and + fileDateFormat is ignored. Use with caution! + Default value: true +

+ + + +

Turns on conditional logging. If set, requests will be + logged only if ServletRequest.getAttribute() is + null. For example, if this value is set to + junk, then a particular request will only be logged + if ServletRequest.getAttribute("junk") == null. + The use of Filters is an easy way to set/unset the attribute + in the ServletRequest on many different requests. +

+ + + +

Allows a customized date format in the access log file name. + The date format also decides how often the file is rotated. + If you wish to rotate every hour, then set this value + to: yyyy-MM-dd.HH. The default value is + yyyy-MM-dd. The date format will always be localized + using the locale en_US. +

+ + + +

Flag to determine if logging will be buffered. + If set to false, then access logging will be written after each + request. Default value: true +

+ + + + +

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
    • +
  • 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
    • +
+ +

For any of the x-H(XXX) the following method will be called from the + HttpServletRequestObject:

+
    +
  • x-H(authType): getAuthType
    • +
  • x-H(characterEncoding): getCharacterEncoding
    • +
  • x-H(contentLength): getContentLength
    • +
  • x-H(locale): getLocale
    • +
  • x-H(protocol): getProtocol
    • +
  • x-H(remoteUser): getRemoteUser
    • +
  • x-H(requestedSessionId): getGequestedSessionId
    • +
  • x-H(requestedSessionIdFromCookie): + isRequestedSessionIdFromCookie
    • +
  • x-H(requestedSessionIdValid): + isRequestedSessionIdValid
    • +
  • x-H(scheme): getScheme
    • +
  • x-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 XXX
    • +
  • sc(XXX) for outgoing response headers with name XXX
    • +
  • x-A(XXX) for the servlet context attribute with name XXX
    • +
  • x-C(XXX) for the first cookie with name XXX
    • +
  • x-O(XXX) for a concatenation of all outgoing response headers with name XXX
    • +
  • x-P(XXX) for the URL encoded request parameter with name XXX
    • +
  • x-R(XXX) for the request attribute with name XXX
    • +
  • x-S(XXX) for the session attribute with name XXX
    • +
+ + + +
+ +
-- 2.11.0