Author: markt
Date: Thu Aug 29 08:28:43 2013
New Revision: 1518536
URL: http://svn.apache.org/r1518536
Log:
Fix https://issues.apache.org/bugzilla/show_bug.cgi?id=55215
Additional clarifications to logging documentation that make clear why access
logs are handled separately. Patch provided by Brian Burch.
Modified:
tomcat/trunk/webapps/docs/config/valve.xml
tomcat/trunk/webapps/docs/logging.xml
Modified: tomcat/trunk/webapps/docs/config/valve.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/config/valve.xml?rev=1518536&r1=1518535&r2=1518536&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/config/valve.xml (original)
+++ tomcat/trunk/webapps/docs/config/valve.xml Thu Aug 29 08:28:43 2013
@@ -57,13 +57,19 @@
<subsection name="Introduction">
- <p>The <strong>Access Log Valve</strong> 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. The files produces by this
<code>Valve</code>
- are rolled over nightly at midnight. This <code>Valve</code>
- may be associated with any Catalina container (<code>Context</code>,
- <code>Host</code>, or <code>Engine</code>), and
+ <p>The <strong>Access Log Valve</strong> 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 <code>Valve</code>
+ 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 <code>Valve</code> does not
+ use Apache Commons Logging, thus avoiding additional overhead and
+ potentially complex configuration).</p>
+
+ <p>This <code>Valve</code> may be associated with any Catalina container
+ (<code>Context</code>, <code>Host</code>, or <code>Engine</code>), and
will record ALL requests processed by that container.</p>
<p>Some requests may be handled by Tomcat before they are passed to a
@@ -339,12 +345,15 @@
<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
+ <p>The <strong>Extended Access Log Valve</strong> extends the
+ <a href="#Access_Log_Valve">Access Log Valve</a> 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 <code>AccessLogValve</code> is that
+ <code>ExtendedAccessLogValve</code> creates log files which
+ conform to the the Working Draft for the
<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>
+ defined by the W3C.</p>
</subsection>
Modified: tomcat/trunk/webapps/docs/logging.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/logging.xml?rev=1518536&r1=1518535&r2=1518536&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/logging.xml (original)
+++ tomcat/trunk/webapps/docs/logging.xml Thu Aug 29 08:28:43 2013
@@ -57,7 +57,7 @@
logging, one has to replace the logging library with the one that is
built
with the full implementation. Such library is provided as an <a
href="extras.html">extras</a>
component. Instructions on how to configure Tomcat to use Log4j framework
- for its internal logging may be found below.
+ for its internal logging may be found <a href="#Using_Log4j">below</a>.
</p>
<p>
@@ -193,9 +193,16 @@
<subsection name="Access logging">
<p>
- A related, but different feature is access logging. It can be configured
- as a valve at the Context, or Host, or Engine. See <a
href="config/valve.html">Valves</a>
- documentation for more details.
+ Access logging is a related but different feature, which is
+ implemented as a <code>Valve</code>. It uses self-contained
+ logic to write its log files. The essential requirement for
+ access logging is to handle a large continuous stream of data
+ with low overhead, so it only uses Apache Commons Logging for
+ its own debug messages. This implementation approach avoids
+ additional overhead and potentially complex configuration.
+ Please refer to the <a href="config/valve.html">Valves</a>
+ documentation for more details on its configuration, including
+ the various report formats.
</p>
</subsection>
@@ -547,10 +554,10 @@ log4j.logger.org.apache.catalina.core.Co
described until a future version of log4j allows this convention.
</p>
<source>
-log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG<br
/>
-log4j.logger.org.apache.catalina.core=DEBUG<br />
-log4j.logger.org.apache.catalina.session=DEBUG<br />
-</source>
+log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG<br/>
+log4j.logger.org.apache.catalina.core=DEBUG<br/>
+log4j.logger.org.apache.catalina.session=DEBUG<br/>
+ </source>
<p>
Be warned: a level of DEBUG will produce megabytes of logging and slow
@@ -580,15 +587,26 @@ log4j.logger.org.apache.catalina.session
library are likely to automatically choose log4j as the underlying
logging implementation.</p></li>
- <li><p>The <code>java.util.logging</code> API is still available, for
- those web applications that use it directly. The
+ <li><p>The <code>java.util.logging</code> API is still available for
+ those web applications that use it directly. The
<code>${catalina.base}/conf/logging.properties</code> file is still
- referenced by Tomcat startup scripts.</p>
+ referenced by Tomcat startup scripts. For more information, see the
+ subsections of the <a href="#Introduction">Introduction</a> to
+ this page.</p>
<p> Removal of <code>${catalina.base}/conf/logging.properties</code>
- file, mentioned as one of the steps, just causes
- <code>java.util.logging</code> to fallback to the default configuration
- as configured in JRE, which is to use a ConsoleHandler and do not
- create any files.</p></li>
+ file, mentioned as one of the steps above, causes
+ <code>java.util.logging</code> to fallback to the default
+ configuration for the JRE, which is to use a ConsoleHandler
+ and therefore not create any standard log files. You should
+ confirm that all your log files are being created by log4j
+ <i>before</i> disabling the standard mechanism.</p></li>
+
+ <li><p>The <strong>Access Log Valve</strong> and
+ <strong>ExtendedAccessLogValve</strong> use their own self-contained
+ logging implementation, so they
+ <strong><i>cannot be configured to use log4j</i></strong>.
+ Refer to <a href="config/valve.html#Access_Log_Valve">Valves</a>
+ for specific configuration details.</p></li>
</ul>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
