Author: markt
Date: Tue Oct 7 12:31:49 2014
New Revision: 1629867
URL: http://svn.apache.org/r1629867
Log:
Some rewording and other improvements
Modified:
tomcat/trunk/webapps/docs/logging.xml
Modified: tomcat/trunk/webapps/docs/logging.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/logging.xml?rev=1629867&r1=1629866&r2=1629867&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/logging.xml (original)
+++ tomcat/trunk/webapps/docs/logging.xml Tue Oct 7 12:31:49 2014
@@ -36,26 +36,20 @@
<section name="Introduction">
<p>
- Logging in Apache Tomcat is implemented with the help of
- <a href="http://commons.apache.org/logging";>Apache Commons Logging</a>
- library. That library is a thin wrapper above different logging
- frameworks. It provides Tomcat with the ability to log
- hierarchically across various log levels without the need to rely on a
- particular logging implementation.
+ The internal logging for Apache Tomcat uses JULI, a packaged renamed fork
+ of <a href="http://commons.apache.org/logging";>Apache Commons Logging</a>
+ that, by default, is hard-coded to use the <code>java.util.logging</code>
+ framework. This ensures that Tomcat's internal logging and any web
+ application logging will remain independent, even if a web application
+ uses Apache Commons Logging.
</p>
<p>
- Since Tomcat 6.0, Tomcat uses a private package-renamed implementation of
- Apache Commons Logging, to allow web applications to use their own
- independent copies of the original Apache Commons Logging library.
- In the default distribution this private copy of the library
- is simplified and hardcoded to use the <code>java.util.logging</code>
framework.
- </p>
-
- <p>
- To configure Tomcat to use alternative logging frameworks for its
internal
- 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>
+ To configure Tomcat to use an alternative logging framework for its
+ internal logging, one has to replace the JULI impementation that is
+ hard-coded to use <code>java.util.logging</code> with a JULI
+ implementation that retains the full Commons Logging discovery mechanism.
+ Such an implementation 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 <a href="#Using_Log4j">below</a>.
</p>
@@ -65,31 +59,31 @@
</p>
<ul>
<li>
+ Use any logging framework of its choice.
+ </li>
+ <li>
Use system logging API, <code>java.util.logging</code>.
</li>
<li>
Use the logging API provided by the Java Servlets specification,
<code>javax.servlet.ServletContext.log(...)</code>
</li>
- <li>
- Use any logging framework of its choice.
- </li>
</ul>
<p>
- The logging frameworks used by different web applications run
independently
- of each other. See <a href="class-loader-howto.html">class loading</a>
- for more details.
- The exception to this rule is <code>java.util.logging</code>, if it used
- directly or indirectly by your logging library. That is because it is
loaded
- by the system and is shared across web applications.
+ The logging frameworks used by different web applications are
independent.
+ See <a href="class-loader-howto.html">class loading</a> for more details.
+ The exception to this rule is <code>java.util.logging</code>. If it used
+ directly or indirectly by your logging library then elements of it will
be
+ shared across web applications because it is loaded by the system class
+ loader.
</p>
<subsection name="Java logging API — java.util.logging">
<p>
Apache Tomcat has its own implementation of several key elements of
- <code>java.util.logging</code> API. This implementation is called "JULI".
+ <code>java.util.logging</code> API. This implementation is called JULI.
The key component there is a custom LogManager implementation,
that is aware of different web applications running on Tomcat (and
their different class loaders). It supports private per-application
@@ -213,17 +207,19 @@
<p>
The default implementation of java.util.logging provided in the JDK is too
- limited to be useful. A limitation of JDK Logging appears to be the
- inability to have per-web application logging, as the configuration is
- per-VM. As a result, Tomcat will, in the default configuration, replace the
- default LogManager implementation with a container friendly implementation
- called JULI, which addresses these shortcomings. It supports the same
- configuration mechanisms as the standard JDK java.util.logging, using
either
- a programmatic approach, or properties files. The main difference is that
- per-classloader properties files can be set (which enables easy
redeployment
- friendly webapp configuration), and the properties files support slightly
- extended constructs which allows more freedom for defining handlers and
- assigning them to loggers.
+ limited to be useful. The key limitation is the inability to have per-web
+ application logging, as the configuration is per-VM. As a result, Tomcat
+ will, in the default configuration, replace the default LogManager
+ implementation with a container friendly implementation called JULI, which
+ addresses these shortcomings.
+ </p>
+ <p>
+ JULI supports the same configuration mechanisms as the standard JDK
+ <code>java.util.logging</code>, using either a programmatic approach, or
+ properties files. The main difference is that per-classloader properties
+ files can be set (which enables easy redeployment friendly webapp
+ configuration), and the properties files support extended constructs which
+ allows more freedom for defining handlers and assigning them to loggers.
</p>
<p>
JULI is enabled by default, and supports per classloader configuration, in
@@ -255,17 +251,21 @@
a level.
</p>
<p>
- Here is how you would set debugging from Tomcat. You would need to ensure
the
- ConsoleHandler's (or FileHandler's') level is also set to collect this
threshold,
- so FINEST or ALL should be set. Please refer to
<code>java.util.logging</code>
- documentation in the JDK for the complete details:
- </p>
- <source>org.apache.catalina.level=FINEST</source>
- <p>
- The configuration used by JULI is extremely similar to the one supported by
- plain <code>java.util.logging</code>, but uses a few
- extensions to allow better flexibility in assigning loggers. The main
- differences are:
+ To enable debug logging for part of Tomcat's internals, you should
+ configure both the appropriate logger(s) and the appropriate handler(s) to
+ use the <code>FINEST</code> or <code>ALL</code> level. e.g.:
+ </p>
+ <source>org.apache.catalina.session.level=ALL
+java.util.logging.ConsoleHandler.level=ALL</source>
+ <p>
+ When enabling debug logging it is recommended that it is enabled for the
+ narrowest possible scope as debug logging can generate large amounts of
+ information.
+ </p>
+ <p>
+ The configuration used by JULI is the same as the one supported by plain
+ <code>java.util.logging</code>, but uses a few extensions to allow better
+ flexibility in configuring loggers and handlers. The main differences are:
</p>
<ul>
<li>A prefix may be added to handler names, so that multiple handlers of
a
@@ -274,8 +274,6 @@
prefix.</li>
<li>System property replacement is performed for property values which
contain ${systemPropertyName}.</li>
- <li>As in Java 6, loggers can define a list of handlers using the
- <code>loggerName.handlers</code> property.</li>
<li>By default, loggers will not delegate to their parent if they have
associated handlers. This may be changed per logger using the
<code>loggerName.useParentHandlers</code> property, which accepts a
@@ -380,23 +378,22 @@ java.util.logging.ConsoleHandler.formatt
</ul>
</subsection>
- <subsection name="Considerations for productive usage">
+ <subsection name="Considerations for production usage">
<p>You may want to take note of the following:</p>
<ul>
- <li><p>Consider removing <code>ConsoleHandler</code> from
configuration.</p>
- <p>By default (thanks to the <code>.handlers</code> setting) logging
goes
- both to a <code>FileHandler</code> and to a
<code>ConsoleHandler</code>.
- The output of the latter one is usually captured into a file, such as
+ <li>Consider removing <code>ConsoleHandler</code> from configuration.
By
+ default (thanks to the <code>.handlers</code> setting) logging goes
both
+ to a <code>FileHandler</code> and to a <code>ConsoleHandler</code>. The
+ output of the latter one is usually captured into a file, such as
<code>catalina.out</code>. Thus you end up with two copies of the same
- messages.</p>
- </li>
- <li><p>Consider removing <code>FileHandler</code>s for the applications
- that you do not use. E.g., the one for
<code>host-manager</code>.</p></li>
- <li><p>The handlers by default use the system default encoding to write
+ messages.</li>
+ <li>Consider removing <code>FileHandler</code>s for the applications
+ that you do not use. E.g., the one for <code>host-manager</code>.</li>
+ <li>The handlers by default use the system default encoding to write
the log files. It can be configured with <code>encoding</code>
property.
- See Javadoc for details.</p></li>
- <li><p>Consider configuring an
- <a href="config/valve.html#Access_Logging">Access log</a>.</p></li>
+ See Javadoc for details.</li>
+ <li>Consider configuring an
+ <a href="config/valve.html#Access_Logging">Access log</a>.</li>
</ul>
</subsection>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
