Author: kkolinko
Date: Wed Aug 3 23:29:41 2011
New Revision: 1153703
URL: http://svn.apache.org/viewvc?rev=1153703&view=rev
Log:
CTR: Docs
Update logging documentation
1. Place a better note that Log4J configuration is not needed if it is only
osed by one's webapp.
2. Rearrange Log4J configuration section and document how configure it to be
used by a single CATALINA_BASE only.
3. Add "productive usage considerations" subsection to JULI one.
Modified:
tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml
tomcat/tc6.0.x/trunk/webapps/docs/logging.xml
Modified: tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml?rev=1153703&r1=1153702&r2=1153703&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml (original)
+++ tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml Wed Aug 3 23:29:41 2011
@@ -297,7 +297,8 @@
(markt)
</fix>
<update>
- Improve Tomcat Logging documentation. (kkolinko)
+ Improve class loading documentation and logging documentation.
+ (kkolinko)
</update>
<update>
Configure Security Manager How-To to include a copy of the actual
@@ -336,9 +337,6 @@
(markt)
</fix>
<update>
- Improve class loading documentation. (kkolinko)
- </update>
- <update>
Update documentation to be even more explicit about the implications
of setting the <code>path</code> attribute on a <code>Context</code>
element in <code>server.xml</code>. (markt/kkolinko)
Modified: tomcat/tc6.0.x/trunk/webapps/docs/logging.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/logging.xml?rev=1153703&r1=1153702&r2=1153703&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/logging.xml (original)
+++ tomcat/tc6.0.x/trunk/webapps/docs/logging.xml Wed Aug 3 23:29:41 2011
@@ -85,7 +85,7 @@
by the system and is shared across web applications.
</p>
- <subsection name="java.util.logging">
+ <subsection name="Java logging API — java.util.logging">
<p>
Apache Tomcat has its own implementation of several key elements of
@@ -367,10 +367,10 @@ java.util.logging.ConsoleHandler.formatt
</source>
</p>
- <subsection name="References">
+ <subsection name="Documentation references">
<p>See the following resources for additional information:</p>
<ul>
- <li>Tomcat Javadoc for the
+ <li>Apache Tomcat Javadoc for the
<a
href="api/org/apache/juli/package-summary.html"><code>org.apache.juli</code></a>
package.
</li>
@@ -381,6 +381,26 @@ java.util.logging.ConsoleHandler.formatt
</ul>
</subsection>
+ <subsection name="Considerations for productive 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
+ <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
+ 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
+ log</a>.</p></li>
+ </ul>
+ </subsection>
+
</section>
<section name="Using Log4j">
@@ -389,29 +409,22 @@ java.util.logging.ConsoleHandler.formatt
<a href="http://logging.apache.org/log4j/";>log4j</a> rather than
java.util.logging for all Tomcat's internal logging.
</p>
- <p>Note, that</p>
- <ul>
- <li>This exposes log4j libraries to the web applications through the
- Common classloader. See <a href="class-loader-howto.html">class
loading</a>
- for details. The web applications using
- <a href="http://commons.apache.org/logging";>Apache Commons Logging</a>
- library are likely to automatically choose log4j as the underlying
- logging implementation.</li>
- <li>The <code>java.util.logging</code> API is still available, for
- those who use it directly. Removal of the
- <code>${catalina.base}/conf/logging.properties</code> file, mentioned
- as one of the steps below, causes it to fallback to the default
- configuration configured in JRE, which is to use a ConsoleHandler and
- do not create any files.</li>
- </ul>
+ <p><em>Note</em>: The steps described in this section are needed
+ when you want to reconfigure Tomcat to use Apache log4j for its own
+ logging. These steps are <strong>not</strong> needed if you just want
+ to use log4j in your own web application. — In that case, just
+ put <code>log4j.jar</code> and <code>log4j.properties</code> into
+ <code>WEB-INF/lib</code> and <code>WEB-INF/classes</code>
+ of your web application.
+ </p>
<p>
The following steps describe configuring log4j to output Tomcat's
internal logging.
</p>
<ol>
- <li>Create a file called log4j.properties with the following content
- and save it into $CATALINA_HOME/lib.</li>
+ <li>Create a file called <code>log4j.properties</code> with the
+ following content and save it into <code>$CATALINA_BASE/lib</code></li>
</ol>
<source>
log4j.rootLogger=INFO, CATALINA
@@ -464,25 +477,61 @@ log4j.logger.org.apache.catalina.core.Co
</source>
<ol start="2">
<li><a href="http://logging.apache.org/log4j";>Download Log4J</a>
- (v1.2 or later) and place the log4j jar in $CATALINA_HOME/lib.</li>
+ (v1.2 or later).</li>
+
+ <li><p>Download or build <code>tomcat-juli.jar</code> and
+ <code>tomcat-juli-adapters.jar</code> that are available as an "extras"
+ component for Tomcat. See <a href="extras.html">Additional Components
+ documentation</a> for details.</p>
+ <p>This <code>tomcat-juli.jar</code> differs from the default one. It
+ contains the full Apache Commons Logging implementation and thus is
+ able to discover the presense of log4j and configure itself.</p>
+ </li>
+
+ <li><p>If you want to configure Tomcat to use log4j globally:</p>
+ <ul>
+ <li>Put log4j.jar into <code>$CATALINA_HOME/lib</code>.</li>
+ <li>Replace <code>$CATALINA_HOME/bin/tomcat-juli.jar</code> with
+ <code>tomcat-juli.jar</code> from "extras".</li>
+ <li>Put <code>tomcat-juli-adapters.jar</code> from "extras" into
+ <code>$CATALINA_HOME/lib</code></li>
+ </ul>
+ </li>
+
+ <li><p>If you are running Tomcat with separate $CATALINA_HOME and
+ $CATALINA_BASE and want to configure to use log4j in a single
+ $CATALINA_BASE only:</p>
+ <ul>
+ <li>Create <code>$CATALINA_BASE/bin</code> and
+ <code>$CATALINA_BASE/lib</code> directories if they do not exist.
+ </li>
+ <li>Put log4j.jar into <code>$CATALINA_BASE/lib</code></li>
+ <li>Put <code>tomcat-juli.jar</code> from "extras" as
+ <code>$CATALINA_BASE/bin/tomcat-juli.jar</code></li>
+ <li>Put <code>tomcat-juli-adapters.jar</code> from "extras" into
+ <code>$CATALINA_BASE/lib</code></li>
+ <li>If you are running with a
+ <a href="security-manager-howto.html">security manager</a>, you
+ would need to edit the
+ <code>$CATALINA_BASE/conf/catalina.policy</code> file to adjust
+ it to using a different copy of tomcat-juli.jar.</li>
+ <li>The old <code>tomcat-juli.jar</code> in
+ <code>$CATALINA_HOME/bin</code> is still referenced by manifest of
+ <code>bootstrap.jar</code> and thus will be implicitly present
+ on Tomcat's classpath. The startup scripts configure
+ <code>$CATALINA_BASE/bin/tomcat-juli.jar</code> to be earlier on the
+ classpath than <code>bootstrap.jar</code>, and so it should have
+ higher priority. Thus it should be OK, but
+ consider removing the unneeded copy of <code>tomcat-juli.jar</code>
+ (copy it into all other $CATALINA_BASEs that do not use log4j).
+ Tomcat 7 does not have this issue.</li>
+ </ul>
+ </li>
+
+ <li><p>Delete <code>$CATALINA_BASE/conf/logging.properties</code> to
+ prevent java.util.logging generating zero length log files.</p></li>
- <li>Build or download the additional logging components. See the
- <a href="extras.html">extras components</a> documentation for
- details.</li>
-
- <li>Replace <code>$CATALINA_HOME/bin/tomcat-juli.jar</code> with
- <code>output/extras/tomcat-juli.jar</code>.</li>
-
- <li>Place <code>output/extras/tomcat-juli-adapters.jar</code> in
- $CATALINA_HOME/lib.<br />
- Note, that <code>tomcat-juli.jar</code> and
- <code>tomcat-juli-adapters.jar</code> go into different
- directories. While the first one goes into <code>bin</code>, this
- one goes into <code>lib</code>.</li>
-
- <li>Delete <code>$CATALINA_BASE/conf/logging.properties</code> to
- prevent java.util.logging generating zero length log files.</li>
- <li>Start Tomcat</li>
+ <li><p>Start Tomcat</p></li>
</ol>
<p>
@@ -491,7 +540,7 @@ log4j.logger.org.apache.catalina.core.Co
individual log file, and everything else goes to the "catalina.log" log
file. Each file is rolled-over once per day.
</p>
-
+
<p>
You can (and should) be more picky about which packages to include
in the logging. Tomcat defines loggers by Engine and Host names.
@@ -500,18 +549,19 @@ log4j.logger.org.apache.catalina.core.Co
using this naming convention (with square brackets) in log4j XML based
configuration files, so we recommend you use a properties file as
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>
- Be warned a level of DEBUG will produce megabytes of logging and slow
+ <p>
+ Be warned: a level of DEBUG will produce megabytes of logging and slow
startup of Tomcat. This level should be used sparingly when debugging of
internal Tomcat operations is required.
</p>
-
+
<p>
Your web applications should certainly use their own log4j
configuration.
This is valid <i>with</i> the above configuration. You would place a
@@ -524,20 +574,26 @@ log4j.logger.org.apache.catalina.session
bootstrapping guide.
</p>
- <p>
- If you have multiple instances of Tomcat, each with a separate
- <code>$CATALINA_BASE</code> but a shared <code>$CATALINA_HOME</code> then
- you can configure log4j on a per instance basis by replacing references
to
- <code>$CATALINA_HOME</code> in the above instructions with
- <code>$CATALINA_BASE</code>. Note that if you do this then you may need
to
- make some, or all, of the following additional changes:
- <ul>
- <li>create a <code>$CATALINA_BASE/bin</code> directory</li>
- <li>create a <code>$CATALINA_BASE/lib</code> directory</li>
- <li>if running with a security manager, adjust the codebase for JULI in
- <code>$CATALINA_BASE/conf/catalina.policy</code></li>
- </ul>
- </p>
+ <p><em>Additional notes</em></p>
+ <ul>
+ <li><p>This exposes log4j libraries to the web applications through the
+ Common classloader. See <a href="class-loader-howto.html">class
loading</a>
+ documentation for details.</p>
+ <p>Because of that, the web applications and libraries using
+ <a href="http://commons.apache.org/logging";>Apache Commons Logging</a>
+ 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
+ <code>${catalina.base}/conf/logging.properties</code> file is still
+ referenced by Tomcat startup scripts.</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>
+ </ul>
</section>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
