Return-Path: X-Original-To: apmail-logging-commits-archive@minotaur.apache.org Delivered-To: apmail-logging-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 42729D34A for ; Sat, 17 Nov 2012 13:12:19 +0000 (UTC) Received: (qmail 17232 invoked by uid 500); 17 Nov 2012 13:12:18 -0000 Delivered-To: apmail-logging-commits-archive@logging.apache.org Received: (qmail 17166 invoked by uid 500); 17 Nov 2012 13:12:18 -0000 Mailing-List: contact commits-help@logging.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@logging.apache.org Delivered-To: mailing list commits@logging.apache.org Received: (qmail 17047 invoked by uid 99); 17 Nov 2012 13:12:12 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 17 Nov 2012 13:12:12 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 17 Nov 2012 13:12:09 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 7FA6F23889E2; Sat, 17 Nov 2012 13:11:49 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1410726 [1/3] - in /logging/log4j/log4j2/trunk/src/site: resources/css/ xdoc/ xdoc/manual/ Date: Sat, 17 Nov 2012 13:11:47 -0000 To: commits@logging.apache.org From: ihabunek@apache.org X-Mailer: svnmailer-1.0.8-patched Message-Id: <20121117131149.7FA6F23889E2@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: ihabunek Date: Sat Nov 17 13:11:44 2012 New Revision: 1410726 URL: http://svn.apache.org/viewvc?rev=1410726&view=rev Log: Improved site styling, mostly code blocks and tables. Modified: logging/log4j/log4j2/trunk/src/site/resources/css/site.css logging/log4j/log4j2/trunk/src/site/xdoc/build.xml.vm logging/log4j/log4j2/trunk/src/site/xdoc/index.xml logging/log4j/log4j2/trunk/src/site/xdoc/manual/api.xml logging/log4j/log4j2/trunk/src/site/xdoc/manual/appenders.xml logging/log4j/log4j2/trunk/src/site/xdoc/manual/architecture.xml logging/log4j/log4j2/trunk/src/site/xdoc/manual/configuration.xml.vm logging/log4j/log4j2/trunk/src/site/xdoc/manual/eventlogging.xml logging/log4j/log4j2/trunk/src/site/xdoc/manual/extending.xml logging/log4j/log4j2/trunk/src/site/xdoc/manual/filters.xml logging/log4j/log4j2/trunk/src/site/xdoc/manual/flowtracing.xml logging/log4j/log4j2/trunk/src/site/xdoc/manual/index.xml logging/log4j/log4j2/trunk/src/site/xdoc/manual/layouts.xml.vm logging/log4j/log4j2/trunk/src/site/xdoc/manual/lookups.xml logging/log4j/log4j2/trunk/src/site/xdoc/manual/markers.xml logging/log4j/log4j2/trunk/src/site/xdoc/manual/messages.xml logging/log4j/log4j2/trunk/src/site/xdoc/manual/migration.xml logging/log4j/log4j2/trunk/src/site/xdoc/manual/plugins.xml logging/log4j/log4j2/trunk/src/site/xdoc/manual/thread-context.xml Modified: logging/log4j/log4j2/trunk/src/site/resources/css/site.css URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/resources/css/site.css?rev=1410726&r1=1410725&r2=1410726&view=diff ============================================================================== --- logging/log4j/log4j2/trunk/src/site/resources/css/site.css (original) +++ logging/log4j/log4j2/trunk/src/site/resources/css/site.css Sat Nov 17 13:11:44 2012 @@ -22,6 +22,10 @@ div.clear hr { display: none; } --------------------------------- */ li { line-height: 20px; } tt { font-family: Menlo, Monaco, "Courier New", monospace; font-size: 12px; -webkit-border-radius: 3px; -moz-border-radius: 3px; border-radius: 3px; padding: 3px 4px; color: #d14; background-color: #f7f7f9; border: 1px solid #e1e1e8; } +dt { margin: 15px 0 5px 0; font-size: 1.2em } + +.big-red { font-weight: bold; color: #D14 } +.big-green { font-weight: bold; color: green } .layout-table { width: 100%; } .sidebar { width: 250px; vertical-align: top; } Modified: logging/log4j/log4j2/trunk/src/site/xdoc/build.xml.vm URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/xdoc/build.xml.vm?rev=1410726&r1=1410725&r2=1410726&view=diff ============================================================================== --- logging/log4j/log4j2/trunk/src/site/xdoc/build.xml.vm (original) +++ logging/log4j/log4j2/trunk/src/site/xdoc/build.xml.vm Sat Nov 17 13:11:44 2012 @@ -26,13 +26,12 @@
-

- Log4j 2.x is hosted in the Apache Software Foundation's subversion repository. Details on obtaining the - most current source code can be found at - Log4j Source Repository]. - The source from the latest release may be obtained by downloading it using the instructions at - Log4j Downloads. -

+

+ Log4j 2.x is hosted in the Apache Software Foundation's subversion repository. Details on obtaining the + most current source code can be found at + Log4j Source Repository. The source from the latest release may be + obtained by downloading it using the instructions at Log4j Downloads. +

Log4j 2.x uses Maven 2 or 3 as its build tool. To build Log4j simply run "mvn install" from the root directory. @@ -43,20 +42,20 @@ To use Log4j 2 in your application make sure that both the API and Core jars are in the application's classpath. With Maven add the dependencies listed below to your pom.xml.

- - - org.apache.logging.log4j - log4j-api - ${Log4jReleaseVersion} - - - org.apache.logging.log4j - log4j-core - ${Log4jReleaseVersion} - - - ]]> +

+  
+    org.apache.logging.log4j
+    log4j-api
+    ${Log4jReleaseVersion}
+  
+  
+    org.apache.logging.log4j
+    log4j-core
+    ${Log4jReleaseVersion}
+  
+
+]]>

@@ -66,42 +65,42 @@

If there are existing components that are written to use Log4j 1.x and it is desired to have this logging routed to Log4j 2 then remove any log4j 1.x dependencies and add the following.

- - - org.apache.logging.log4j.adapters - log4j12-api - ${Log4jReleaseVersion} - - - ]]> +

+  
+    org.apache.logging.log4j.adapters
+    log4j12-api
+    ${Log4jReleaseVersion}
+  
+
+]]>

Apache Commons Logging

Commons Logging is used in many components as a way of letting applications choose the specific logging implementation. To route logging from those components into Log4j 2 include the following dependency and do not remove the Commons Logging jar.

- - - org.apache.logging.log4j.adapters - log4j-jcl - ${Log4jReleaseVersion} - - - ]]> +

+  
+    org.apache.logging.log4j.adapters
+    log4j-jcl
+    ${Log4jReleaseVersion}
+  
+
+]]>

SLF4J

SLF4J is another popular logging API that may be bound to Log4j 2 by including the following dependency along with the SLF4J dependencies.

- - - org.apache.logging.log4j.adapters - log4j-slf4j-impl - ${Log4jReleaseVersion} - - - ]]> +

+  
+    org.apache.logging.log4j.adapters
+    log4j-slf4j-impl
+    ${Log4jReleaseVersion}
+  
+
+]]>
Modified: logging/log4j/log4j2/trunk/src/site/xdoc/index.xml URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/xdoc/index.xml?rev=1410726&r1=1410725&r2=1410726&view=diff ============================================================================== --- logging/log4j/log4j2/trunk/src/site/xdoc/index.xml (original) +++ logging/log4j/log4j2/trunk/src/site/xdoc/index.xml Sat Nov 17 13:11:44 2012 @@ -24,81 +24,85 @@ -
+
-

- Log4j 2 is an upgrade to Log4j that provides significant improvements over its predecessor, Log4j - 1.x, and provides many of the improvements available in Logback while fixing some inherent problems in - Logback's architecture. -

- -

Some of the features and improvements in Log4j 2 are:

- -

API Separation

-

+

+ Apache Log4j 2 is an upgrade to Log4j that provides significant improvements over its predecessor, Log4j + 1.x, and provides many of the improvements available in Logback while fixing some inherent problems in + Logback's architecture. +

+ +

Some of the features and improvements in Log4j 2 are:

+ +
+
API Separation
+
The API for Log4j is separate from the implementation making it clear for application developers which classes and methods they can use while ensuring forward compatibility. This allows the Log4j team to improve the implementation safely and in a compatible manner. -

-

Improved Performance

-

+

+
Improved Performance
+
Log4j 2 performs faster than Log4j 1.x in critical areas and similarly to Logback under most circumstances. See Performance for more information. -

-

Support for multiple APIs

-

+

+
Support for multiple APIs
+
While the Log4j 2 API will provide the best performance, Log4j 2 provides support for the SLF4J and Commons Logging APIs. -

-

Automatic Reloading of Configurations

-

+

+
Automatic Reloading of Configurations
+
Like Logback, Log4j 2 can automatically reload its configuration upon modification. Unlike Logback, it will do so without losing log events while reconfiguration is taking place. -

-

Advanced Filtering

-

+

+
Advanced Filtering
+
Like Logback, Log4j 2 supports filtering based on context data, markers, regular expressions, and other components in the Log event. Filtering can be specified to apply to all events before being passed to Loggers or as they pass through Appenders. In addition, filters can also be associated with Loggers. Unlike Logback, you can use a common Filter class in any of these circumstances. -

-

Plugin Architecture

-

+

+
Plugin Architecture
+
Log4j uses the plugin pattern to configure components. As such, you do not need to write code to create and configure an Appender, Layout, Pattern Converter, and so on. Log4j automatically recognizes plugins and uses them when a configuration references them. -

-

Property Support

-

+

+
Property Support
+
You can reference properties in a configuration, Log4j will directly replace them, or Log4j will pass them to an underlying component that will dynamically resolve them. Properties come from values defined in the configuration file, system properties, environment variables, the ThreadContext Map, and data present in the event. Users can further customize the property providers by adding their own Lookup Plugin. -

-
+ + -
-

The Log4j 2 User's Guide is available on this site or as a downloadable - PDF -

. -
-
-

- Log4j 2 requires Java 5 but takes advantage of enhancements in Java 6 to improve performance. - Some features require optional dependencies; the documentation for these features specifies the dependencies. -

-
- -
-

- Log4j 2 is now available for testing. The API for Log4j 2 is not compatible with Log4j 1.x, however an adapter - is available to allow applications to continue to use the Log4j 1.x API. Adapters are also available for - Apache Commons Logging and SLF4J. -

+ +

+ The Log4j 2 User's Guide is available on this site or as a downloadable + PDF. +

+ + + +

+ Log4j 2 requires Java 5 but takes advantage of enhancements in Java 6 to improve performance. + Some features require optional dependencies; the documentation for these features specifies the + dependencies. +

+ + + +

+ Log4j 2 is now available for testing. The API for Log4j 2 is not compatible with Log4j 1.x, however an adapter + is available to allow applications to continue to use the Log4j 1.x API. Adapters are also available for + Apache Commons Logging and SLF4J. +

+
- Modified: logging/log4j/log4j2/trunk/src/site/xdoc/manual/api.xml URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/xdoc/manual/api.xml?rev=1410726&r1=1410725&r2=1410726&view=diff ============================================================================== --- logging/log4j/log4j2/trunk/src/site/xdoc/manual/api.xml (original) +++ logging/log4j/log4j2/trunk/src/site/xdoc/manual/api.xml Sat Nov 17 13:11:44 2012 @@ -40,7 +40,7 @@ write the "Hello, World!" message, however the message will be written only if the Logger is configured to allow informational messages.

- import org.apache.logging.log4j.LogManager; + 
import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 
 public class HelloWorld {
@@ -48,7 +48,7 @@ public class HelloWorld {
     public static void main(String[] args) {
         logger.info("Hello, World!");
     }
-}
+}

The output from the call to logger.info() will vary significantly depending on the configuration used. See the Configuration section for more details. @@ -59,15 +59,15 @@ public class HelloWorld { which requires including information about the objects being manipulated. In Log4j 1.x this could be accomplished by doing:

- if (logger.isDebugEnabled()) { + 
if (logger.isDebugEnabled()) {
     logger.debug("Logging in user " + user.getName() + " with id " + user.getId());
-}
+}

Doing this repeatedly has the effect of making the code feel like it is more about logging than the actual task at hand. In addition, it results in the logging level being checked twice; once on the call to isDebugEnabled and once on the debug method. A better alternative would be:

- logger.debug("Logging in user {} with id {}", user.getName(), user.getId()); + 
logger.debug("Logging in user {} with id {}", user.getName(), user.getId());

With the code above the logging level will only be checked once and the String construction will only occur when debug logging is enabled. Modified: logging/log4j/log4j2/trunk/src/site/xdoc/manual/appenders.xml URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/xdoc/manual/appenders.xml?rev=1410726&r1=1410725&r2=1410726&view=diff ============================================================================== --- logging/log4j/log4j2/trunk/src/site/xdoc/manual/appenders.xml (original) +++ logging/log4j/log4j2/trunk/src/site/xdoc/manual/appenders.xml Sat Nov 17 13:11:44 2012 @@ -51,7 +51,7 @@ on a separate Thread. Note that exceptions while writing to those Appenders will be hidden from the application. The AsynchAppender should be configured after the appenders it references to allow it to shut down properly.

- +
@@ -102,7 +102,7 @@

A typical AsynchAppender configuration might look like: - + 


 
   
     
@@ -119,8 +119,7 @@
       
     
   
-
-  ]]>
+]]>

@@ -129,7 +128,7 @@ As one might expect, the ConsoleAppender writes its output to either System.err or System.out with System.err being the default target. A Layout must be provided to format the LogEvent.

-
Parameter Name Type
+
@@ -168,7 +167,7 @@

A typical Console configuration might look like: - + 


 
   
     
@@ -180,15 +179,14 @@
       
     
   
-
-  ]]>
+]]>

The FailoverAppender wraps a set of appenders. If the primary Appender fails the secondary appenders will be tried in order until one succeeds or there are no more secondaries to try.

-
Parameter Name Type
+
@@ -232,7 +230,7 @@

A Failover configuration might look like: - + 


 
   
     
     
   
-
-  ]]>
+]]>

 @@ -267,7 +264,7 @@ FileAppenders from different Configurations cannot be shared, the FileManagers can be if the Manager is accessible. For example, two webapps in a servlet container can have their own configuration and safely write to the same file if Log4J is in a ClassLoader that is common to both of them.

-
Parameter Name Type
+
@@ -336,7 +333,7 @@

Here is a sample File configuration: - + 


 
   
     
@@ -350,8 +347,7 @@
       
     
   
-
-  ]]>
+]]>

 @@ -374,7 +370,7 @@ addition, configuring agent properties in the appender configuration will also cause the embedded agent to be used.

-
Parameter Name Type
+
@@ -498,7 +494,7 @@ A sample FlumeAppender configuration that is configured with a primary and a secondary agent, compresses the body, and formats the body using the RFC5424Layout: - + 

 
   
     
@@ -512,15 +508,14 @@
       
     
   
-
-  ]]>
+]]>

A sample FlumeAppender configuration that is configured with a primary and a secondary agent, compresses the body, formats the body using RFC5424Layout and passes the events to an embedded Flume Agent.

- + 

 
   
     
@@ -540,14 +535,13 @@
       
     
   
-
-   ]]>
+]]>

A sample FlumeAppender configuration that is configured with a primary and a secondary agent using Flume configuration properties, compresses the body, formats the body using RFC5424Layout and passes the events to an embedded Flume Agent.

- + 

 
   
     
@@ -585,13 +579,12 @@
       
     
   
-
-   ]]>
+]]>

The JMSQueueAppender sends the formatted log event to a JMS Queue.

-
Parameter Name Type
+
@@ -682,7 +675,7 @@

Here is a sample JMSQueueAppender configuration: - + 


 
   
     
     
   
-
-  ]]>
+]]>

The JMSTopicAppender sends the formatted log event to a JMS Topic.

-
Parameter Name Type
+
@@ -792,7 +784,7 @@

Here is a sample JMSTopicAppender configuration: - + 


 
   
     
     
   
-
-  ]]>
+]]>

 @@ -823,7 +814,7 @@ The RewriteAppender must be configured with a RewritePolicy. The RewriteAppender should be configured after any Appenders it references to allow it to shut down properly.

-
Parameter Name Type
+
@@ -870,7 +861,7 @@ MapRewritePolicy will evaluate LogEvents that contain a MapMessage and will add or update elements of the Map.

-
Parameter Name Type
+
@@ -891,7 +882,7 @@ The following configuration shows a RewriteAppender configured to add a product key and its value to the MapMessage.: - + 

 
   
     
@@ -909,8 +900,7 @@
       
     
   
-
-  ]]>
+]]>

PropertiesRewritePolicy

@@ -919,7 +909,7 @@ values may contain variables that will be evaluated when the configuration is processed as well as when the event is logged.

-
Parameter Name Type
+
@@ -935,7 +925,7 @@ The following configuration shows a RewriteAppender configured to add a product key and its value to the MapMessage.: - + 

 
   
     
@@ -954,8 +944,7 @@
       
     
   
-
-  ]]>
+]]>

@@ -976,7 +965,7 @@

File locking is not supported by the RollingFileAppender.

-
Parameter Name Type
+
@@ -1078,7 +1067,7 @@ accepts an "increment" attribute which indicates how frequently the rollover should occur based on the time pattern and a "modulate" boolean attribute.

-
Parameter Name Type
+
@@ -1119,7 +1108,7 @@

The Default rollover strategy also accepts a minimum value and a maximum value. When a minimim value other than 1 is specified than files with an index lower than that value will not be deleted when the maximum value is exceeded.

-
Parameter Name Type
+
@@ -1144,7 +1133,7 @@ based on the current year and month, and will compress each archive using gzip: - + 

 
   
     
     
   
-
-  ]]>
+]]>

This second example shows a rollover strategy that will keep up to 20 files before removing them. - + 


 
   
     
     
   
-
-  ]]>
+]]>

Below is a sample configuration that uses a RollingFileAppender with both the time and size based @@ -1197,7 +1184,7 @@ based on the current year and month, and will compress each archive using gzip and will roll every 6 hours when the hour is divisible by 6: - + 


 
   
     
     
   
-
-  ]]>
+]]>

 @@ -1228,7 +1214,7 @@ Appender can be dynamically created as needed. The RoutingAppender should be configured after any Appenders it references to allow it to shut down properly.

-
Parameter Name Type
+
@@ -1283,7 +1269,7 @@ the specific event type. Note that the AuditAppender was predefined while the RollingFileAppenders are created as needed. - + 

 
   
     
@@ -1311,8 +1297,7 @@
       
     
   
-
-  ]]>
+]]>

 @@ -1323,7 +1308,7 @@ The default format is to send a Serialized LogEvent. Log4j 2 contains a SocketServer which is capable of receiving serialized LogEvents and routing them through the logging system on the server.

-
Parameter Name Type
+
@@ -1383,7 +1368,7 @@
Parameter Name Type
SocketAppender Parameters
- + 

 
   
     
@@ -1395,8 +1380,7 @@
       
     
   
-
-  ]]>
+]]>
 @@ -1405,7 +1389,7 @@ specified by a host and port in a format that conforms with either the BSD Syslog format or the RFC 5424 format. The data can be sent over either TCP or UDP.

- +
@@ -1546,7 +1530,7 @@ A sample syslogAppender configuration that is configured with two SyslogAppenders, one using the BSD format and one using RFC 5424. - + 

 
   
     
@@ -1563,8 +1547,7 @@
       
     
   
-
-  ]]>
+]]>

Modified: logging/log4j/log4j2/trunk/src/site/xdoc/manual/architecture.xml URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/xdoc/manual/architecture.xml?rev=1410726&r1=1410725&r2=1410726&view=diff ============================================================================== --- logging/log4j/log4j2/trunk/src/site/xdoc/manual/architecture.xml (original) +++ logging/log4j/log4j2/trunk/src/site/xdoc/manual/architecture.xml Sat Nov 17 13:11:44 2012 @@ -26,7 +26,7 @@

Log4j uses the classes shown in the diagram below.

-

Applications using the Log4j 2 API will request a Logger with a specific name from the LogManager. The LogManager will locate the appropriate LoggerContext and then obtain the Logger from it. @@ -53,32 +53,17 @@ they follow the hierarchical naming rule:

-

-

Parameter Name Type
- - - -
-
-
- Named Hierarchy -
- -
A LoggerConfig is said to be an - ancestor - of another - LoggerConfig if its name followed by a dot is a prefix of the - descendant - logger name. A LoggerConfig is said to be a - parent - of a - child - LoggerConfig if there are no - ancestors between itself and the descendant LoggerConfig. -
-
-
-

+
+
+
Named Hierarchy
+
+ A LoggerConfig is said to be an ancestor of another LoggerConfig if its name followed by a dot + is a prefix of the descendant logger name. A LoggerConfig is said to be a parent of a + child LoggerConfig if there are no ancestors between itself and the descendant LoggerConfig. +
+
+
+

For example, the LoggerConfig named "com.foo" is a parent @@ -94,7 +79,7 @@

The root LoggerConfig resides at the top of the LoggerConfig hierarchy. It is exceptional in that it always exists and it is part of every hierarchy. A Logger that is directly linked to the root LoggerConfig can be obtained as follows: - Logger logger = LogManager.getLogger(LogManager.ROOT_LOGGER_NAME); + 

Logger logger = LogManager.getLogger(LogManager.ROOT_LOGGER_NAME);
All other Loggers can be retrieved using the LogManager.getLogger @@ -130,22 +115,17 @@ and implements the required methods. As the configuration is modified Loggers may become associated with a different LoggerConfig, thus causing their behavior to be modified.

- - - - -
Retrieving Loggers
-

Calling the - getLogger - method with the same name will - always return a reference to the exact same Logger object. +

Retrieving Loggers
+

+ Calling the getLogger method with the same name will always return a reference to the exact + same Logger object.

For example, in - - Logger x = Logger.getLogger("wombat"); - Logger y = Logger.getLogger("wombat"); - +

+Logger x = Logger.getLogger("wombat");
+Logger y = Logger.getLogger("wombat");
+
x and y refer to exactly the same Logger object.

@@ -176,11 +156,7 @@ passed to any Appenders. It contains references to the set of Appenders that should be used to process the event.

- - - - -
Log Levels
+
Log Levels

LoggerConfigs will be assigned a Log Level. The set of possible levels includes (TRACE, DEBUG, INFO, WARN, ERROR and FATAL). Note that in Log4j 2, the Level is @@ -201,28 +177,28 @@ is not configured a default Level will be assigned to it.

- +
- + - + - + - + - + @@ -234,28 +210,28 @@ Loggers reference the root LoggerConfig and use its Level.

-
Logger Name Assigned LoggerConfiglevelLevel
root root DEBUG
X root DEBUG
X.Y root DEBUG
X.Y.Z root DEBUG
+
- + - + - + - + - + @@ -267,28 +243,28 @@ from it.

-
Logger Name Assigned LoggerConfiglevelLevel
root root DEBUG
X X ERROR
X.Y X.Y INFO
X.Y.Z X.Y.Z WARN
+
- + - + - + - + - + @@ -309,28 +285,28 @@ name has the longest match to the start of the Logger's name.

-
Logger Name Assigned LoggerConfiglevelLevel
root root DEBUG
X X ERROR
X.Y X ERROR
X.Y.Z X.Y.Z WARN
+
- + - + - + - + @@ -352,28 +328,28 @@ longest match to the start of the Logger's name.

-
Logger Name Assigned LoggerConfig level
root root DEBUG
X X ERROR
X.Y X ERROR
X.Y.Z X ERROR
+
- + - + - + - + @@ -397,224 +373,216 @@ with the appopriate LoggerConfig. The intersection identifies whether the LogEvent would be allowed to pass for further processing (Yes) or discarded (No).

-
Logger Name Assigned LoggerConfig level
root root DEBUG
X X ERROR
X.Y X.Y INFO
X.YZ X ERROR
+
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Event LevelLoggerConfig Level
 TRACEDEBUGINFOWARNERRORFATAL
ALLNONONONONONO
TRACEYESNONONONONO
DEBUGYESYESNONONONO
INFOYESYESYESNONONO
WARNYESYESYESYESNONO
ERRORYESYESYESYESYESNO
FATALYESYESYESYESYESYES
OFFYESYESYESYESYESYESEvent LevelLoggerConfig Level
 TRACEDEBUGINFOWARNERRORFATAL
ALLNONONONONONO
TRACEYESNONONONONO
DEBUGYESYESNONONONO
INFOYESYESYESNONONO
WARNYESYESYESYESNONO
ERRORYESYESYESYESYESNO
FATALYESYESYESYESYESYES
OFFYESYESYESYESYESYES

Filter

-

In addition to the automatic log Level filtering that takes place as described in the previous - section, Log4j provides - Filters that can - be applied before control is passed to any LoggerConfig, after control is passed to a LoggerConfig - but before calling any Appenders, after control is passed to a LoggerConfig but before calling a - specific Appender, and on each Appender. In a manner very similar to firewall filters, - each Filter can return one of three results, Accept, Deny or Neutral. A response of Accept means - that no other Filters should be called and the event should progress. A response of Deny means - the event should be immediately ignored and control should be returned to the caller. A response - of Neutral indicates the event should be passed to other Filters. If there are no other Fitlers the - event will be processed. -

-

Although an event may be accepted by a Filter the event still might not be logged. This can happen - when the event is accepted by the pre-LoggerConfig Filter but is then denied by a LoggerConfig - filter or is denied by all Appenders. -

+

In addition to the automatic log Level filtering that takes place as described in the previous + section, Log4j provides + Filters that can + be applied before control is passed to any LoggerConfig, after control is passed to a LoggerConfig + but before calling any Appenders, after control is passed to a LoggerConfig but before calling a + specific Appender, and on each Appender. In a manner very similar to firewall filters, + each Filter can return one of three results, Accept, Deny or Neutral. A response of Accept means + that no other Filters should be called and the event should progress. A response of Deny means + the event should be immediately ignored and control should be returned to the caller. A response + of Neutral indicates the event should be passed to other Filters. If there are no other Fitlers the + event will be processed. +

+

Although an event may be accepted by a Filter the event still might not be logged. This can happen + when the event is accepted by the pre-LoggerConfig Filter but is then denied by a LoggerConfig + filter or is denied by all Appenders. +

+

Appender

-

The ability to selectively enable or disable logging requests based - on their logger is only part of the picture. Log4j allows logging - requests to print to multiple destinations. In log4j speak, an output - destination is called an - Appender. - Currently, appenders exist for the console, files, remote socket servers, Apache Flume, - JMS, and remote UNIX Syslog daemons. More than one Appender can be attached to a Logger. -

-

An Appender can be added to a Logger by calling the - addLoggerAppender - method of the current Configuration. If a LoggerConfig matching the name of the Logger does - not exist, one will be created, the Appender will be attached to it and then all Loggers - will be notified to update their LoggerConfig references. -

-

Each enabled logging request for a given logger will be forwarded to all the appenders in - that Logger's LoggerConfig as well as the Appenders of the LoggerConfig's parents. In - other words, Appenders are inherited additively from the LoggerConfig hierarchy. For example, - if a console appender is added to the root logger, then all enabled logging requests will at - least print on the console. If in addition a file appender is added to a LoggerConfig, say - C, then enabled logging requests for C and C's children will print - in a file and on the console. It is possible to override this default behavior so that - Appender accumulation is no longer additive by setting additivity="false" on the - Logger declaration in the configuration file. -

-

The rules governing appender additivity are summarized below.

- -

- - - - - -
-
-
Appender Additivity
- -
-

The output of a log statement of Logger L will - go to all the Appenders in the LoggerConfig associated with L - and the ancestors of that LoggerConfig. This is the meaning of the term "appender additivity". -

- -

However, if an ancestor of the LoggerConfig associated with Logger L, say P, - has the additivity flag set to false, then L's output will be - directed to all the appenders in L's LoggerConfig and it's ancestors up to - and including P but not the Appenders in any of the ancestors of P. -

- -

Loggers have their additivity flag set to true by default.

-
-
-
-

- -

The table below shows an example:

- -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Logger
Name 		Added
Appenders		Additivity
Flag		Output TargetsComment
rootA1not applicableA1The root logger has no parent so additivity does not apply to it.
xA-x1, A-x2true A1, A-x1, A-x2Appenders of "x" and root.
x.ynonetrue A1, A-x1, A-x2Appenders of "x" and root. It would not be typical to configure a Logger with no Appenders.
x.y.zA-xyz1true A1, A-x1, A-x2, A-xyz1Appenders in "x.y.z", "x" and root.
securityA-secfalseA-secNo appender accumulation since the additivity flag is set to false.
security.accessnonetrueA-secOnly appenders of "security" because the additivity flag in "security" is - set to false. -
-

+ +

The ability to selectively enable or disable logging requests based + on their logger is only part of the picture. Log4j allows logging + requests to print to multiple destinations. In log4j speak, an output + destination is called an + Appender. + Currently, appenders exist for the console, files, remote socket servers, Apache Flume, + JMS, and remote UNIX Syslog daemons. More than one Appender can be attached to a Logger. +

+

An Appender can be added to a Logger by calling the + addLoggerAppender + method of the current Configuration. If a LoggerConfig matching the name of the Logger does + not exist, one will be created, the Appender will be attached to it and then all Loggers + will be notified to update their LoggerConfig references. +

+

Each enabled logging request for a given logger will be forwarded to all the appenders in + that Logger's LoggerConfig as well as the Appenders of the LoggerConfig's parents. In + other words, Appenders are inherited additively from the LoggerConfig hierarchy. For example, + if a console appender is added to the root logger, then all enabled logging requests will at + least print on the console. If in addition a file appender is added to a LoggerConfig, say + C, then enabled logging requests for C and C's children will print + in a file and on the console. It is possible to override this default behavior so that + Appender accumulation is no longer additive by setting additivity="false" on the + Logger declaration in the configuration file. +

+

The rules governing appender additivity are summarized below.

+ +
+
+
Appender Additivity
+
+

+ The output of a log statement of Logger L will go to all the Appenders in the LoggerConfig + associated with L and the ancestors of that LoggerConfig. This is the meaning of the term + "appender additivity". +

+

+ However, if an ancestor of the LoggerConfig associated with Logger L, say P, has the + additivity flag set to false, then L's output will be directed to all the + appenders in L's LoggerConfig and it's ancestors up to and including P but not the + Appenders in any of the ancestors of P. +

+

Loggers have their additivity flag set to true by default.

+
+
+
+ +

The table below shows an example:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Logger
Name 		Added
Appenders		Additivity
Flag		Output TargetsComment
rootA1not applicableA1The root logger has no parent so additivity does not apply to it.
xA-x1, A-x2true A1, A-x1, A-x2Appenders of "x" and root.
x.ynonetrue A1, A-x1, A-x2Appenders of "x" and root. It would not be typical to configure a Logger with no Appenders.
x.y.zA-xyz1true A1, A-x1, A-x2, A-xyz1Appenders in "x.y.z", "x" and root.
securityA-secfalseA-secNo appender accumulation since the additivity flag is set to false.
security.accessnonetrueA-secOnly appenders of "security" because the additivity flag in "security" is + set to false. +
+

Layout

More often than not, users wish to customize not only the output destination but also the output format. This is accomplished by associating a @@ -628,7 +596,7 @@

For example, the PatternLayout with the conversion pattern "%r [%t] %-5p %c - %m%n" will output something akin to:
- 176 [main] INFO org.foo.Bar - Located nearest gas station. + 

176 [main] INFO  org.foo.Bar - Located nearest gas station.

The first field is the number of milliseconds elapsed since the