remm 2005/03/03 10:26:40
Modified: webapps/docs logging.xml tomcat-docs.xsl
Log:
- Documentation on JULI.
Revision Changes Path
1.6 +120 -8 jakarta-tomcat-catalina/webapps/docs/logging.xml
Index: logging.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/logging.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- logging.xml 7 Dec 2004 16:38:15 -0000 1.5
+++ logging.xml 3 Mar 2005 18:26:40 -0000 1.6
@@ -128,14 +128,37 @@
</section>
<section name="java.util.logging">
+
<p>
In order to configure JDK logging you should have JDK 1.4+. Tomcat 5.5
is intended for
JDK 5.0, but can be run on JDK 1.4 using a compatibility package.
</p>
<p>
- In order to configure JDK Logging, you should find the JDK's
logging.properties file. Check
- your JAVA_HOME environment setting to see which JDK Tomcat is using (or
maybe JRE 5.0 as Tomcat
- can now run on a JRE from version 5.5). The file will be in
<code>$JAVA_HOME/jre/lib</code>.
+ The default implemenatation 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.
+ </p>
+ <p>
+ JULI is enabled by default in Tomcat 5.5, and supports per classloader
configuration, in addition to
+ the regular global java.util.logging configuration. This means that
logging can be configured at
+ the following layers:
+ <ul>
+ <li>In the JDK's logging.properties file. Check
+ your JAVA_HOME environment setting to see which JDK Tomcat is using
(or maybe JRE 5.0 as Tomcat
+ can now run on a JRE from version 5.5). The file will be in
<code>$JAVA_HOME/jre/lib</code>.
+ Alternately, it can also use a global configuration file located
elsewhere by using the
+ system property <code>java.util.logging.config.file</code>, or
programmatic configuration using
+ <code>java.util.logging.config.class</code>.</li>
+ <li>In each classloader using a logging.properties file. This means
that it is possible to have a
+ configuration for the Tomcat core, as well as separate configurations
for each webapps which will
+ have the same lifecycle as the webapps.</li>
+ </ul>
</p>
<p>
The default logging.properties specifies a ConsoleHandler for routing
logging to stdout and
@@ -143,17 +166,106 @@
WARN, FINE, FINEST or ALL. The logging.properties shipped with JDK is
set to INFO. You
can also target specific packages to collect logging from and specify a
level. Here is how
you would set debugging from Tomcat. You would need to ensure the
ConsoleHandler's level is also
- set to collect this threshold, so FINEST or ALL should be set.
+ set to collect this threshold, so FINEST or ALL should be set. Please
refer to Sun's java.util.logging
+ documentation for the complete details.
</p>
<p>
<source>org.apache.catalina.level=FINEST</source>
</p>
-
<p>
- A limitation of JDK Logging appears to be the inability to have per-web
application logging,
- as the configuration is per-VM. It is advisable to use log4j for per-web
application logging
- as explained below.
+ The configuration used by JULI is extremely similar, but uses a few
extensions to allow better
+ flexibility in assigning loggers. The main differences are:
+ <ul>
+ <li>A prefix may be added to handler names, so that multiple handlers
of a single class may be
+ instantiated. A prefix is a String which starts with a digit, and ends
with '.'. For example,
+ <code>22foobar.</code> is a valid prefix.</li>
+ <li>As in Java 5.0, 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 boolean value.</li>
+ <li>The root logger can define its set of handlers using a
<code>.handlers</code> property.</li>
+ <li>System property replacement for property values which start with
${sytstemPropertyName}.</li>
+ </ul>
</p>
+ <p>
+ Example logging.properties file to be placed in common/classes:
+ <source>
+handlers = 1catalina.org.apache.juli.FileHandler,
2localhost.org.apache.juli.FileHandler, \
+ 3manager.org.apache.juli.FileHandler,
4admin.org.apache.juli.FileHandler, \
+ java.util.logging.ConsoleHandler
+
+.handlers = 1catalina.org.apache.juli.FileHandler,
java.util.logging.ConsoleHandler
+
+############################################################
+# Handler specific properties.
+# Describes specific configuration info for Handlers.
+############################################################
+
+1catalina.org.apache.juli.FileHandler.level = FINE
+1catalina.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
+1catalina.org.apache.juli.FileHandler.prefix = catalina.
+
+2localhost.org.apache.juli.FileHandler.level = FINE
+2localhost.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
+2localhost.org.apache.juli.FileHandler.prefix = localhost.
+
+3manager.org.apache.juli.FileHandler.level = FINE
+3manager.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
+3manager.org.apache.juli.FileHandler.prefix = manager.
+
+4admin.org.apache.juli.FileHandler.level = FINE
+4admin.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
+4admin.org.apache.juli.FileHandler.prefix = admin.
+
+java.util.logging.ConsoleHandler.level = FINE
+java.util.logging.ConsoleHandler.formatter =
java.util.logging.SimpleFormatter
+
+
+############################################################
+# Facility specific properties.
+# Provides extra control for each logger.
+############################################################
+
+org.apache.catalina.core.ContainerBase.[Catalina].[localhost].level = INFO
+org.apache.catalina.core.ContainerBase.[Catalina].[localhost].handlers = \
+ 2localhost.org.apache.juli.FileHandler
+
+org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager].level
= INFO
+org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager].handlers
= \
+ 3manager.org.apache.juli.FileHandler
+
+org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/admin].level
= INFO
+org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/admin].handlers
= \
+ 4admin.org.apache.juli.FileHandler
+
+# For example, set the com.xyz.foo logger to only log SEVERE
+# messages:
+#org.apache.catalina.startup.ContextConfig.level = FINE
+#org.apache.catalina.startup.HostConfig.level = FINE
+#org.apache.catalina.session.ManagerBase.level = FINE
+ </source>
+ </p>
+
+ <p>
+ Example logging.properties for the servlet-examples web application to
be placed
+ in WEB-INF/classes inside the web application:
+ <source>
+handlers = org.apache.juli.FileHandler, java.util.logging.ConsoleHandler
+
+############################################################
+# Handler specific properties.
+# Describes specific configuration info for Handlers.
+############################################################
+
+org.apache.juli.FileHandler.level = FINE
+org.apache.juli.FileHandler.directory = ${catalina.base}/logs
+org.apache.juli.FileHandler.prefix = servlet-examples.
+
+java.util.logging.ConsoleHandler.level = FINE
+java.util.logging.ConsoleHandler.formatter =
java.util.logging.SimpleFormatter
+ </source>
+ </p>
</section>
1.11 +2 -2 jakarta-tomcat-catalina/webapps/docs/tomcat-docs.xsl
Index: tomcat-docs.xsl
===================================================================
RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/tomcat-docs.xsl,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- tomcat-docs.xsl 3 Jan 2005 22:37:38 -0000 1.10
+++ tomcat-docs.xsl 3 Mar 2005 18:26:40 -0000 1.11
@@ -159,7 +159,7 @@
<xsl:comment>PAGE FOOTER</xsl:comment>
<tr><td colspan="2">
<div align="center"><font color="{$body-link}" size="-1"><em>
- Copyright © 1999-2004, Apache Software Foundation
+ Copyright © 1999-2005, Apache Software Foundation
</em></font></div>
</td></tr>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
