You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by ih...@apache.org on 2012/11/17 14:11:47 UTC
svn commit: r1410726 [1/3] - in /logging/log4j/log4j2/trunk/src/site:
resources/css/ xdoc/ xdoc/manual/
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 @@
<section name="Building and Installing Log4j 2.x">
<subsection name="Building">
- <p>
- 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
- <a href="http://logging.apache.org/log4j/2.x/source-repository.html">Log4j Source Repository]</a>.
- The source from the latest release may be obtained by downloading it using the instructions at
- <a href="http://logging.apache.org/log4j/2.x/download.html">Log4j Downloads</a>.
- </p>
+ <p>
+ 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
+ <a href="./source-repository.html">Log4j Source Repository</a>. The source from the latest release may be
+ obtained by downloading it using the instructions at <a href="./download.html">Log4j Downloads</a>.
+ </p>
<p>
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.
</p>
- <source><![CDATA[
- <dependencies>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-api</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-core</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- </dependecies>
- ]]></source>
+<pre class="prettyprint linenums"><![CDATA[
+<dependencies>
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-api</artifactId>
+ <version>${Log4jReleaseVersion}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-core</artifactId>
+ <version>${Log4jReleaseVersion}</version>
+ </dependency>
+</dependecies>
+]]></pre>
</subsection>
<subsection name="Optional Components">
<p>
@@ -66,42 +65,42 @@
<p>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.
</p>
- <source><![CDATA[
- <dependencies>
- <dependency>
- <groupId>org.apache.logging.log4j.adapters</groupId>
- <artifactId>log4j12-api</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- </dependecies>
- ]]></source>
+<pre class="prettyprint linenums"><![CDATA[
+<dependencies>
+ <dependency>
+ <groupId>org.apache.logging.log4j.adapters</groupId>
+ <artifactId>log4j12-api</artifactId>
+ <version>${Log4jReleaseVersion}</version>
+ </dependency>
+</dependecies>
+]]></pre>
<h4>Apache Commons Logging</h4>
<p>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.
</p>
- <source><![CDATA[
- <dependencies>
- <dependency>
- <groupId>org.apache.logging.log4j.adapters</groupId>
- <artifactId>log4j-jcl</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- </dependecies>
- ]]></source>
+<pre class="prettyprint linenums"><![CDATA[
+<dependencies>
+ <dependency>
+ <groupId>org.apache.logging.log4j.adapters</groupId>
+ <artifactId>log4j-jcl</artifactId>
+ <version>${Log4jReleaseVersion}</version>
+ </dependency>
+</dependecies>
+]]></pre>
<h4>SLF4J</h4>
<p>SLF4J is another popular logging API that may be bound to Log4j 2 by including the following
dependency along with the SLF4J dependencies.
</p>
- <source><![CDATA[
- <dependencies>
- <dependency>
- <groupId>org.apache.logging.log4j.adapters</groupId>
- <artifactId>log4j-slf4j-impl</artifactId>
- <version>${Log4jReleaseVersion}</version>
- </dependency>
- </dependecies>
- ]]></source>
+<pre class="prettyprint linenums"><![CDATA[
+<dependencies>
+ <dependency>
+ <groupId>org.apache.logging.log4j.adapters</groupId>
+ <artifactId>log4j-slf4j-impl</artifactId>
+ <version>${Log4jReleaseVersion}</version>
+ </dependency>
+</dependecies>
+]]></pre>
</subsection>
</section>
</body>
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 @@
</properties>
<body>
- <section name="About Log4j 2">
+ <section name="Apache Log4j 2">
- <p>
- 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.
- </p>
-
- <p>Some of the features and improvements in Log4j 2 are:</p>
-
- <h3>API Separation</h3>
- <p>
+ <p>
+ 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.
+ </p>
+
+ <p>Some of the features and improvements in Log4j 2 are:</p>
+
+ <dl>
+ <dt>API Separation</dt>
+ <dd>
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.
- </p>
- <h3>Improved Performance</h3>
- <p>
+ </dd>
+ <dt>Improved Performance</dt>
+ <dd>
Log4j 2 performs faster than Log4j 1.x in critical areas and similarly to Logback under most circumstances.
See <a href="performance.html">Performance</a> for more information.
- </p>
- <h3>Support for multiple APIs</h3>
- <p>
+ </dd>
+ <dt>Support for multiple APIs</dt>
+ <dd>
While the Log4j 2 API will provide the best performance, Log4j 2 provides support for the SLF4J and
Commons Logging APIs.
- </p>
- <h3>Automatic Reloading of Configurations</h3>
- <p>
+ </dd>
+ <dt>Automatic Reloading of Configurations</dt>
+ <dd>
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.
- </p>
- <h3>Advanced Filtering</h3>
- <p>
+ </dd>
+ <dt>Advanced Filtering</dt>
+ <dd>
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.
- </p>
- <h3>Plugin Architecture</h3>
- <p>
+ </dd>
+ <dt>Plugin Architecture</dt>
+ <dd>
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.
- </p>
- <h3>Property Support</h3>
- <p>
+ </dd>
+ <dt>Property Support</dt>
+ <dd>
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 <a href="../lookups.html">Lookup</a> Plugin.
- </p>
- </section>
+ </dd>
+ </dl>
- <section name="Documentation">
- <p>The Log4j 2 User's Guide is available on this <a href="manual/index.html">site</a> or as a downloadable
- <a href="log4j-users-guide.pdf">PDF</a>
- </p>.
- </section>
- <section name="Requirements">
- <p>
- 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.
- </p>
- </section>
-
- <section name="News">
- <p>
- 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.
- </p>
+ <subsection name="Documentation">
+ <p>
+ The Log4j 2 User's Guide is available on this <a href="manual/index.html">site</a> or as a downloadable
+ <a href="log4j-users-guide.pdf">PDF</a>.
+ </p>
+ </subsection>
+
+ <subsection name="Requirements">
+ <p>
+ 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.
+ </p>
+ </subsection>
+
+ <subsection name="News">
+ <p>
+ 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.
+ </p>
+ </subsection>
</section>
-
</body>
</document>
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.
</p>
- <source>import org.apache.logging.log4j.LogManager;
+ <pre class="prettyprint linenums">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!");
}
-}</source>
+}</pre>
<p>
The output from the call to logger.info() will vary significantly depending on the configuration
used. See the <a href="./configuration.html">Configuration</a> 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:
</p>
- <source>if (logger.isDebugEnabled()) {
+ <pre class="prettyprint linenums">if (logger.isDebugEnabled()) {
logger.debug("Logging in user " + user.getName() + " with id " + user.getId());
-}</source>
+}</pre>
<p>
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:
</p>
- <source>logger.debug("Logging in user {} with id {}", user.getName(), user.getId());</source>
+ <pre class="prettyprint">logger.debug("Logging in user {} with id {}", user.getName(), user.getId());</pre>
<p>
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.</p>
- <table border="1" width="100%">
+ <table>
<tr>
<th>Parameter Name</th>
<th>Type</th>
@@ -102,7 +102,7 @@
<p>
A typical AsynchAppender configuration might look like:
- <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
<appenders>
<File name="MyFile" fileName="logs/app.log">
@@ -119,8 +119,7 @@
<appender-ref ref="Asynch"/>
</root>
</loggers>
-</configuration>
- ]]></source>
+</configuration>]]></pre>
</p>
</subsection>
<a name="ConsoleAppender"/>
@@ -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.
</p>
- <table border="1" width="100%">
+ <table>
<tr>
<th>Parameter Name</th>
<th>Type</th>
@@ -168,7 +167,7 @@
<p>
A typical Console configuration might look like:
- <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
<appenders>
<Console name="STDOUT" target="SYSTEM_OUT">
@@ -180,15 +179,14 @@
<appender-ref ref="STDOUT"/>
</root>
</loggers>
-</configuration>
- ]]></source>
+</configuration>]]></pre>
</p>
</subsection>
<a name="FailoverAppender"/>
<subsection name="FailoverAppender">
<p>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.</p>
- <table border="1" width="100%">
+ <table>
<tr>
<th>Parameter Name</th>
<th>Type</th>
@@ -232,7 +230,7 @@
<p>
A Failover configuration might look like:
- <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
<appenders>
<RollingFile name="RollingFile" fileName="logs/app.log"
@@ -256,8 +254,7 @@
<appender-ref ref="Failover"/>
</root>
</loggers>
-</configuration>
- ]]></source>
+</configuration>]]></pre>
</p>
</subsection>
<a name="FileAppender"/>
@@ -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.</p>
- <table border="1" width="100%">
+ <table>
<tr>
<th>Parameter Name</th>
<th>Type</th>
@@ -336,7 +333,7 @@
<p>
Here is a sample File configuration:
- <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
<appenders>
<File name="MyFile" fileName="logs/app.log">
@@ -350,8 +347,7 @@
<appender-ref ref="MyFile"/>
</root>
</loggers>
-</configuration>
- ]]></source>
+</configuration>]]></pre>
</p>
</subsection>
<a name="FlumeAppender"/>
@@ -374,7 +370,7 @@
addition, configuring agent properties in the appender configuration will also cause the embedded agent
to be used.
</p>
- <table border="1" width="100%">
+ <table>
<tr>
<th>Parameter Name</th>
<th>Type</th>
@@ -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:
- <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
<appenders>
<Flume name="eventLogger" suppressExceptions="false" compress="true">
@@ -512,15 +508,14 @@
<appender-ref ref="eventLogger"/>
</root>
</loggers>
-</configuration>
- ]]></source>
+</configuration>]]></pre>
</p>
<p>
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.
</p>
- <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
<appenders>
<Flume name="eventLogger" suppressExceptions="false" compress="true" embedded="true">
@@ -540,14 +535,13 @@
<appender-ref ref="STDOUT"/>
</root>
</loggers>
-</configuration>
- ]]></source>
+</configuration>]]></pre>
<p>
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.
</p>
- <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="error" name="MyApp" packages="">
<appenders>
<Flume name="eventLogger" suppressExceptions="false" compress="true" embedded="true">
@@ -585,13 +579,12 @@
<appender-ref ref="STDOUT"/>
</root>
</loggers>
-</configuration>
- ]]></source>
+</configuration>]]></pre>
</subsection>
<a name="JMSQueueAppender"/>
<subsection name="JMSQueueAppender">
<p>The JMSQueueAppender sends the formatted log event to a JMS Queue.</p>
- <table border="1" width="100%">
+ <table>
<tr>
<th>Parameter Name</th>
<th>Type</th>
@@ -682,7 +675,7 @@
<p>
Here is a sample JMSQueueAppender configuration:
- <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
<appenders>
<JMSQueue name="jmsQueue" queueBindingName="MyQueue"
@@ -693,14 +686,13 @@
<appender-ref ref="jmsQueue"/>
</root>
</loggers>
-</configuration>
- ]]></source>
+</configuration>]]></pre>
</p>
</subsection>
<a name="JMSTopicAppender"/>
<subsection name="JMSTopicAppender">
<p>The JMSTopicAppender sends the formatted log event to a JMS Topic.</p>
- <table border="1" width="100%">
+ <table>
<tr>
<th>Parameter Name</th>
<th>Type</th>
@@ -792,7 +784,7 @@
<p>
Here is a sample JMSTopicAppender configuration:
- <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
<appenders>
<JMSTopic name="jmsTopic" topicBindingName="MyTopic"
@@ -803,8 +795,7 @@
<appender-ref ref="jmsQueue"/>
</root>
</loggers>
-</configuration>
- ]]></source>
+</configuration>]]></pre>
</p>
</subsection>
<a name="OutputStreamAppender"/>
@@ -823,7 +814,7 @@
The RewriteAppender must be configured with a <a href="RewritePolicy">RewritePolicy</a>. The
RewriteAppender should be configured after any Appenders it references to allow it to shut down properly.
</p>
- <table border="1" width="100%">
+ <table>
<tr>
<th>Parameter Name</th>
<th>Type</th>
@@ -870,7 +861,7 @@
MapRewritePolicy will evaluate LogEvents that contain a MapMessage and will add or update
elements of the Map.
</p>
- <table border="1" width="100%">
+ <table>
<tr>
<th>Parameter Name</th>
<th>Type</th>
@@ -891,7 +882,7 @@
The following configuration shows a RewriteAppender configured to add a product key and its value
to the MapMessage.:
- <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
<appenders>
<Console name="STDOUT" target="SYSTEM_OUT">
@@ -909,8 +900,7 @@
<appender-ref ref="Rewrite"/>
</root>
</loggers>
-</configuration>
- ]]></source>
+</configuration>]]></pre>
</p>
<h5>PropertiesRewritePolicy</h5>
<p>
@@ -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.
</p>
- <table border="1" width="100%">
+ <table>
<tr>
<th>Parameter Name</th>
<th>Type</th>
@@ -935,7 +925,7 @@
The following configuration shows a RewriteAppender configured to add a product key and its value
to the MapMessage.:
- <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
<appenders>
<Console name="STDOUT" target="SYSTEM_OUT">
@@ -954,8 +944,7 @@
<appender-ref ref="Rewrite"/>
</root>
</loggers>
-</configuration>
- ]]></source>
+</configuration>]]></pre>
</p>
</subsection>
<a name="RollingFileAppender"/>
@@ -976,7 +965,7 @@
<p>
File locking is not supported by the RollingFileAppender.
</p>
- <table border="1" width="100%">
+ <table>
<tr>
<th>Parameter Name</th>
<th>Type</th>
@@ -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.
</p>
- <table border="1" width="100%">
+ <table>
<tr>
<th>Parameter Name</th>
<th>Type</th>
@@ -1119,7 +1108,7 @@
<p>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.</p>
- <table border="1" width="100%">
+ <table>
<tr>
<th>Parameter Name</th>
<th>Type</th>
@@ -1144,7 +1133,7 @@
based on the current year and month, and will compress each
archive using gzip:
- <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
<appenders>
<RollingFile name="RollingFile" fileName="logs/app.log"
@@ -1163,12 +1152,11 @@
<appender-ref ref="RollingFile"/>
</root>
</loggers>
-</configuration>
- ]]></source>
+</configuration>]]></pre>
</p>
<p>
This second example shows a rollover strategy that will keep up to 20 files before removing them.
- <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
<appenders>
<RollingFile name="RollingFile" fileName="logs/app.log"
@@ -1188,8 +1176,7 @@
<appender-ref ref="RollingFile"/>
</root>
</loggers>
-</configuration>
- ]]></source>
+</configuration>]]></pre>
</p>
<p>
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:
- <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
<appenders>
<RollingFile name="RollingFile" fileName="logs/app.log"
@@ -1216,8 +1203,7 @@
<appender-ref ref="RollingFile"/>
</root>
</loggers>
-</configuration>
- ]]></source>
+</configuration>]]></pre>
</p>
</subsection>
<a name="RoutingAppender"/>
@@ -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.
</p>
- <table border="1" width="100%">
+ <table>
<tr>
<th>Parameter Name</th>
<th>Type</th>
@@ -1283,7 +1269,7 @@
the specific event type. Note that the AuditAppender was predefined while the RollingFileAppenders
are created as needed.
- <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
<appenders>
<Flume name="AuditLogger" suppressExceptions="false" compress="true">
@@ -1311,8 +1297,7 @@
<appender-ref ref="Routing"/>
</root>
</loggers>
-</configuration>
- ]]></source>
+</configuration>]]></pre>
</p>
</subsection>
<a name="SocketAppender"/>
@@ -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.
</p>
- <table border="1" width="100%">
+ <table>
<tr>
<th>Parameter Name</th>
<th>Type</th>
@@ -1383,7 +1368,7 @@
<caption align="top">SocketAppender Parameters</caption>
</table>
- <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
<appenders>
<Socket name="socket" host="localhost" port="9500">
@@ -1395,8 +1380,7 @@
<appender-ref ref="socket"/>
</root>
</loggers>
-</configuration>
- ]]></source>
+</configuration>]]></pre>
</subsection>
<a name="SyslogAppender"/>
<subsection name="SyslogAppender">
@@ -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.
</p>
- <table border="1" width="100%">
+ <table>
<tr>
<th>Parameter Name</th>
<th>Type</th>
@@ -1546,7 +1530,7 @@
A sample syslogAppender configuration that is configured with two SyslogAppenders, one using the BSD
format and one using RFC 5424.
- <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
<appenders>
<Syslog name="bsd" host="localhost" port="514" protocol="TCP"/>
@@ -1563,8 +1547,7 @@
<appender-ref ref="bsd"/>
</root>
</loggers>
-</configuration>
- ]]></source>
+</configuration>]]></pre>
</p>
</subsection>
</section>
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 @@
<section name="Architecture">
<subsection name="Main Components">
<p>Log4j uses the classes shown in the diagram below.</p>
- <img src="../images/Log4jClasses.jpg" title="Log4j 2 Class Relationships"
+ <img src="../images/Log4jClasses.jpg" title="Log4j 2 Class Relationships"
caption="Log4j 2 Class Relationships"/>
<p>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:
</p>
- <p>
- <table bgcolor="#EEEE99">
- <tr>
- <td>
- <dl>
- <dt>
- <b>Named Hierarchy</b>
- </dt>
-
- <dd>A LoggerConfig is said to be an
- <em>ancestor</em>
- of another
- LoggerConfig if its name followed by a dot is a prefix of the
- <em>descendant</em>
- logger name. A LoggerConfig is said to be a
- <em>parent</em>
- of a
- <em>child</em>
- LoggerConfig if there are no
- ancestors between itself and the descendant LoggerConfig.
- </dd>
- </dl>
- </td>
- </tr>
- </table>
- </p>
+ <div class="well">
+ <dl>
+ <dt>Named Hierarchy</dt>
+ <dd>
+ A LoggerConfig is said to be an <em>ancestor</em> of another LoggerConfig if its name followed by a dot
+ is a prefix of the <em>descendant</em> logger name. A LoggerConfig is said to be a <em>parent</em> of a
+ <em>child</em> LoggerConfig if there are no ancestors between itself and the descendant LoggerConfig.
+ </dd>
+ </dl>
+ </div>
+
<p>For example, the LoggerConfig named
<code>"com.foo"</code>
is a parent
@@ -94,7 +79,7 @@
<p>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:
- <source>Logger logger = LogManager.getLogger(LogManager.ROOT_LOGGER_NAME);</source>
+ <pre class="prettyprint">Logger logger = LogManager.getLogger(LogManager.ROOT_LOGGER_NAME);</pre>
All other Loggers can be retrieved using the
<a href="../log4j-api/apidocs/org/apache/logging/log4j/LogManager.html#getLogger(java.lang.String)">
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.
</p>
- <table bgcolor="#EEEE99">
- <tr>
- <td>Retrieving Loggers</td>
- </tr>
- </table>
- <p>Calling the
- <code>getLogger</code>
- method with the same name will
- always return a reference to the exact same Logger object.
+ <h5>Retrieving Loggers</h5>
+ <p>
+ Calling the <code>getLogger</code> method with the same name will always return a reference to the exact
+ same Logger object.
</p>
<p>For example, in
- <source>
- Logger x = Logger.getLogger("wombat");
- Logger y = Logger.getLogger("wombat");
- </source>
+<pre class="prettyprint">
+Logger x = Logger.getLogger("wombat");
+Logger y = Logger.getLogger("wombat");
+</pre>
<code>x</code> and <code>y</code> refer to <em>exactly</em> the same Logger object.
</p>
@@ -176,11 +156,7 @@
passed to any Appenders. It contains references to the set of Appenders that should be used to
process the event.
</p>
- <table bgcolor="#EEEE99">
- <tr>
- <td>Log Levels</td>
- </tr>
- </table>
+ <h5>Log Levels</h5>
<p>LoggerConfigs will be assigned a Log
<a href="../log4j-api/apidocs/org/apache/logging/log4j/Level.html">Level</a>. 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.
</p>
- <table border="1" width="40%">
+ <table style="width: 40%">
<tr>
<th>Logger Name</th>
<th>Assigned LoggerConfig</th>
- <th>level</th>
+ <th>Level</th>
</tr>
- <tr align="left">
+ <tr>
<td>root</td>
<td>root</td>
<td>DEBUG</td>
</tr>
- <tr align="left">
+ <tr>
<td>X</td>
<td>root</td>
<td>DEBUG</td>
</tr>
- <tr align="left">
+ <tr>
<td>X.Y</td>
<td>root</td>
<td>DEBUG</td>
</tr>
- <tr align="left">
+ <tr>
<td>X.Y.Z</td>
<td>root</td>
<td>DEBUG</td>
@@ -234,28 +210,28 @@
Loggers reference the root LoggerConfig and use its Level.
</p>
- <table border="1" width="40%">
+ <table style="width: 40%">
<tr>
<th>Logger Name</th>
<th>Assigned LoggerConfig</th>
- <th>level</th>
+ <th>Level</th>
</tr>
- <tr align="left">
+ <tr>
<td>root</td>
<td>root</td>
<td>DEBUG</td>
</tr>
- <tr align="left">
+ <tr>
<td>X</td>
<td>X</td>
<td>ERROR</td>
</tr>
- <tr align="left">
+ <tr>
<td>X.Y</td>
<td>X.Y</td>
<td>INFO</td>
</tr>
- <tr align="left">
+ <tr>
<td>X.Y.Z</td>
<td>X.Y.Z</td>
<td>WARN</td>
@@ -267,28 +243,28 @@
from it.
</p>
- <table border="1" width="40%">
+ <table style="width: 40%">
<tr>
<th>Logger Name</th>
<th>Assigned LoggerConfig</th>
- <th>level</th>
+ <th>Level</th>
</tr>
- <tr align="left">
+ <tr>
<td>root</td>
<td>root</td>
<td>DEBUG</td>
</tr>
- <tr align="left">
+ <tr>
<td>X</td>
<td>X</td>
<td>ERROR</td>
</tr>
- <tr align="left">
+ <tr>
<td>X.Y</td>
<td>X</td>
<td>ERROR</td>
</tr>
- <tr align="left">
+ <tr>
<td>X.Y.Z</td>
<td>X.Y.Z</td>
<td>WARN</td>
@@ -309,28 +285,28 @@
name has the longest match to the start of the Logger's name.
</p>
- <table border="1" width="40%">
+ <table style="width: 40%">
<tr>
<th>Logger Name</th>
<th>Assigned LoggerConfig</th>
<th>level</th>
</tr>
- <tr align="left">
+ <tr>
<td>root</td>
<td>root</td>
<td>DEBUG</td>
</tr>
- <tr align="left">
+ <tr>
<td>X</td>
<td>X</td>
<td>ERROR</td>
</tr>
- <tr align="left">
+ <tr>
<td>X.Y</td>
<td>X</td>
<td>ERROR</td>
</tr>
- <tr align="left">
+ <tr>
<td>X.Y.Z</td>
<td>X</td>
<td>ERROR</td>
@@ -352,28 +328,28 @@
longest match to the start of the Logger's name.
</p>
- <table border="1" width="40%">
+ <table style="width: 40%">
<tr>
<th>Logger Name</th>
<th>Assigned LoggerConfig</th>
<th>level</th>
</tr>
- <tr align="left">
+ <tr>
<td>root</td>
<td>root</td>
<td>DEBUG</td>
</tr>
- <tr align="left">
+ <tr>
<td>X</td>
<td>X</td>
<td>ERROR</td>
</tr>
- <tr align="left">
+ <tr>
<td>X.Y</td>
<td>X.Y</td>
<td>INFO</td>
</tr>
- <tr align="left">
+ <tr>
<td>X.YZ</td>
<td>X</td>
<td>ERROR</td>
@@ -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).
</p>
- <table width="100%">
+ <table>
<tr>
- <th style="background-color:cyan; color:black">Event Level</th>
- <th style="background-color:cyan; color:black; border-top: 1px solid #DDDDDD;"
- align="center" colspan="6">LoggerConfig Level</th>
- </tr>
- <tr align="left">
- <th style="background-color:cyan; color:black"> </th>
- <th style="background-color:cyan; color:black">TRACE</th>
- <th style="background-color:cyan; color:black">DEBUG</th>
- <th style="background-color:cyan; color:black">INFO</th>
- <th style="background-color:cyan; color:black">WARN</th>
- <th style="background-color:cyan; color:black">ERROR</th>
- <th style="background-color:cyan; color:black">FATAL</th>
- </tr>
- <tr align="left">
- <th style="background-color:cyan; color:black">ALL</th>
- <td style="color:red;font-weight:bold">NO</td>
- <td style="color:red;font-weight:bold">NO</td>
- <td style="color:red;font-weight:bold">NO</td>
- <td style="color:red;font-weight:bold">NO</td>
- <td style="color:red;font-weight:bold">NO</td>
- <td style="color:red;font-weight:bold">NO</td>
- </tr>
- <tr align="left">
- <th style="background-color:cyan; color:black">TRACE</th>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:red;font-weight:bold">NO</td>
- <td style="color:red;font-weight:bold">NO</td>
- <td style="color:red;font-weight:bold">NO</td>
- <td style="color:red;font-weight:bold">NO</td>
- <td style="color:red;font-weight:bold">NO</td>
- </tr>
- <tr align="left">
- <th style="background-color:cyan; color:black">DEBUG</th>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:red;font-weight:bold">NO</td>
- <td style="color:red;font-weight:bold">NO</td>
- <td style="color:red;font-weight:bold">NO</td>
- <td style="color:red;font-weight:bold">NO</td>
- </tr>
- <tr align="left">
- <th style="background-color:cyan; color:black">INFO</th>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:red;font-weight:bold">NO</td>
- <td style="color:red;font-weight:bold">NO</td>
- <td style="color:red;font-weight:bold">NO</td>
- </tr>
- <tr align="left">
- <th style="background-color:cyan; color:black">WARN</th>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:red;font-weight:bold">NO</td>
- <td style="color:red;font-weight:bold">NO</td>
- </tr>
- <tr align="left">
- <th style="background-color:cyan; color:black">ERROR</th>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:red;font-weight:bold">NO</td>
- </tr>
- <tr align="left">
- <th style="background-color:cyan; color:black">FATAL</th>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- </tr>
- <tr align="left">
- <th style="background-color:cyan; color:black">OFF</th>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
- <td style="color:green;font-weight:bold">YES</td>
+ <th>Event Level</th>
+ <th style="text-align: center" colspan="6">LoggerConfig Level</th>
+ </tr>
+ <tr>
+ <th> </th>
+ <th>TRACE</th>
+ <th>DEBUG</th>
+ <th>INFO</th>
+ <th>WARN</th>
+ <th>ERROR</th>
+ <th>FATAL</th>
+ </tr>
+ <tr>
+ <th>ALL</th>
+ <td class="big-red">NO</td>
+ <td class="big-red">NO</td>
+ <td class="big-red">NO</td>
+ <td class="big-red">NO</td>
+ <td class="big-red">NO</td>
+ <td class="big-red">NO</td>
+ </tr>
+ <tr>
+ <th>TRACE</th>
+ <td class="big-green">YES</td>
+ <td class="big-red">NO</td>
+ <td class="big-red">NO</td>
+ <td class="big-red">NO</td>
+ <td class="big-red">NO</td>
+ <td class="big-red">NO</td>
+ </tr>
+ <tr>
+ <th>DEBUG</th>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-red">NO</td>
+ <td class="big-red">NO</td>
+ <td class="big-red">NO</td>
+ <td class="big-red">NO</td>
+ </tr>
+ <tr>
+ <th>INFO</th>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-red">NO</td>
+ <td class="big-red">NO</td>
+ <td class="big-red">NO</td>
+ </tr>
+ <tr>
+ <th>WARN</th>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-red">NO</td>
+ <td class="big-red">NO</td>
+ </tr>
+ <tr>
+ <th>ERROR</th>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-red">NO</td>
+ </tr>
+ <tr>
+ <th>FATAL</th>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ </tr>
+ <tr>
+ <th>OFF</th>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
+ <td class="big-green">YES</td>
</tr>
</table>
<h4>Filter</h4>
- <p>In addition to the automatic log Level filtering that takes place as described in the previous
- section, Log4j provides
- <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/Filter.html">Filter</a>s 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.
- </p>
- <p>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.
- </p>
+ <p>In addition to the automatic log Level filtering that takes place as described in the previous
+ section, Log4j provides
+ <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/Filter.html">Filter</a>s 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.
+ </p>
+ <p>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.
+ </p>
+
<h4>Appender</h4>
- <p>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
- <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/Appender.html">Appender</a>.
- 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.
- </p>
- <p>An Appender can be added to a Logger by calling the
- <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/Configuration.html#addLoggerAppender(org.apache.logging.log4j.core.Logger, org.apache.logging.log4j.core.Appender)">addLoggerAppender</a>
- 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.
- </p>
- <p><b>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.</b> 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
- <em>C</em>, then enabled logging requests for <em>C</em> and <em>C</em>'s children will print
- in a file <em>and</em> on the console. It is possible to override this default behavior so that
- Appender accumulation is no longer additive by setting <code>additivity="false"</code> on the
- Logger declaration in the configuration file.
- </p>
- <p>The rules governing appender additivity are summarized below.</p>
-
- <p>
- <a name="additivity"/>
- <table bgcolor="#EEEE99">
- <tr>
- <td>
- <dl>
- <dt><b>Appender Additivity</b></dt>
-
- <dd>
- <p>The output of a log statement of Logger <i>L</i> will
- go to all the Appenders in the LoggerConfig associated with <i>L</i>
- and the ancestors of that LoggerConfig. This is the meaning of the term "appender additivity".
- </p>
-
- <p>However, if an ancestor of the LoggerConfig associated with Logger <i>L</i>, say <i>P</i>,
- has the additivity flag set to <code>false</code>, then <i>L</i>'s output will be
- directed to all the appenders in <i>L</i>'s LoggerConfig and it's ancestors up to
- and including <i>P</i> but not the Appenders in any of the ancestors of <i>P</i>.
- </p>
-
- <p>Loggers have their additivity flag set to <code>true</code> by default.</p>
- </dd>
- </dl>
- </td>
- </tr>
- </table>
- </p>
-
- <p>The table below shows an example:</p>
-
- <p>
- <table align="center" border="3" cellpadding="10">
- <tr rowspan="2">
- <th>Logger<br />Name </th>
- <th>Added<br/>Appenders</th>
- <th>Additivity<br/>Flag</th>
- <th>Output Targets</th>
- <th>Comment</th>
- </tr>
- <tr>
- <td>root</td>
- <td>A1</td>
- <td>not applicable</td>
- <td>A1</td>
- <td>The root logger has no parent so additivity does not apply to it.</td>
- </tr>
- <tr>
- <td>x</td>
- <td>A-x1, A-x2</td>
- <td>true </td>
- <td>A1, A-x1, A-x2</td>
- <td>Appenders of "x" and root.</td>
- </tr>
- <tr>
- <td>x.y</td>
- <td>none</td>
- <td>true </td>
- <td>A1, A-x1, A-x2</td>
- <td>Appenders of "x" and root. It would not be typical to configure a Logger with no Appenders.</td>
- </tr>
- <tr>
- <td>x.y.z</td>
- <td>A-xyz1</td>
- <td>true </td>
- <td>A1, A-x1, A-x2, A-xyz1</td>
- <td>Appenders in "x.y.z", "x" and root.</td>
- </tr>
- <tr>
- <td>security</td>
- <td>A-sec</td>
- <td><font color="blue">false</font></td>
- <td>A-sec</td>
- <td>No appender accumulation since the additivity flag is set to <code>false</code>.</td>
- </tr>
- <tr>
- <td>security.access</td>
- <td>none</td>
- <td>true</td>
- <td>A-sec</td>
- <td>Only appenders of "security" because the additivity flag in "security" is
- set to <code>false</code>.
- </td>
- </tr>
- </table>
- </p>
+
+ <p>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
+ <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/Appender.html">Appender</a>.
+ 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.
+ </p>
+ <p>An Appender can be added to a Logger by calling the
+ <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/Configuration.html#addLoggerAppender(org.apache.logging.log4j.core.Logger, org.apache.logging.log4j.core.Appender)">addLoggerAppender</a>
+ 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.
+ </p>
+ <p><b>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.</b> 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
+ <em>C</em>, then enabled logging requests for <em>C</em> and <em>C</em>'s children will print
+ in a file <em>and</em> on the console. It is possible to override this default behavior so that
+ Appender accumulation is no longer additive by setting <code>additivity="false"</code> on the
+ Logger declaration in the configuration file.
+ </p>
+ <p>The rules governing appender additivity are summarized below.</p>
+
+ <div class="well">
+ <dl>
+ <dt><b>Appender Additivity</b></dt>
+ <dd>
+ <p>
+ The output of a log statement of Logger <i>L</i> will go to all the Appenders in the LoggerConfig
+ associated with <i>L</i> and the ancestors of that LoggerConfig. This is the meaning of the term
+ "appender additivity".
+ </p>
+ <p>
+ However, if an ancestor of the LoggerConfig associated with Logger <i>L</i>, say <i>P</i>, has the
+ additivity flag set to <code>false</code>, then <i>L</i>'s output will be directed to all the
+ appenders in <i>L</i>'s LoggerConfig and it's ancestors up to and including <i>P</i> but not the
+ Appenders in any of the ancestors of <i>P</i>.
+ </p>
+ <p>Loggers have their additivity flag set to <code>true</code> by default.</p>
+ </dd>
+ </dl>
+ </div>
+
+ <p>The table below shows an example:</p>
+
+ <table>
+ <tr rowspan="2">
+ <th>Logger<br />Name </th>
+ <th>Added<br/>Appenders</th>
+ <th>Additivity<br/>Flag</th>
+ <th>Output Targets</th>
+ <th>Comment</th>
+ </tr>
+ <tr>
+ <td>root</td>
+ <td>A1</td>
+ <td>not applicable</td>
+ <td>A1</td>
+ <td>The root logger has no parent so additivity does not apply to it.</td>
+ </tr>
+ <tr>
+ <td>x</td>
+ <td>A-x1, A-x2</td>
+ <td>true </td>
+ <td>A1, A-x1, A-x2</td>
+ <td>Appenders of "x" and root.</td>
+ </tr>
+ <tr>
+ <td>x.y</td>
+ <td>none</td>
+ <td>true </td>
+ <td>A1, A-x1, A-x2</td>
+ <td>Appenders of "x" and root. It would not be typical to configure a Logger with no Appenders.</td>
+ </tr>
+ <tr>
+ <td>x.y.z</td>
+ <td>A-xyz1</td>
+ <td>true </td>
+ <td>A1, A-x1, A-x2, A-xyz1</td>
+ <td>Appenders in "x.y.z", "x" and root.</td>
+ </tr>
+ <tr>
+ <td>security</td>
+ <td>A-sec</td>
+ <td><font color="blue">false</font></td>
+ <td>A-sec</td>
+ <td>No appender accumulation since the additivity flag is set to <code>false</code>.</td>
+ </tr>
+ <tr>
+ <td>security.access</td>
+ <td>none</td>
+ <td>true</td>
+ <td>A-sec</td>
+ <td>Only appenders of "security" because the additivity flag in "security" is
+ set to <code>false</code>.
+ </td>
+ </tr>
+ </table>
+
<h4>Layout</h4>
<p>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 @@
<p>For example, the PatternLayout with the conversion pattern "%r [%t]
%-5p %c - %m%n" will output something akin to:<br />
- <source>176 [main] INFO org.foo.Bar - Located nearest gas station.</source>
+ <pre>176 [main] INFO org.foo.Bar - Located nearest gas station.</pre>
</p>
<p>The first field is the number of milliseconds elapsed since the