Author: rgoers
Date: Mon Oct 17 06:07:26 2011
New Revision: 1185013
URL: http://svn.apache.org/viewvc?rev=1185013&view=rev
Log:
Added more content to architecture page
Modified:
logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/architecture.xml
Modified:
logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/architecture.xml
URL:
http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/architecture.xml?rev=1185013&r1=1185012&r2=1185013&view=diff
==============================================================================
---
logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/architecture.xml
(original)
+++
logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/architecture.xml
Mon Oct 17 06:07:26 2011
@@ -17,90 +17,658 @@
-->
<document>
- <properties>
- <title>Overview</title>
- <author email="[email protected]">Ralph Goers</author>
- </properties>
-
- <body>
- <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.0 Class
Relationships"
- caption="Log4j 2.0 Class Relationships"/>
- <p>Applications using the Log4j 2.0 API will request a Logger with a
specific name from the
+ <properties>
+ <title>Overview</title>
+ <author email="[email protected]">Ralph Goers</author>
+ </properties>
+
+ <body>
+ <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.0 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.
If the Logger must be created it will be associated with the
LoggerConfig that contains either a) the
same name as the Logger, b) the name of a parent package, or c) the
root LoggerConfig. LoggerConfig
objects are created from Logger declarations in the configuration.
The LoggerConfig is associated with
- the Appenders that actually deliver the LogEvents.</p>
- <h4>Logger Hierarchy</h4>
- <p>The first and foremost advantage of any logging API over plain
- <code>System.out.println</code> resides in its ability to disable
- certain log statements while allowing others to print
unhindered. This
- capability assumes that the logging space, that is, the space of
all
- possible logging statements, is categorized according to some
- developer-chosen criteria.
- </p>
- <p>In Log4j 1.x the Logger Hierarchy was maintained through a
relationship between Loggers.
- In Log4j 2.0 this relationship no longers exists. Instead, the
hierarchy is maintained
- in the relationship between LoggerConfig objects.
- </p>
-
- <p>Loggers and LoggerConfigs are named entities. Logger names are
case-sensitive and
- they follow the hierarchical naming rule:
- </p>
+ the Appenders that actually deliver the LogEvents.
+ </p>
+ <h4>Logger Hierarchy</h4>
+ <p>The first and foremost advantage of any logging API over plain
+ <code>System.out.println</code>
+ resides in its ability to disable
+ certain log statements while allowing others to print unhindered.
This
+ capability assumes that the logging space, that is, the space of all
+ possible logging statements, is categorized according to some
+ developer-chosen criteria.
+ </p>
+ <p>In Log4j 1.x the Logger Hierarchy was maintained through a
relationship between Loggers.
+ In Log4j 2 this relationship no longers exists. Instead, the
hierarchy is maintained
+ in the relationship between LoggerConfig objects.
+ </p>
+
+ <p>Loggers and LoggerConfigs are named entities. Logger names are
case-sensitive and
+ 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>
+ <p>For example, the LoggerConfig named
+ <code>"com.foo"</code>
+ is a parent
+ of the LoggerConfig named<code>"com.foo.Bar"</code>. Similarly,
+ <code>"java"</code>
+ is a parent of
+ <code>"java.util"</code>
+ and an
+ ancestor of<code>"java.util.Vector"</code>. This naming scheme
+ should be familiar to most developers.
+ </p>
+
+ <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>
+ All other Loggers can be retrieved using the
+ <a
href="../log4j2-api/apidocs/org/apache/logging/log4j/LogManager.html#getLogger(java.lang.String)">
+ LogManager.getLogger
+ </a>
+ static method and passing the name of the desired Logger. Further
informaiton on the Logging
+ API can be found at<a href="../log4j2-api/api.html">Log4j 2 API</a>.
+ </p>
+ <h4>LoggerContext</h4>
+ <p>
+ The
+ <a
href="../log4j2-core/apidocs/org/apache/logging/log4j/core/LoggerContext.html">LoggerContext</a>
+ acts as the anchor point for the Logging system. However, it is
possible to have multiple active
+ LoggerContexts in an application depending on the circumstances.
+ More details on the LoggerContext are at<a href="logsep.html">Log
Separation</a>.
+ </p>
+ <h4>Configuration</h4>
+ <p>Every LoggerContext has an active
+ <a
href="../log4j/log4j2-core/apidocs/org/apache/logging/log4j/core/config/Configuration.html">
+ Configuration</a>.
+ The Configuration contains all the Appenders,
+ context-wide Filtes, LoggerConfigs and contains the reference to the
StrSubstitutor. During
+ reconfiguration two Configuration objects will exist. Once all
Loggers have been redirected to
+ the new Configuration, the old Configuration will be stopped and
discarded.
+ </p>
+ <h4>Logger</h4>
+ <p>As stated previously, Loggers are created by calling
+ <a
href="../log4j2-api/apidocs/org/apache/logging/log4j/LogManager.html#getLogger(java.lang.String)">LogManager.getLogger</a>.
+ The Logger itself performs no direct actions. It simply has a name
and is associated with a LoggerConfig.
+ It extends
+ <a
href="file:///Users/rgoers/log4j/log4j2-api/apidocs/org/apache/logging/log4j/spi/AbstractLogger.html">
+ AbstractLogger
+ </a>
+ 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.
+ </p>
+
+ <p>For example, in
+ <source>
+ Logger x = Logger.getLogger("wombat");
+ Logger y = Logger.getLogger("wombat");
+ </source>
+ <code>x</code> and <code>y</code> refer to <em>exactly</em> the same
Logger object.
+ </p>
+
+ <p>Configuration of the log4j environment is typically done at
+ application initialization. The preferred way is by reading a
+ configuration file. This is discussed in <a
href="configuration.html">Configuration</a>.
+ </p>
+
+ <p>Log4j makes it easy to name Loggers by <em>software component</em>.
This can be accomplished
+ by instantiating a Logger in each class, with the logger name equal
to the fully
+ qualified name of the class. This is a useful and straightforward
+ method of defining loggers. As the log output bears the name of the
+ generating Logger, this naming strategy makes it easy to identify
+ the origin of a log message. However, this is only one possible,
+ albeit common, strategy for naming loggers. Log4j does not restrict
+ the possible set of loggers. The developer is free to name the
+ loggers as desired.
+ </p>
+
+ <p>Nevertheless, naming loggers after the class where they are
+ located seems to be the best strategy known so far.
+ </p>
+ <h4>LoggerConfig</h4>
+ <p>
+ <a
href="../log4j2-core/apidocs/org/apache/logging/log4j/core/config/LoggerConfig.html">LoggerConfig</a>
+ objects are created when Loggers are declared in the logging
configuration.
+ The LoggerConfig contains a set of Filters that must allow the
LogEvent to pass before it will be
+ 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>
+ <p>LoggerConfigs will be assigned a Log
+ <a
href="../log4j2-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
+ an Enum and cannot be sub-classed. Users who desire more granularity
are encouraged to use
+ <a href="../log4j2-api/api.html#Markers">Markers</a>
+ instead.
+ </p>
+ <p>
+ <a href="http://logging.apache.org/log4j/1.2/manual.html";>Log4j
1.x</a>
+ and
+ <a
href="http://logback.qos.ch/manual/architecture.html#effectiveLevel";>Logback</a>
+ both have the concept of "Level Inheritance". In Log4j 2, Loggers
and LoggerConfigs are two different
+ objects so this concept is implemented differently. Each Logger
references the
+ appropriate LoggerConfig which in turn can reference its parent,
thus achieving the same effect.
+ </p>
+ <p>Below are five tables with various assigned level values and the
resulting levels that
+ will be associated with each Logger. Note that in all these cases if
the root LoggerConfig
+ is not configured a default Level will be assigned to it.
+ </p>
+
+ <table border="1" width="40%">
+ <tr>
+ <th>Logger Name</th>
+ <th>Assigned LoggerConfig</th>
+ <th>level</th>
+ </tr>
+ <tr align="left">
+ <td>root</td>
+ <td>root</td>
+ <td>DEBUG</td>
+ </tr>
+ <tr align="left">
+ <td>X</td>
+ <td>root</td>
+ <td>DEBUG</td>
+ </tr>
+ <tr align="left">
+ <td>X.Y</td>
+ <td>root</td>
+ <td>DEBUG</td>
+ </tr>
+ <tr align="left">
+ <td>X.Y.Z</td>
+ <td>root</td>
+ <td>DEBUG</td>
+ </tr>
+ <caption align="bottom">Example 1</caption>
+ </table>
+
+ <p>In example 1 above, only the root logger is configured and has a
Log Level. All the other
+ Loggers reference the root LoggerConfig and use its Level.
+ </p>
+
+ <table border="1" width="40%">
+ <tr>
+ <th>Logger Name</th>
+ <th>Assigned LoggerConfig</th>
+ <th>level</th>
+ </tr>
+ <tr align="left">
+ <td>root</td>
+ <td>root</td>
+ <td>DEBUG</td>
+ </tr>
+ <tr align="left">
+ <td>X</td>
+ <td>X</td>
+ <td>ERROR</td>
+ </tr>
+ <tr align="left">
+ <td>X.Y</td>
+ <td>X.Y</td>
+ <td>INFO</td>
+ </tr>
+ <tr align="left">
+ <td>X.Y.Z</td>
+ <td>X.Y.Z</td>
+ <td>WARN</td>
+ </tr>
+ <caption align="bottom">Example 2</caption>
+ </table>
+
+ <p>In example 2, all loggers have a configured LoggerConfig and obtain
their Level
+ from it.
+ </p>
+
+ <table border="1" width="40%">
+ <tr>
+ <th>Logger Name</th>
+ <th>Assigned LoggerConfig</th>
+ <th>level</th>
+ </tr>
+ <tr align="left">
+ <td>root</td>
+ <td>root</td>
+ <td>DEBUG</td>
+ </tr>
+ <tr align="left">
+ <td>X</td>
+ <td>X</td>
+ <td>ERROR</td>
+ </tr>
+ <tr align="left">
+ <td>X.Y</td>
+ <td>X</td>
+ <td>ERROR</td>
+ </tr>
+ <tr align="left">
+ <td>X.Y.Z</td>
+ <td>X.Y.Z</td>
+ <td>WARN</td>
+ </tr>
+ <caption align="bottom">Example 3</caption>
+ </table>
+
+ <p>In example 3, the loggers<code>root</code>,
+ <code>X</code>
+ and
+ <code>X.Y.Z</code>
+ each have a configured LoggerConfig with the same name. The Logger
+ <code>X.Y</code>
+ does not have a configured LoggerConfig with a matching name so uses
+ the configuration of LoggerConfig
+ <code>X</code>
+ since that is the LoggerConfig whose
+ name has the longest match to the start of the Logger's name.
+ </p>
+
+ <table border="1" width="40%">
+ <tr>
+ <th>Logger Name</th>
+ <th>Assigned LoggerConfig</th>
+ <th>level</th>
+ </tr>
+ <tr align="left">
+ <td>root</td>
+ <td>root</td>
+ <td>DEBUG</td>
+ </tr>
+ <tr align="left">
+ <td>X</td>
+ <td>X</td>
+ <td>ERROR</td>
+ </tr>
+ <tr align="left">
+ <td>X.Y</td>
+ <td>X</td>
+ <td>ERROR</td>
+ </tr>
+ <tr align="left">
+ <td>X.Y.Z</td>
+ <td>X</td>
+ <td>ERROR</td>
+ </tr>
+ <caption align="bottom">Example 4</caption>
+ </table>
+
+ <p>In example 4, the loggers
+ <code>root</code>
+ and
+ <code>X</code>
+ each have a Configured
+ LoggerConfig with the same name. The loggers
+ <code>X.Y</code>
+ and
+ <code>X.Y.Z</code>
+ do not have configured LoggerConfigs and so get their Level from the
LoggerConfig
+ assigned to them,<code>X</code>, since it is the LoggerCofnig whose
name has the
+ longest match to the start of the Logger's name.
+ </p>
+
+ <table border="1" width="40%">
+ <tr>
+ <th>Logger Name</th>
+ <th>Assigned LoggerConfig</th>
+ <th>level</th>
+ </tr>
+ <tr align="left">
+ <td>root</td>
+ <td>root</td>
+ <td>DEBUG</td>
+ </tr>
+ <tr align="left">
+ <td>X</td>
+ <td>X</td>
+ <td>ERROR</td>
+ </tr>
+ <tr align="left">
+ <td>X.Y</td>
+ <td>X.Y</td>
+ <td>INFO</td>
+ </tr>
+ <tr align="left">
+ <td>X.YZ</td>
+ <td>X</td>
+ <td>ERROR</td>
+ </tr>
+ <caption align="bottom">Example 5</caption>
+ </table>
+
+ <p>In example 5, the loggers<code>root</code>.<code>X</code>, and
+ <code>X.Y</code>
+ each
+ have a Configured LoggerConfig with the same name. The logger
+ <code>X.YZ</code>
+ does not have configured LoggerConfig and so gets its Level from the
LoggerConfig
+ assigned to it,<code>X</code>, since it is the LoggerCofnig whose
name has the
+ longest match to the start of the Logger's name. It is not
associated with LoggerConfig
+ <code>X.Y</code>
+ since tokens after periods must match exactly.
+ </p>
+ <p>The table below provides illustrates how Level filtering works. Im
the table, the vertical
+ header shows the Level of the LogEvent, while the horizontal header
shows the Level associated
+ 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%">
+ <tr>
+ <th style="background-color:cyan; color:black" rowspan="2">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">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>
+ </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="../log4j2-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 pased to a LoggerConfig
+ but before calling any Appenders, 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="../log4j2-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="../log4j2-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>
+ <p>
+ <a name="additivity"/>
<table bgcolor="#EEEE99">
<tr>
<td>
<dl>
- <dt><b>Named Hierarchy</b></dt>
+ <dt><b>Appender Additivity</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>
+ <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>For example, the LoggerConfig named <code>"com.foo"</code> is a
parent
- of the LoggerConfig named <code>"com.foo.Bar"</code>. Similarly,
- <code>"java"</code> is a parent of <code>"java.util"</code> and
an
- ancestor of <code>"java.util.Vector"</code>. This naming scheme
- should be familiar to most developers.
- </p>
-
- <p>The root logger resides at the top of the logger hierarchy. It
- is exceptional in that it always exists and it is part of every
hierarchy. It can
- be obtained as follows:
- <source>Logger logger =
LogManager.getLogger(LogManager.ROOT_LOGGER_NAME);</source>
- </p>
- <h4>LoggerContext</h4>
-
- <h4>Configuration</h4>
-
- <h4>Logger</h4>
-
- <h5>Log Levels</h5>
-
- <h4>LoggerConfig</h4>
+ </p>
- <h4>Filter</h4>
+ <p>The table below shows an example:</p>
- <h4>Appender</h4>
-
- <h4>Layout</h4>
-
- <h4>StrSubstitutor and StrLookup</h4>
+ <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>
+ <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
+ <a
href="../log4j2-core/apidocs/org/apache/logging/log4j/core/Layout.html">Layout</a>
+ with an Appender. The Layout is responsible for formatting the
LogEvent according to the user's
+ wishes, whereas an appender takes care of sending the formatted
output to its destination.
+ The <a
href="../log4j2-core/apidocs/org/apache/logging/log4j/core/layout/PatternLayout.html">PatternLayout</a>,
+ part of the standard log4j distribution, lets the user specify the
output
+ format according to conversion patterns similar to the C language
<code>printf</code> function.
+ </p>
+
+ <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>
+ </p>
+
+ <p>The first field is the number of milliseconds elapsed since the
+ start of the program. The second field is the thread making the log
+ request. The third field is the level of the log statement. The
+ fourth field is the name of the logger associated with the log
+ request. The text after the '-' is the message of the statement.
+ </p>
+
+ <p>Just as importantly, log4j will render the content of the log
+ message according to user specified criteria. For example, if you
+ frequently need to log <code>Oranges</code>, an object type used in
+ your current project, then you can create an OrangeMessage that
accepts an
+ Orange instance and pass that to Log4J so that the Orange object can
+ be formatted into an appropriate byte array when required.
+ </p>
+
+ <h4>StrSubstitutor and StrLookup</h4>
+ <p>The
+ <a
href="../log4j/log4j2-core/apidocs/org/apache/logging/log4j/core/lookup/StrSubstitutor.html">
+ StrSubstitutor
+ </a>
+ class and
+ <a
href="../log4j/log4j2-core/apidocs/org/apache/logging/log4j/core/lookup/StrLookup.html">StrLookup</a>
+ interface were borrowed from Apache Commons Lang and then modified
to support evaluating LogEvents. In
+ addition the
+ <a
href="../log4j/log4j2-core/apidocs/org/apache/logging/log4j/core/lookup/Interpolator.html">Interpolator</a>
+ class was borrowed from Apache Commons Configuration to allow the
StrSubstitutor to evaluate variables
+ that from multiple StrLookups. It too was modified to support
evaluating LogEvents. Together these
+ provide a mechanism to allow the configuration to reference
variables coming from System Properties,
+ the configuration file, the ThreadContext Map, StructuredData in the
LogEvent. The variables can
+ either be resolved when the configuration is processed or as each
event is processed, if the component
+ is capable of handling it. See
+ <a href="lookups.html">Lookups</a>
+ for more information.
+ </p>
- </subsection>
+ </subsection>
- </section>
- </body>
+ </section>
+ </body>
</document>
\ No newline at end of file
