logging-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rgo...@apache.org
Subject svn commit: r1206410 - in /logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers: log4j2-core/src/main/java/org/apache/logging/log4j/core/config/ src/site/ src/site/xdoc/manual/
Date Sat, 26 Nov 2011 08:32:56 GMT
Author: rgoers
Date: Sat Nov 26 08:32:55 2011
New Revision: 1206410

URL: http://svn.apache.org/viewvc?rev=1206410&view=rev
Log:
More configuration documentation. Check file configuration when filtering

Modified:
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/FileConfigurationMonitor.java
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/LoggerConfig.java
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/configuration.xml

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/FileConfigurationMonitor.java
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/FileConfigurationMonitor.java?rev=1206410&r1=1206409&r2=1206410&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/FileConfigurationMonitor.java
(original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/FileConfigurationMonitor.java
Sat Nov 26 08:32:55 2011
@@ -60,8 +60,8 @@ public class FileConfigurationMonitor im
      */
     public void checkConfiguration() {
         if ((++counter & MASK) == 0) {
-            long current = System.currentTimeMillis();
             synchronized(this) {
+                long current = System.currentTimeMillis();
                 if (current >= nextCheck) {
                     nextCheck = current + interval;
                     if (lastModified >= file.lastModified()) {

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/LoggerConfig.java
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/LoggerConfig.java?rev=1206410&r1=1206409&r2=1206410&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/LoggerConfig.java
(original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/LoggerConfig.java
Sat Nov 26 08:32:55 2011
@@ -89,6 +89,12 @@ public class LoggerConfig extends Filter
         this.additive = additive;
     }
 
+    @Override
+    public Filter getFilter() {
+        monitor.checkConfiguration();
+        return super.getFilter();
+    }
+
     /**
      * Set the ConfigurationMonitor that will detect configuration changes.
      * @param monitor The ConfigurationMonitor.

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml?rev=1206410&r1=1206409&r2=1206410&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml Sat Nov 26 08:32:55
2011
@@ -43,7 +43,15 @@
     <menu name="Manual" inherit="top">
       <item name="Introduction" href="/manual/index.html"/>
       <item name="Architecture" href="/manual/architecture.html"/>
-      <item name="Configuration" href="/manual/configuration.html"/>
+      <item name="Configuration" href="/manual/configuration.html" collapse="true">
+        <item name="Automatic Configuration" href="/manual/configuration.html#AutomaticConfiguration"/>
+        <item name="Additivity" href="/manual/configuration.html#Additvity"/>
+        <item name="Automatic Reconfiguration" href="/manual/configuration.html#AutomaticReconfiguration"/>
+        <item name="Configuration Syntax" href="/manual/configuration.html#ConfigurationSyntax"/>
+        <item name="Property Substitution" href="/manual/configuration.html#PropertySubstitution"/>
+        <item name="Status Messages" href="/manual/configuration.html#StatusMessages"/>
+        <item name="Unit Testing in Maven" href="/manual/configuration.html#UnitTestingInMaven"/>
+      </item>
       <item name="Plugins" href="/manual/plugins.html" collapse="true">
         <item name="Core" href="/manual/plugins.html#Core"/>
         <item name="Converters" href="/manual/plugins.html#Converters"/>

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/configuration.xml
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/configuration.xml?rev=1206410&r1=1206409&r2=1206410&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/configuration.xml
(original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/configuration.xml
Sat Nov 26 08:32:55 2011
@@ -47,6 +47,7 @@
           Note that unlike Log4j 1.x, the public Log4j 2 API does not expose methods to add,
modify or remove
           appenders and filters or manipulate the configuration in any way.
         </p>
+        <a name="AutomaticConfiguration"/>
         <subsection name="Automatic Configuration">
           <p>
             Log4j has the ability to automatically configure itself during initialization.
@@ -90,21 +91,20 @@
 
    logger.trace("Entering application.");
    Bar bar = new Bar();
-   bar.doIt();
+   if (!bar.doIt() {
+     logger.error("Didn't do it.");
+   }
    logger.trace("Exiting application."                 }
  }</source>
           </p>
-
           <p>
             <code>MyApp</code> begins by importing log4j related classes. It
             then defines a static logger variable with the name <code>MyApp</code>
             which happens to be the fully qualified name of the class.
           </p>
-
           <p>
             <code>MyApp</code> uses the <code>Bar</code> class defined
in the package<code>com.foo</code>.
           </p>
-
           <p>
 <source>  package com.foo;
   import org.apache.logging.log4j.Logger;
@@ -112,26 +112,29 @@
   public class Bar {
     static Logger logger = LogManager.getLogger(Bar.class.getName());
 
-    public void doIt() {
+    public boolean doIt() {
+      logger.entry();
       logger.error("Did it again!");
+      logger.exit();
+      return false;
     }
   }</source>
           </p>
-
           <p>
             If no configuration files are present logback will default to the DefaultConfiguration
which
-            will set up a minimal logging environment consisting of a <a href="">ConsoleAppender</a>
attached
-            to the root logger. The output will be formatted using a
-            <a href="">PatternLayout</a> set to the pattern "%d{HH:mm:ss.SSS}
[%t] %-5level %logger{36} - %msg%n".
+            will set up a minimal logging environment consisting of a
+            <a href="../log4j2-core/apidocs/org/apache/logging/log4j/core/appender/ConsoleAppender.html">ConsoleAppender</a>
+            attached to the root logger. The output will be formatted using a
+            <a href="../log4j2-core/apidocs/org/apache/logging/log4j/core/layout/PatternLayout.html">PatternLayout</a>
+            set to the pattern "%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n".
           </p>
-
           <p>
             Note that by default, the root logger is assigned to <code>Level.ERROR</code>.
           </p>
-
           <p>The output of MyApp would be similar to:
             <pre>
   17:13:01.540 [main] ERROR com.foo.Bar - Did it again!
+  17:13:01.540 [main] ERROR MyApp - Didn't do it.
             </pre>
           </p>
           <p>
@@ -152,34 +155,232 @@
 </configuration>]]></source>
             Once the file above is placed into the classpath as log4j.xml you will get results
identical to
             those listed above. Changing the root level to trace will result in results similar
to:
-             <pre>
+             <source>
   17:13:01.540 [main] TRACE MyApp - Entering application.
+  17:13:01.540 [main] TRACE com.foo.Bar - entry
   17:13:01.540 [main] ERROR com.foo.Bar - Did it again!
-  17:13:01.540 [main] TRACE MyApp - Exiting application.</pre>
+  17:13:01.540 [main] TRACE com.foo.Bar - exit
+  17:13:01.540 [main] ERROR MyApp - Didn't do it.
+  17:13:01.540 [main] TRACE MyApp - Exiting application.</source>
+          </p>
+          <p>
+            Note that status logging is disabled when the default configuration is used.
           </p>
           <p>
-            Note that status logging is disabled using the default configuration.
+            Perhaps it is desired to eliminate all the TRACE output from everything except
com.foo.BAR. Simply
+            changing the log level would not accomplish the task. Instead, the solution is
to
+            add a new logger definition to the configuration:
+          </p>
+            <source><![CDATA[    <logger name="com.foo.Bar" level="TRACE"/>
+    <root level="ERROR">
+      <appender-ref ref="STDOUT">
+    </root>]]></source>
+          <p>
+            With this configuration all log events from com.foo.Bar will be recorded while
only error events will
+            be recorded from all other components.
           </p>
         </subsection>
-
+        <a name="Additivity"/>
+        <subsection name="Additivity">
+          <p>
+            In the previous example all the events from com.foo.Bar were still written to
the Console. This is
+            because the logger for com.foo.Bar did not have any appenders configured while
its parent did. In fact,
+            the following configuration
+          </p>
+          <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="OFF">
+  <appenders>
+    <Console name="Console" target="SYSTEM_OUT">
+      <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
+    </Console>
+  </appenders>
+  <loggers>
+    <logger name="com.foo.Bar" level="trace">
+      <appender-ref ref="Console"/>
+    </logger>
+    <root level="error">
+      <appender-ref ref="Console"/>
+    </root>
+  </loggers>
+</configuration>]]></source>
+          <p>would result in</p>
+             <source>
+  17:13:01.540 [main] TRACE com.foo.Bar - entry
+  17:13:01.540 [main] TRACE com.foo.Bar - entry
+  17:13:01.540 [main] ERROR com.foo.Bar - Did it again!
+  17:13:01.540 [main] TRACE com.foo.Bar - exit
+  17:13:01.540 [main] TRACE com.foo.Bar - exit
+  17:13:01.540 [main] ERROR MyApp - Didn't do it.</source>
+          <p>Notice that the trace messages from com.foo.Bar appear twice. This is
because the appender associated
+            with logger com.foo.Bar is first used, which writes the first instance to the
Console. Next, the parent
+            of com.foo.Bar, which in this case is the root logger, is referenced. The event
is then passed to its
+            appender, which is also writes to the Console, resulting in the second instance.
This is known as
+            additivity. While additivity can be quite a convenient feature (as in the first
previous example where
+            no appender reference needed to be configured), in many cases this behavior is
considered undesirable
+            and so it is possible to disable it by setting the additivity attribute on the
logger to false:
+          </p>
+           <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="OFF">
+  <appenders>
+    <Console name="Console" target="SYSTEM_OUT">
+      <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
+    </Console>
+  </appenders>
+  <loggers>
+    <logger name="com.foo.Bar" level="trace" additivity="false">
+      <appender-ref ref="Console"/>
+    </logger>
+    <root level="error">
+      <appender-ref ref="Console"/>
+    </root>
+  </loggers>
+</configuration>]]></source>
+          <p>
+            Once an event reaches a logger with its additivity set to false the event will
not be passed to
+            any of its parent loggers, regardless of their additivity setting.
+          </p>
+        </subsection>
+        <a name="AutomaticReconfiguration"/>
         <subsection name="Automatic Reconfiguration">
-
+          <p>
+            When configured from a File, Log4j has the ability to automatically detect changes
to the configuration
+            file and reconfigure itself. If the monitorInterval attribute is specified on
the configuration element
+            and is set to a non-zero value then the file will be checked the next time a
log event is evaluated
+            and/or logged and the monitorInterval has elapsed since the last check.
+          </p>
         </subsection>
-
+        <a name="ConfigurationSyntax"/>
         <subsection name="Configuration Syntax">
 
         </subsection>
-
+        <a name="PropertySubstitution"/>
         <subsection name="Property Substitution">
 
         </subsection>
+        <a name="StatusMessages"/>
+        <subsection name="Status Messages">
+          <p>
+            Just as it is desirable to be able to diagnose problems in applications, it is
frequently necessary
+            to be able to diagnose problems in the logging configuration or in the configured
components. Since
+            logging has not been configured, "normal" logging cannot be used during initialization.
In addition,
+            normal logging within appenders could create infinite recursion which Log4j will
detect and cause
+            the recursive events to be ignored. To accomodate this need, the Log4j 2 API
includes a
+            <a href="../log4j2-api/apidocs/org/apache/logging/log4j/status/StatusLogger.html">StatusLogger</a>.
+            Components declare an instance of the StatusLogger similar to</p>
+<source>
+  protected final static Logger logger = StatusLogger.getLogger();</source>
+          <p>
+            Since StatusLogger implements the Log4j 2 API's Logger interface, all the normal
Logger methods may
+            be used.
+          </p>
+          <p>
+            When configuring Log4j it is sometimes necessary to view the generated status
events. This can be
+            accomplished by adding the status attribute to the configuration element. The
following
+            configuration has the status attribute set to debug.
+
+<source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>;
+<configuration status="debug" name="RoutingTest" packages="org.apache.logging.log4j.test">
+  <properties>
+    <property name="filename">target/rolling1/rollingtest-$${sd:type}.log</property>
+  </properties>
+  <ThresholdFilter level="debug"/>
 
+  <appenders>
+    <Console name="STDOUT">
+      <PatternLayout pattern="%m%n"/>
+    </Console>
+    <List name="List">
+      <ThresholdFilter level="debug"/>
+    </List>
+    <Routing name="Routing">
+      <Routes pattern="$${sd:type}">
+        <Route>
+          <RollingFile name="Rolling-${sd:type}" fileName="${filename}"
+                       filePattern="target/rolling1/test1-${sd:type}.%i.log.gz">
+            <PatternLayout>
+              <pattern>%d %p %C{1.} [%t] %m%n</pattern>
+            </PatternLayout>
+            <SizeBasedTriggeringPolicy size="500" />
+          </RollingFile>
+        </Route>
+        <Route appender-ref="STDOUT" key="Audit"/>
+        <Route appender-ref="List" key="Service"/>
+      </Routes>
+    </Routing>
+  </appenders>
 
-        <subsection name="Status Messages">
+  <loggers>
+    <logger name="EventLogger" level="info" additivity="false">
+      <appender-ref ref="Routing"/>
+    </logger>
+
+    <root level="error">
+      <appender-ref ref="STDOUT"/>
+    </root>
+  </loggers>
 
+</configuration>]]></source>
+            During startup this configuration produces:
+<source>
+  2011-11-23 17:08:00,769 DEBUG Generated plugins in 0.003374000 seconds
+  2011-11-23 17:08:00,789 DEBUG Calling createProperty on class org.apache.logging.log4j.core.config.Property
for element property with params(name="filename", value="target/rolling1/rollingtest-${sd:type}.log")
+  2011-11-23 17:08:00,792 DEBUG Calling configureSubstitutor on class org.apache.logging.log4j.core.config.plugins.PropertiesPlugin
for element properties with params(properties={filename=target/rolling1/rollingtest-${sd:type}.log})
+  2011-11-23 17:08:00,794 DEBUG Generated plugins in 0.001362000 seconds
+  2011-11-23 17:08:00,797 DEBUG Calling createFilter on class org.apache.logging.log4j.core.filter.ThresholdFilter
for element ThresholdFilter with params(level="debug", onMatch="null", onMismatch="null")
+  2011-11-23 17:08:00,800 DEBUG Calling createLayout on class org.apache.logging.log4j.core.layout.PatternLayout
for element PatternLayout with params(pattern="%m%n", Configuration(RoutingTest), null, charset="null")
+  2011-11-23 17:08:00,802 DEBUG Generated plugins in 0.001349000 seconds
+  2011-11-23 17:08:00,804 DEBUG Calling createAppender on class org.apache.logging.log4j.core.appender.ConsoleAppender
for element Console with params(PatternLayout(%m%n), null, target="null", name="STDOUT", suppressExceptions="null")
+  2011-11-23 17:08:00,804 DEBUG Calling createFilter on class org.apache.logging.log4j.core.filter.ThresholdFilter
for element ThresholdFilter with params(level="debug", onMatch="null", onMismatch="null")
+  2011-11-23 17:08:00,806 DEBUG Calling createAppender on class org.apache.logging.log4j.test.appender.ListAppender
for element List with params(name="List", entryPerNewLine="null", raw="null", null, ThresholdFilter(DEBUG))
+  2011-11-23 17:08:00,813 DEBUG Calling createRoute on class org.apache.logging.log4j.core.appender.routing.Route
for element Route with params(appender-ref="null", key="null", Node=Route)
+  2011-11-23 17:08:00,823 DEBUG Calling createRoute on class org.apache.logging.log4j.core.appender.routing.Route
for element Route with params(appender-ref="STDOUT", key="Audit", Node=Route)
+  2011-11-23 17:08:00,824 DEBUG Calling createRoute on class org.apache.logging.log4j.core.appender.routing.Route
for element Route with params(appender-ref="List", key="Service", Node=Route)
+  2011-11-23 17:08:00,825 DEBUG Calling createRoutes on class org.apache.logging.log4j.core.appender.routing.Routes
for element Routes with params(pattern="${sd:type}", routes={Route(type=dynamic default),
Route(type=static Reference=STDOUT key='Audit'), Route(type=static Reference=List key='Service')})
+  2011-11-23 17:08:00,827 DEBUG Calling createAppender on class org.apache.logging.log4j.core.appender.routing.RoutingAppender
for element Routing with params(name="Routing", suppressExceptions="null", Routes({Route(type=dynamic
default),Route(type=static Reference=STDOUT key='Audit'),Route(type=static Reference=List
key='Service')}), Configuration(RoutingTest), null, null)
+  2011-11-23 17:08:00,827 DEBUG Calling createAppenders on class org.apache.logging.log4j.core.config.plugins.AppendersPlugin
for element appenders with params(appenders={STDOUT, List, Routing})
+  2011-11-23 17:08:00,828 DEBUG Calling createAppenderRef on class org.apache.logging.log4j.core.config.plugins.AppenderRefPlugin
for element appender-ref with params(ref="Routing")
+  2011-11-23 17:08:00,829 DEBUG Calling createLogger on class org.apache.logging.log4j.core.config.LoggerConfig
for element logger with params(additivity="false", level="info", name="EventLogger", appender-ref={Routing},
null)
+  2011-11-23 17:08:00,830 DEBUG Calling createAppenderRef on class org.apache.logging.log4j.core.config.plugins.AppenderRefPlugin
for element appender-ref with params(ref="STDOUT")
+  2011-11-23 17:08:00,831 DEBUG Calling createLogger on class org.apache.logging.log4j.core.config.LoggerConfig$RootLogger
for element root with params(additivity="null", level="error", appender-ref={STDOUT}, null)
+  2011-11-23 17:08:00,833 DEBUG Calling createLoggers on class org.apache.logging.log4j.core.config.plugins.LoggersPlugin
for element loggers with params(loggers={EventLogger, root})
+  2011-11-23 17:08:00,834 DEBUG Reconfiguration completed
+  2011-11-23 17:08:00,846 DEBUG Calling createLayout on class org.apache.logging.log4j.core.layout.PatternLayout
for element PatternLayout with params(pattern="%d %p %C{1.} [%t] %m%n", Configuration(RoutingTest),
null, charset="null")
+  2011-11-23 17:08:00,849 DEBUG Calling createPolicy on class org.apache.logging.log4j.core.appender.rolling.SizeBasedTriggeringPolicy
for element SizeBasedTriggeringPolicy with params(size="500")
+  2011-11-23 17:08:00,851 DEBUG Calling createAppender on class org.apache.logging.log4j.core.appender.RollingFileAppender
for element RollingFile with params(fileName="target/rolling1/rollingtest-Unknown.log", filePattern="target/rolling1/test1-Unknown.%i.log.gz",
append="null", name="Rolling-Unknown", bufferedIO="null", immediateFlush="null", SizeBasedTriggeringPolicy(SizeBasedTriggeringPolicy(size=500)),
null, PatternLayout(%d %p %C{1.} [%t] %m%n), null, suppressExceptions="null")
+  2011-11-23 17:08:00,858 DEBUG Generated plugins in 0.002014000 seconds
+  2011-11-23 17:08:00,889 DEBUG Reconfiguration started for context sun.misc.Launcher$AppClassLoader@37b90b39
+  2011-11-23 17:08:00,890 DEBUG Generated plugins in 0.001355000 seconds
+  2011-11-23 17:08:00,959 DEBUG Generated plugins in 0.001239000 seconds
+  2011-11-23 17:08:00,961 DEBUG Generated plugins in 0.001197000 seconds
+  2011-11-23 17:08:00,965 WARN No Loggers were configured, using default
+  2011-11-23 17:08:00,976 DEBUG Reconfiguration completed</source>
+          </p>
+          <p>
+            If the status attribute is set to error than only error messages will be written
to the console. This
+            makes troubleshooting configuration errors possible. As an example, if the configuration
above is changed
+            to have the status set to error and the logger declaration is:</p>
+<source><![CDATA[  <logger name="EventLogger" level="info" additivity="false">
+    <appender-ref ref="Routng"/>
+  </logger>]]></source>
+          <p>
+            the following error message will be produced.
+<source>
+ 2011-11-24 23:21:25,517 ERROR Unable to locate appender Routng for logger EventLogger</source>
+          </p>
+          <p>
+            Applications may wish to direct the status output to some other destination.
This can be accomplished
+            by insuring the configured status is set to OFF and then configuring the application
programmatically
+            such as:
+<source>
+  StatusConsoleListener listener = new StatusConsoleListener(Level.ERROR);
+  ((StatusLogger) logger).registerListener(listener);
+</source>
+          </p>
         </subsection>
+        <a name="UnitTestingInMaven"/>
         <subsection name="Unit Testing in Maven">
 
+
         </subsection>
       </section>
     </body>



Mime
View raw message