From 6b4736aac515d1514ff81c2564df9f73d86bc646 Mon Sep 17 00:00:00 2001 From: kkolinko Date: Wed, 3 Aug 2011 22:57:35 +0000 Subject: [PATCH] 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. git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@1153696 13f79535-47bb-0310-9956-ffa450edef68 --- webapps/docs/changelog.xml | 5 +- webapps/docs/logging.xml | 152 +++++++++++++++++++++++++++++---------------- 2 files changed, 102 insertions(+), 55 deletions(-) diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml index ec3b87d59..ac7e04335 100644 --- a/webapps/docs/changelog.xml +++ b/webapps/docs/changelog.xml @@ -115,7 +115,7 @@ Servlet instance. (markt) - Committing connection if autoCommit is false. + In JDBCStore: Committing connection if autoCommit is false. Make sure committed connection is returned to the pool if datasource is enabled. (kfujino) @@ -215,7 +215,8 @@ $CATALINA_BASE. (markt) - Improve class loading documentation. (kkolinko) + Improve class loading documentation and logging documentation. + (kkolinko) Add information to the security page of the the documentation web diff --git a/webapps/docs/logging.xml b/webapps/docs/logging.xml index 9c43e4e94..796c1116d 100644 --- a/webapps/docs/logging.xml +++ b/webapps/docs/logging.xml @@ -85,7 +85,7 @@ by the system and is shared across web applications.

- +

Apache Tomcat has its own implementation of several key elements of @@ -364,10 +364,10 @@ java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

- +

See the following resources for additional information:

    -
  • Tomcat Javadoc for the +
  • Apache Tomcat Javadoc for the org.apache.juli package.
    • @@ -378,6 +378,26 @@ java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
+ +

You may want to take note of the following:

+
    +

  • Consider removing ConsoleHandler from configuration.

    +

    By default (thanks to the .handlers setting) logging goes + both to a FileHandler and to a ConsoleHandler. + The output of the latter one is usually captured into a file, such as + catalina.out. Thus you end up with two copies of the same + messages.

    +
    • +

  • Consider removing FileHandlers for the applications + that you do not use. E.g., the one for host-manager.

    • +

  • The handlers by default use the system default encoding to write + the log files. It can be configured with encoding property. + See Javadoc for details.

    • +

  • Consider configuring an Access + log.

    • +
+ +
@@ -386,29 +406,22 @@ java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter log4j rather than java.util.logging for all Tomcat's internal logging.

-

Note, that

-
    -
  • This exposes log4j libraries to the web applications through the - Common classloader. See class loading - for details. The web applications using - Apache Commons Logging - library are likely to automatically choose log4j as the underlying - logging implementation.
    • -
  • The java.util.logging API is still available, for - those who use it directly. Removal of the - ${catalina.base}/conf/logging.properties 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.
    • -
+

Note: 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 not needed if you just want + to use log4j in your own web application. — In that case, just + put log4j.jar and log4j.properties into + WEB-INF/lib and WEB-INF/classes + of your web application. +

The following steps describe configuring log4j to output Tomcat's internal logging.

    -
  1. Create a file called log4j.properties with the following content - and save it into $CATALINA_HOME/lib.
    2. +
  2. Create a file called log4j.properties with the + following content and save it into $CATALINA_BASE/lib
log4j.rootLogger=INFO, CATALINA @@ -461,25 +474,51 @@ log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/hos
  1. Download Log4J - (v1.2 or later) and place the log4j jar in $CATALINA_HOME/lib.
    2. + (v1.2 or later). + +

  2. Download or build tomcat-juli.jar and + tomcat-juli-adapters.jar that are available as an "extras" + component for Tomcat. See Additional Components + documentation for details.

    +

    This tomcat-juli.jar 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.

    +
    3. -
  3. Build or download the additional logging components. See the - extras components documentation for - details.
    4. +

  4. If you want to configure Tomcat to use log4j globally:

    +
      +
    • Put log4j.jar into $CATALINA_HOME/lib.
      • +
    • Replace $CATALINA_HOME/bin/tomcat-juli.jar with + tomcat-juli.jar from "extras".
      • +
    • Put tomcat-juli-adapters.jar from "extras" into + $CATALINA_HOME/lib
      • +
    +
    5. -
  5. Replace $CATALINA_HOME/bin/tomcat-juli.jar with - output/extras/tomcat-juli.jar.
    6. +

  6. 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:

    +
      +
    • Create $CATALINA_BASE/bin and + $CATALINA_BASE/lib directories if they do not exist. +
      • +
    • Put log4j.jar into $CATALINA_BASE/lib
      • +
    • Put tomcat-juli.jar from "extras" as + $CATALINA_BASE/bin/tomcat-juli.jar
      • +
    • Put tomcat-juli-adapters.jar from "extras" into + $CATALINA_BASE/lib
      • +
    • If you are running with a + security manager, you + would need to edit the + $CATALINA_BASE/conf/catalina.policy file to adjust + it to using a different copy of tomcat-juli.jar.
      • +
    +
    7. -
  7. Place output/extras/tomcat-juli-adapters.jar in - $CATALINA_HOME/lib.
    - Note, that tomcat-juli.jar and - tomcat-juli-adapters.jar go into different - directories. While the first one goes into bin, this - one goes into lib.
    8. +

  8. Delete $CATALINA_BASE/conf/logging.properties to + prevent java.util.logging generating zero length log files.

    9. -
  9. Delete $CATALINA_BASE/conf/logging.properties to - prevent java.util.logging generating zero length log files.
    10. -
  10. Start Tomcat
    11. +

  11. Start Tomcat

@@ -488,7 +527,7 @@ log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/hos individual log file, and everything else goes to the "catalina.log" log file. Each file is rolled-over once per day.

- +

You can (and should) be more picky about which packages to include in the logging. Tomcat defines loggers by Engine and Host names. @@ -497,18 +536,19 @@ log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/hos 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. - +

log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG
log4j.logger.org.apache.catalina.core=DEBUG
log4j.logger.org.apache.catalina.session=DEBUG
- Be warned a level of DEBUG will produce megabytes of logging and slow +

+ 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.

- +

Your web applications should certainly use their own log4j configuration. This is valid with the above configuration. You would place a @@ -521,20 +561,26 @@ log4j.logger.org.apache.catalina.session=DEBUG
bootstrapping guide.

-

- If you have multiple instances of Tomcat, each with a separate - $CATALINA_BASE but a shared $CATALINA_HOME then - you can configure log4j on a per instance basis by replacing references to - $CATALINA_HOME in the above instructions with - $CATALINA_BASE. Note that if you do this then you may need to - make some, or all, of the following additional changes: -

    -
  • create a $CATALINA_BASE/bin directory
    • -
  • create a $CATALINA_BASE/lib directory
    • -
  • if running with a security manager, adjust the codebase for JULI in - $CATALINA_BASE/conf/catalina.policy
    • -
-

+

Additional notes

+
    +

  • This exposes log4j libraries to the web applications through the + Common classloader. See class loading + documentation for details.

    +

    Because of that, the web applications and libraries using + Apache Commons Logging + library are likely to automatically choose log4j as the underlying + logging implementation.

    • + +

  • The java.util.logging API is still available, for + those web applications that use it directly. The + ${catalina.base}/conf/logging.properties file is still + referenced by Tomcat startup scripts.

    +

    Removal of ${catalina.base}/conf/logging.properties + file, mentioned as one of the steps, just causes + java.util.logging to fallback to the default configuration + as configured in JRE, which is to use a ConsoleHandler and do not + create any files.

    • +
-- 2.11.0