yoavs 2004/11/19 07:38:37
Modified: webapps/docs changelog.xml logging.xml
Log:
Bugzilla 32249: Updated logging documentation
Revision Changes Path
1.175 +3 -0 jakarta-tomcat-catalina/webapps/docs/changelog.xml
Index: changelog.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/changelog.xml,v
retrieving revision 1.174
retrieving revision 1.175
diff -u -r1.174 -r1.175
--- changelog.xml 19 Nov 2004 15:07:39 -0000 1.174
+++ changelog.xml 19 Nov 2004 15:38:36 -0000 1.175
@@ -38,6 +38,9 @@
<update>
<bug>22679</bug>: Added misc note on accessing session ID to
SSL-HowTo. (yoavs)
</update>
+ <update>
+ <bug>32249</bug>: Updated logging documentation. (yoavs)
+ </update>
</changelog>
</subsection>
1.4 +121 -57 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.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- logging.xml 17 Nov 2004 10:35:29 -0000 1.3
+++ logging.xml 19 Nov 2004 15:38:36 -0000 1.4
@@ -9,76 +9,140 @@
<properties>
<title>Logging in Tomcat</title>
<author>Allistair Crossley</author>
+ <author email="[EMAIL PROTECTED]">Yoav Shapira</author>
</properties>
<body>
<section name="Introduction">
- </section>
+ <p>
+ Tomcat 5.5 uses
+ <a href="http://jakarta.apache.org/commons/logging";>Commons Logging</a>
+ throughout its internal code allowing the
+ developer to choose a logging configuration that suits their needs, e.g
+ JDK Logging or
+ <a href="http://logging.apache.org/log4j";>Log4J</a>.
+ Commons Logging provides Tomcat the ability to log
+ hierarchially across various log levels without needing to rely on a
particular
+ logging implementation.
+ </p>
+ <p>
+ An important consequence for Tomcat 5.5 is that the <Logger>
element found in
+ previous versions to create a <code>localhost_log</code> is no longer a
valid nested element
+ of <Context>. Instead, <code>stdout</code> will collect runtime
exceptions and other uncaught
+ exception generated by web applications. If the developer wishes to
collect detailed internal
+ Tomcat logging (i.e what is happening within the Tomcat engine), then
they should configure
+ a logging system such as JDK Logging or log4j as detailed next.
+ </p>
- <section name="java.util.logging">
</section>
<section name="log4j">
<p>
- Tomcat 5.5 has done away with localhost_log which you may be
familiar with
- as the runtime exception/stack trace log. These types of error
are usually thrown
- by uncaught exceptions, but are still valuable to the
developer. They can now be
- found in the stdout log.
- </p>
-
- <p>
- If you need to setup cross-context detailed logging from within
Tomcat's code, then you can use a simple
- log4j configuration. Note that this logging van be very verbose
depending on the log level you chose to use.
- Note also that a log4j logging configuration is not going to
produce stack trace type logging, that is output to
- stdout as discussed.
- </p>
-
- <p>Follow the following steps to setup a file named tomcat.log that has
internal Tomcat logging output to it.</p>
-
- <ol>
- <li>
- Create a file called log4j.properties with the
following content and save it into common/classes.
- Use the appropriate file path convention for your OS,
here is is Windows, and example *nix path may be
- /var/jakarta-tomcat-5.5.4/logs/tomcat.log
-<source>
-log4j.rootLogger=debug, R
-log4j.appender.R=org.apache.log4j.RollingFileAppender
-log4j.appender.R.File=d:/jakarta-tomcat-5.5.4/logs/tomcat.log
-log4j.appender.R.MaxFileSize=10MB
-log4j.appender.R.MaxBackupIndex=10
-log4j.appender.R.layout=org.apache.log4j.PatternLayout
-log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n
-log4j.logger.org.apache.catalina=DEBUG, R</source>
- </li>
- <li><a>Acquire log4j1.2.8.jar</a> and add it into Tomcat's
common/lib folder.</li>
- <li>Start Tomcat</li>
- </ol>
-
- <p>
- This log4j configuration sets up a file called tomcat.log in
your Tomcat logs folder with a maximum file size of 10MB and
- up to 10 backups. DEBUG level is specified which will result in
the most verbose output from Tomcat. The above generated
- about 5MB of logging with bundled web applications and Struts
web applications.
- </p>
-
- <p>
- You can of course choose to be more picky about which packages
to include in the logging. For example try substituting the
- last line of the above configuration with one of these:
+ Tomcat 5.5 has done away with <code>localhost_log</code> which you may
be familiar with
+ as the runtime exception/stack trace log. These types of error are
usually thrown
+ by uncaught exceptions, but are still valuable to the developer. They
can now be
+ found in the <code>stdout</code> log.
+ </p>
+
+ <p>
+ If you need to setup cross-context detailed logging from within
Tomcat's code,
+ then you can use a simple log4j configuration. Note that this logging
van be very
+ verbose depending on the log level you chose to use. Note also that a
log4j logging
+ configuration is not going to produce stack trace type logging: those
stack traces
+ are output to <code>stdout</code> as discussed above.
+ </p>
+
+ <p>
+ Follow the following steps to setup a file named tomcat.log that has
internal
+ Tomcat logging output to it:
+ </p>
+
+ <p>
+ <ol>
+ <li>Create a file called log4j.properties with the following content
+ and save it into common/classes. </li>
+ <li>Use the appropriate file path convention for your OS. Below is
+ a Window example, which on *nix might be
+ <code>/var/jakarta-tomcat-5.5.4/logs/tomcat.log</code>.</li>
+ <li>
+ <source>
+ log4j.rootLogger=debug, R <br />
+ log4j.appender.R=org.apache.log4j.RollingFileAppender <br />
+ log4j.appender.R.File=d:/jakarta-tomcat-5.5.4/logs/tomcat.log
<br />
+ log4j.appender.R.MaxFileSize=10MB <br />
+ log4j.appender.R.MaxBackupIndex=10 <br />
+ log4j.appender.R.layout=org.apache.log4j.PatternLayout <br />
+ log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n <br />
+ log4j.logger.org.apache.catalina=DEBUG, R
+ </source>
+ </li>
+
+ <li><a href="http://logging.apache.org/log4j";>Download Log4J</a>
+ (v1.2 or later) and place the log4j jar in
$CATALINA_HOME/common/lib.</li>
+ <li>Start Tomcat</li>
+ </ol>
+ </p>
+
+ <p>
+ This log4j configuration sets up a file called tomcat.log in your
+ Tomcat logs folder with a maximum file size of 10MB and
+ up to 10 backups. DEBUG level is specified which will result in the
+ most verbose output from Tomcat.
+ </p>
- <ul>
-
<li>log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG,
R</li>
- <li>log4j.logger.org.apache.catalina.core=DEBUG, R</li>
- <li>log4j.logger.org.apache.catalina.session=DEBUG,
R</li>
- </ul>
- </p>
+ <p>
+ You can (and should) be more picky about which packages to include
+ in the logging. For example try substituting the
+ last line of the above configuration with one of these:
+
+ <ul>
+
<li>log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG,
R</li>
+ <li>log4j.logger.org.apache.catalina.core=DEBUG, R</li>
+ <li>log4j.logger.org.apache.catalina.session=DEBUG, R</li>
+ </ul>
+ </p>
- <p>The usefulness of what you will find from the log4j logging is
debatable and will depend on your needs. Your
- web applications should certainly use their own log4j
configuration. This is valid <i>with</i> the above.
- You would place a similar log4j.properties file in your web
application's WEB-INF/classes folder, and log4j1.2.8.jar into
- WEB-INF/lib. Then specify your package level logging. This is a
basic setup of log4j and you should consult the log4j
- documentation for more options, but hopefully this section will
get you up to a basic speed.
- </p>
+ <p>
+ Your web applications should certainly use their own log4j
configuration.
+ This is valid <i>with</i> the above. You would place a similar
log4j.properties
+ file in your web application's WEB-INF/classes folder, and
log4j1.2.8.jar into
+ WEB-INF/lib. Then specify your package level logging. This is a basic
setup of log4j
+ and you should consult the
+ <a
href="http://logging.apache.org/log4j/docs/documentation.html";>log4j
documentation</a>
+ for more options: this page is intended only as a bootstrapping guide.
+ </p>
+ </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>.
+ </p>
+ <p>
+ The default logging.properties specifies a ConsoleHandler for routing
logging to stdout and
+ also a FileHandler. A handler's log level threshold can be set using
SEVERE, CONFIG, INFO,
+ 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.
+ </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.
+ </p>
+
</section>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
