You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by rj...@apache.org on 2011/07/12 00:08:30 UTC
svn commit: r1145381 - in /tomcat/trunk/webapps/docs: changelog.xml
config/valve.xml
Author: rjung
Date: Mon Jul 11 22:08:30 2011
New Revision: 1145381
URL: http://svn.apache.org/viewvc?rev=1145381&view=rev
Log:
A little bit of docs is better than nothing ...
Modified:
tomcat/trunk/webapps/docs/changelog.xml
tomcat/trunk/webapps/docs/config/valve.xml
Modified: tomcat/trunk/webapps/docs/changelog.xml
URL: http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/changelog.xml?rev=1145381&r1=1145380&r2=1145381&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/changelog.xml (original)
+++ tomcat/trunk/webapps/docs/changelog.xml Mon Jul 11 22:08:30 2011
@@ -142,6 +142,9 @@
improve the <c:if> example to make failures more obvious. Based on
suggestions by Charles. (markt)
</fix>
+ <add>
+ Document ExtendedAccessLogValve. (rjung)
+ </add>
</changelog>
</subsection>
<subsection name="Other">
Modified: tomcat/trunk/webapps/docs/config/valve.xml
URL: http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/config/valve.xml?rev=1145381&r1=1145380&r2=1145381&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/config/valve.xml (original)
+++ tomcat/trunk/webapps/docs/config/valve.xml Mon Jul 11 22:08:30 2011
@@ -128,9 +128,7 @@
from the request and response to be logged, or the word
<code>common</code> or <code>combined</code> to select a
standard format. See below for more information on configuring
- this attribute. Note that the optimized access does only support
- <code>common</code> and <code>combined</code> as the value for this
- attribute.</p>
+ this attribute.</p>
</attribute>
<attribute name="prefix" required="false">
@@ -279,6 +277,185 @@
</section>
+<section name="Extended Access Log Valve">
+
+ <subsection name="Introduction">
+
+ <p>The <strong>Extended Access Log Valve</strong> 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
+ <a href="http://www.w3.org/TR/WD-logfile.html">Extended Log File Format</a>
+ defined by the W3C. The main difference to the standard
+ <code>AccessLogValve</code> are the supported pattern values.</p>
+
+ </subsection>
+
+ <subsection name="Attributes">
+
+ <p>The <strong>Extended Access Log Valve</strong> supports the following
+ configuration attributes:</p>
+
+ <attributes>
+
+ <attribute name="className" required="true">
+ <p>Java class name of the implementation to use. This MUST be set to
+ <strong>org.apache.catalina.valves.ExtendedAccessLogValve</strong> to
+ use the extended access log valve.</p>
+ </attribute>
+
+ <attribute name="directory" required="false">
+ <p>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).</p>
+ </attribute>
+
+ <attribute name="encoding" required="false">
+ <p>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.
+ </p>
+ </attribute>
+
+ <attribute name="pattern" required="false">
+ <p>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.</p>
+ </attribute>
+
+ <attribute name="prefix" required="false">
+ <p>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.</p>
+ </attribute>
+
+ <attribute name="requestAttributesEnabled" required="false">
+ <p>Set to <code>true</code> 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 <code>false</code> then the values
+ from the request will be used. If not set, the default value of
+ <code>false</code> will be used.</p>
+ </attribute>
+
+ <attribute name="resolveHosts" required="false">
+ <p>Set to <code>true</code> to convert the IP address of the remote
+ host into the corresponding host name via a DNS lookup. Set to
+ <code>false</code> to skip this lookup, and report the remote IP
+ address instead.</p>
+ </attribute>
+
+ <attribute name="suffix" required="false">
+ <p>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.</p>
+ </attribute>
+
+ <attribute name="rotatable" required="false">
+ <p>Flag to determine if log rotation should occur.
+ If set to <code>false</code>, then this file is never rotated and
+ <code>fileDateFormat</code> is ignored. Use with caution!
+ Default value: <code>true</code>
+ </p>
+ </attribute>
+
+ <attribute name="condition" required="false">
+ <p>Turns on conditional logging. If set, requests will be
+ logged only if <code>ServletRequest.getAttribute()</code> is
+ null. For example, if this value is set to
+ <code>junk</code>, then a particular request will only be logged
+ if <code>ServletRequest.getAttribute("junk") == null</code>.
+ The use of Filters is an easy way to set/unset the attribute
+ in the ServletRequest on many different requests.
+ </p>
+ </attribute>
+
+ <attribute name="fileDateFormat" required="false">
+ <p>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: <code>yyyy-MM-dd.HH</code>. The default value is
+ <code>yyyy-MM-dd</code>. The date format will always be localized
+ using the locale <code>en_US</code>.
+ </p>
+ </attribute>
+
+ <attribute name="buffered" required="false">
+ <p>Flag to determine if logging will be buffered.
+ If set to <code>false</code>, then access logging will be written after each
+ request. Default value: <code>true</code>
+ </p>
+ </attribute>
+
+ </attributes>
+
+ <p>Values for the <code>pattern</code> attribute are made up of
+ format tokens. Some of the tokens need an additional prefix. Possible
+ prefixes are <code>c</code> for "client", <code>s</code> for "server",
+ <code>cs</code> for "client to server", <code>sc</code> for
+ "server to client" or <code>x</code> for "application specific".
+ Furthermore some tokens are completed by an additional selector.
+ See the <a href="http://www.w3.org/TR/WD-logfile.html">W3C specification</a>
+ for more information about the format.</p>
+
+ <p>The following format tokens are supported:</p>
+ <ul>
+ <li><b>bytes</b> - Bytes sent, excluding HTTP headers, or '-' if zero</li>
+ <li><b>c-dns</b> - Remote host name</li>
+ <li><b>c-ip</b> - Remote IP address</li>
+ <li><b>cs-method</b> - Request method (GET, POST, etc.)</li>
+ <li><b>cs-uri</b> - Request URI</li>
+ <li><b>cs-uri-query</b> - Query string (prepended with a '?' if it exists)</li>
+ <li><b>cs-uri-stem</b> - Requested URL path</li>
+ <li><b>date</b> - The date in yyyy-mm-dd format for GMT</li>
+ <li><b>s-dns</b> - Local host name</li>
+ <li><b>s-ip</b> - Local IP address</li>
+ <li><b>sc-status</b> - HTTP status code of the response</li>
+ <li><b>time</b> - Time the request was served in HH:mm:ss format for GMT</li>
+ <li><b>time-taken</b> - Time (in seconds as floating point) taken to serve the request</li>
+ </ul>
+
+ <p>For any of the <code>x-H(XXX)</code> the following method will be called from the
+ HttpServletRequestObject:</p>
+ <ul>
+ <li><b><code>x-H(authType)</code></b>: getAuthType </li>
+ <li><b><code>x-H(characterEncoding)</code></b>: getCharacterEncoding </li>
+ <li><b><code>x-H(contentLength)</code></b>: getContentLength </li>
+ <li><b><code>x-H(locale)</code></b>: getLocale</li>
+ <li><b><code>x-H(protocol)</code></b>: getProtocol </li>
+ <li><b><code>x-H(remoteUser)</code></b>: getRemoteUser</li>
+ <li><b><code>x-H(requestedSessionId)</code></b>: getGequestedSessionId</li>
+ <li><b><code>x-H(requestedSessionIdFromCookie)</code></b>:
+ isRequestedSessionIdFromCookie </li>
+ <li><b><code>x-H(requestedSessionIdValid)</code></b>:
+ isRequestedSessionIdValid</li>
+ <li><b><code>x-H(scheme)</code></b>: getScheme</li>
+ <li><b><code>x-H(secure)</code></b>: isSecure</li>
+ </ul>
+
+ <p>
+ There is also support to write information about headers
+ cookies, context, request or session attributes and request
+ parameters.
+ </p>
+ <ul>
+ <li><b><code>cs(XXX)</code></b> for incoming request headers with name XXX</li>
+ <li><b><code>sc(XXX)</code></b> for outgoing response headers with name XXX</li>
+ <li><b><code>x-A(XXX)</code></b> for the servlet context attribute with name XXX</li>
+ <li><b><code>x-C(XXX)</code></b> for the first cookie with name XXX</li>
+ <li><b><code>x-O(XXX)</code></b> for a concatenation of all outgoing response headers with name XXX</li>
+ <li><b><code>x-P(XXX)</code></b> for the URL encoded request parameter with name XXX</li>
+ <li><b><code>x-R(XXX)</code></b> for the request attribute with name XXX</li>
+ <li><b><code>x-S(XXX)</code></b> for the session attribute with name XXX</li>
+ </ul>
+
+ </subsection>
+
+</section>
+
+
<section name="Remote Address Filter">
<subsection name="Introduction">
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org