Author: rjung
Date: Wed Dec 5 14:25:00 2012
New Revision: 1417437
URL: http://svn.apache.org/viewvc?rev=1417437&view=rev
Log:
Improve ALV docs:
- Log file name stuff
- Remove redudant but incompletely maintained attribute
documentation form Extended ALV. Instead refer to the
docs for the base clas and clarify the differences.
- Logically reorder attribute docs for ALV.
It was neither alphabetical nor especially
logical before. Hope this one is better.
Backports of r1417363 and r1417370-1417372
with a small difference in a skipped leading dot
in fileDateFormat example and default.
Modified:
tomcat/tc7.0.x/trunk/ (props changed)
tomcat/tc7.0.x/trunk/webapps/docs/config/valve.xml
Propchange: tomcat/tc7.0.x/trunk/
------------------------------------------------------------------------------
Merged /tomcat/trunk:r1417363,1417370-1417372
Modified: tomcat/tc7.0.x/trunk/webapps/docs/config/valve.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/docs/config/valve.xml?rev=1417437&r1=1417436&r2=1417437&view=diff
==============================================================================
--- tomcat/tc7.0.x/trunk/webapps/docs/config/valve.xml (original)
+++ tomcat/tc7.0.x/trunk/webapps/docs/config/valve.xml Wed Dec 5 14:25:00 2012
@@ -80,6 +80,17 @@
<code>AccessLog</code> implementation found to log those requests that are
rejected before they are passed to a container.</p>
+ <p>The output file will be placed in the directory given by the
+ <code>directory</code> attribute. The name of the file is composed
+ by concatenation of the configured <code>prefix</code>, timestamp and
+ <code>suffix</code>. The format of the timestamp in the file name can be
+ set using the <code>fileDateFormat</code> attribute. This timestamp will
+ be omitted if the file rotation is switched off by setting
+ <code>rotatable</code> to <code>false</code>.</p>
+
+ <p><strong>Warning:</strong> If multiple AccessLogValve instances
+ are used, they should be configured to use different output files.</p>
+
<p>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
@@ -108,67 +119,32 @@
(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="locale" required="false">
- <p>The locale used to format timestamps in the access log
- lines. Any timestamps configured using an
- explicit SimpleDateFormat pattern (<code>%{xxx}t</code>)
- are formatted in this locale. By default the
- default locale of the Java process is used. Switching the
- locale after the AccessLogValve is initialized is not supported.
- Any timestamps using the common log format
- (<code>CLF</code>) are always formatted in the locale
- <code>en_US</code>.
- </p>
- </attribute>
-
- <attribute name="pattern" required="false">
- <p>A formatting layout identifying the various information fields
- 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.</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.".</p>
</attribute>
- <attribute name="requestAttributesEnabled" required="false">
- <p>Set to <code>true</code> to check for the existence 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>This attribute is no longer supported. Use the connector
- attribute <code>enableLookups</code> instead.</p>
- <p>If you have <code>enableLookups</code> on the connector set to
- <code>true</code> and want to ignore it, use <b>%a</b> instead of
- <b>%h</b> in the value of <code>pattern</code>.</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 "" (a zero-length string),
meaning that no suffix will be added.</p>
</attribute>
+ <attribute name="fileDateFormat" required="false">
+ <p>Allows a customized timestamp in the access log file name.
+ The file is rotated whenever the formatted timestamp changes.
+ The default value is <code>yyyy-MM-dd</code>.
+ If you wish to rotate every hour, then set this value
+ to <code>yyyy-MM-dd.HH</code>.
+ The date format will always be localized
+ using the locale <code>en_US</code>.
+ </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!
+ <code>fileDateFormat</code> is ignored.
Default value: <code>true</code>
</p>
</attribute>
@@ -187,6 +163,44 @@
</p>
</attribute>
+ <attribute name="pattern" required="false">
+ <p>A formatting layout identifying the various information fields
+ 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.</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="locale" required="false">
+ <p>The locale used to format timestamps in the access log
+ lines. Any timestamps configured using an
+ explicit SimpleDateFormat pattern (<code>%{xxx}t</code>)
+ are formatted in this locale. By default the
+ default locale of the Java process is used. Switching the
+ locale after the AccessLogValve is initialized is not supported.
+ Any timestamps using the common log format
+ (<code>CLF</code>) are always formatted in the locale
+ <code>en_US</code>.
+ </p>
+ </attribute>
+
+ <attribute name="requestAttributesEnabled" required="false">
+ <p>Set to <code>true</code> to check for the existence 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="conditionIf" required="false">
<p>Turns on conditional logging. If set, requests will be
logged only if <code>ServletRequest.getAttribute()</code> is
@@ -215,16 +229,6 @@
</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
@@ -232,6 +236,21 @@
</p>
</attribute>
+ <attribute name="maxLogMessageBufferSize" required="false">
+ <p>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 <code>256</code> characters. This should
be
+ set to larger than the typical access log message size.</p>
+ </attribute>
+
+ <attribute name="resolveHosts" required="false">
+ <p>This attribute is no longer supported. Use the connector
+ attribute <code>enableLookups</code> instead.</p>
+ <p>If you have <code>enableLookups</code> on the connector set to
+ <code>true</code> and want to ignore it, use <b>%a</b> instead of
+ <b>%h</b> in the value of <code>pattern</code>.</p>
+ </attribute>
+
</attributes>
<p>Values for the <code>pattern</code> attribute are made up of literal
@@ -330,8 +349,10 @@
<subsection name="Attributes">
- <p>The <strong>Extended Access Log Valve</strong> supports the following
- configuration attributes:</p>
+ <p>The <strong>Extended Access Log Valve</strong> supports all
+ configuration attributes of the standard
+ <a href="#Access_Log_Valve">Access Log Valve.</a> Only the
+ values used for <code>className</code> and <code>pattern</code> differ.</p>
<attributes>
@@ -341,106 +362,12 @@
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.".</p>
- </attribute>
-
- <attribute name="requestAttributesEnabled" required="false">
- <p>Set to <code>true</code> to check for the existence 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>This attribute is no longer supported. Use the connector
- attribute <code>enableLookups</code> 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 "" (a zero-length string),
- meaning that no suffix will be added.</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="conditionIf" required="false">
- <p>Turns on conditional logging. If set, requests will be
- logged only if <code>ServletRequest.getAttribute()</code> is
- not null. For example, if this value is set to
- <code>important</code>, then a particular request will only be
logged
- if <code>ServletRequest.getAttribute("important") != 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="conditionUnless" 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="condition" required="false">
- <p>The same as <code>conditionUnless</code>. This attribute is
- provided for backwards compatibility.
- </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
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
