Author: rgoers
Date: Fri Nov 11 06:53:32 2011
New Revision: 1200749
URL: http://svn.apache.org/viewvc?rev=1200749&view=rev
Log:
Finished adding all the appenders
Modified:
logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/index.xml
logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/appenders.xml
Modified:
logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/index.xml
URL:
http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/index.xml?rev=1200749&r1=1200748&r2=1200749&view=diff
==============================================================================
---
logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/index.xml
(original)
+++
logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/index.xml
Fri Nov 11 06:53:32 2011
@@ -23,7 +23,7 @@
</properties>
<body>
- <section name="Log4j 2.0 Guide">
+ <section name="About Log4j 2.0">
<p>
Log4Jj 2.0 is an upgrade to Log4j that provides significant
improvements over its predecessor, Log4j
@@ -39,9 +39,9 @@
what classes and methods they can use with compatibility being
assured while allowing
improvements to be made to the implementation.
</p>
- <h3>Faster Implementation</h3>
+ <h3>Improved Performance</h3>
<p>
- Faster implementation than Log4j 1.x in critical areas and
similar performance to Logback in
+ Faster performance than Log4j 1.x in critical areas and similar
performance to Logback in
most circumstances.
</p>
<h3>Support for multiple APIs</h3>
@@ -63,10 +63,18 @@
</p>
<h3>Plugin Architecture</h3>
<p>
- All components that can be configured are defined as Log4j
plugins. As such, no Log4j code must
- be changed to create a new Appender, Layout, Pattern Converter,
etc. Log4j will automatically
+ All configurable components are defined as Log4j plugins. As
such, no Log4j code must be changed to
+ create a new Appender, Layout, Pattern Converter, etc. Log4j
will automatically
recognize properly defined plugins and use them when they are
referenced in the configuration.
</p>
+ <h3>Property Support</h3>
+ <p>
+ Properties can be referenced in the configuration and either be
directly replace or passed to the
+ underlying component where they can be dynamically resolved.
Properties can 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>
Modified:
logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/appenders.xml
URL:
http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/appenders.xml?rev=1200749&r1=1200748&r2=1200749&view=diff
==============================================================================
---
logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/appenders.xml
(original)
+++
logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/appenders.xml
Fri Nov 11 06:53:32 2011
@@ -45,7 +45,6 @@
<p>
Appenders always have a name so that they can be referenced from
Loggers.
</p>
- <a name="ConsoleAppender"/>
<subsection name="ConsoleAppender">
<p>
As one might expect, the ConsoleAppender writes its output to
either System.err or System.out with System.err
@@ -96,7 +95,7 @@
<PatternLayout pattern="%m%n"/>
</Console>
</appenders>
- <loggers
+ <loggers>
<root level="error">
<appender-ref ref="STDOUT"/>
</root>
@@ -105,7 +104,6 @@
]]></source>
</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>
@@ -116,11 +114,6 @@
<th>Description</th>
</tr>
<tr>
- <td>config</td>
- <td>Configuration</td>
- <td>Passed automatically by the Configuration, allows the
Appender access to configuration information.</td>
- </tr>
- <tr>
<td>filter</td>
<td>Filter</td>
<td>A Filter to determine if the event should be handled by this
Appender. More than one Filter
@@ -176,7 +169,7 @@
</Failovers>
</Failover>
</appenders>
- <loggers
+ <loggers>
<root level="error">
<appender-ref ref="Failover"/>
</root>
@@ -185,7 +178,6 @@
]]></source>
</p>
</subsection>
- <a name="FileAppender"/>
<subsection name="FileAppender">
<p>The FileAppender is an OutputStreamAppender that writes to the
File named in the fileName parameter. The
FileAppender uses a FileManager (which extends
OutputStreamManager) to actually perform the file I/O. While
@@ -231,6 +223,11 @@
to disk but could impact performance.</td>
</tr>
<tr>
+ <td>layout</td>
+ <td>Layout</td>
+ <td>The Layout to use to format the LogEvent</td>
+ </tr>
+ <tr>
<td>locking</td>
<td>boolean</td>
<td>When set to true, I/O operations will occur only while the
file lock is held allowing FileAppenders
@@ -265,7 +262,7 @@
</PatternLayout>
</File>
</appenders>
- <loggers
+ <loggers>
<root level="error">
<appender-ref ref="MyFile"/>
</root>
@@ -274,7 +271,6 @@
]]></source>
</p>
</subsection>
- <a name="FlumeAvroAppender"/>
<subsection name="FlumeAvroAppender">
<p><a href="http://incubator.apache.org/projects/flume.html";>Apache
Flume</a> is a distributed, reliable,
and available system for efficiently collecting, aggregating, and
moving large amounts of log data
@@ -322,6 +318,11 @@
FlumeAvroAppender itself.</td>
</tr>
<tr>
+ <td>layout</td>
+ <td>Layout</td>
+ <td>The Layout to use to format the LogEvent. If no layout is
specified RFC5424Layout will be used.</td>
+ </tr>
+ <tr>
<td>mdcExcludes</td>
<td>String</td>
<td>A comma separated list of mdc keys that should be excluded
from the FlumeEvent. This is mutually
@@ -379,7 +380,7 @@
<RFC5424Layout enterpriseNumber="18060" includeMDC="true"
appName="MyApp"/>
</Flume>
</appenders>
- <loggers
+ <loggers>
<root level="error">
<appender-ref ref="eventLogger"/>
</root>
@@ -388,7 +389,6 @@
]]></source>
</p>
</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%">
@@ -400,12 +400,17 @@
<tr>
<td>factoryBindingName</td>
<td>String</td>
- <td></td>
+ <td>The name to locate in the Context that provides the
+ <a
href="http://download.oracle.com/javaee/5/api/javax/jms/QueueConnectionFactory.html";>QueueConnectionFactory</a>.</td>
</tr>
<tr>
<td>factoryName</td>
<td>String</td>
- <td></td>
+ <td>The fully qualified class name that should be used to define
the Initial Context Factory as
+ defined in <a
href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#INITIAL_CONTEXT_FACTORY";>INITIAL_CONTEXT_FACTORY</a>.
+ If no value is provided the
+ default InitialContextFactory will be used. If a factoryName
is specified without a providerURL
+ a warning message will be logged as this is likely to cause
problems.</td>
</tr>
<tr>
<td>filter</td>
@@ -414,6 +419,11 @@
may be used by using a CompositeFilter.</td>
</tr>
<tr>
+ <td>layout</td>
+ <td>Layout</td>
+ <td>The Layout to use to format the LogEvent. If no layout is
specified SerializedLayout will be used.</td>
+ </tr>
+ <tr>
<td>name</td>
<td>String</td>
<td>The name of the Appender.</td>
@@ -421,27 +431,33 @@
<tr>
<td>password</td>
<td>String</td>
- <td></td>
+ <td>The password to use to create the queue connection.</td>
</tr>
<tr>
<td>providerURL</td>
<td>String</td>
- <td></td>
+ <td>The URL of the provider to use as defined by
+ <a
href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#PROVIDER_URL";>PROVIDER_URL</a>.
+ If this value is null the default system provider will be
used.</td>
</tr>
<tr>
<td>queueBindingName</td>
<td>String</td>
- <td></td>
+ <td>The name to use to locate the <a
href="http://download.oracle.com/javaee/5/api/javax/jms/Queue.html";>Queue</a>.</td>
</tr>
<tr>
<td>securityPrincipalName</td>
<td>String</td>
- <td></td>
+ <td>The name of the identity of the Principal as specified by
+ <a
href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#SECURITY_PRINCIPAL";>SECURITY_PRINCIPAL</a>.
+ If a securityPrincipalName is specified without
securityCredentials a warning message will be
+ logged as this is likely to cause problems.</td>
</tr>
<tr>
<td>securityCredentials</td>
<td>String</td>
- <td></td>
+ <td>The security credentials for the principal as specified by
+ <a
href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#SECURITY_CREDENTIALS";>SECURITY_CREDENTIALS</a>.</td>
</tr>
<tr>
<td>suppressExceptions</td>
@@ -452,12 +468,14 @@
<tr>
<td>urlPkgPrefixes</td>
<td>String</td>
- <td></td>
+ <td>A colon-separated list of package prefixes for the class
name of the factory class that will create
+ a URL context factory as defined by
+ <a
href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#URL_PKG_PREFIXES";>URL_PKG_PREFIXES</a>.</td>
</tr>
<tr>
<td>userName</td>
<td>String</td>
- <td></td>
+ <td>The user id used to create the queue connection.</td>
</tr>
<caption align="top">JMSQueueAppender Parameters</caption>
</table>
@@ -467,22 +485,125 @@
<source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
<appenders>
- <JMSQueue name="jms" fileName="logs/app.log">
- <PatternLayout>
- <pattern>%d %p %C{1.} [%t] %m%n</pattern>
- </PatternLayout>
- </JMSQueue>
+ <JMSQueue name="jmsQueue" queueBindingName="MyQueue"
factoryBindingName="MyQueueConnectionFactory"/>
</appenders>
- <loggers
+ <loggers>
<root level="error">
- <appender-ref ref="MyFile"/>
+ <appender-ref ref="jmsQueue"/>
+ </root>
+ </loggers>
+</configuration>
+ ]]></source>
+ </p>
+ </subsection>
+ <subsection name="JMSTopicAppender">
+ <p>The JMSTopicAppender sends the formatted log event to a JMS
Topic.</p>
+ <table border="1" width="100%">
+ <tr>
+ <th>Parameter Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>factoryBindingName</td>
+ <td>String</td>
+ <td>The name to locate in the Context that provides the
+ <a
href="http://download.oracle.com/javaee/5/api/javax/jms/TopicConnectionFactory.html";>TopicConnectionFactory</a>.</td>
+ </tr>
+ <tr>
+ <td>factoryName</td>
+ <td>String</td>
+ <td>The fully qualified class name that should be used to define
the Initial Context Factory as
+ defined in <a
href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#INITIAL_CONTEXT_FACTORY";>INITIAL_CONTEXT_FACTORY</a>.
+ If no value is provided the
+ default InitialContextFactory will be used. If a factoryName
is specified without a providerURL
+ a warning message will be logged as this is likely to cause
problems.</td>
+ </tr>
+ <tr>
+ <td>filter</td>
+ <td>Filter</td>
+ <td>A Filter to determine if the event should be handled by this
Appender. More than one Filter
+ may be used by using a CompositeFilter.</td>
+ </tr>
+ <tr>
+ <td>layout</td>
+ <td>Layout</td>
+ <td>The Layout to use to format the LogEvent. If no layout is
specified SerializedLayout will be used.</td>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>String</td>
+ <td>The name of the Appender.</td>
+ </tr>
+ <tr>
+ <td>password</td>
+ <td>String</td>
+ <td>The password to use to create the queue connection.</td>
+ </tr>
+ <tr>
+ <td>providerURL</td>
+ <td>String</td>
+ <td>The URL of the provider to use as defined by
+ <a
href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#PROVIDER_URL";>PROVIDER_URL</a>.
+ If this value is null the default system provider will be
used.</td>
+ </tr>
+ <tr>
+ <td>topicBindingName</td>
+ <td>String</td>
+ <td>The name to use to locate the
+ <a
href="http://download.oracle.com/javaee/5/api/javax/jms/Topic.html";>Topic</a>.</td>
+ </tr>
+ <tr>
+ <td>securityPrincipalName</td>
+ <td>String</td>
+ <td>The name of the identity of the Principal as specified by
+ <a
href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#SECURITY_PRINCIPAL";>SECURITY_PRINCIPAL</a>.
+ If a securityPrincipalName is specified without
securityCredentials a warning message will be
+ logged as this is likely to cause problems.</td>
+ </tr>
+ <tr>
+ <td>securityCredentials</td>
+ <td>String</td>
+ <td>The security credentials for the principal as specified by
+ <a
href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#SECURITY_CREDENTIALS";>SECURITY_CREDENTIALS</a>.</td>
+ </tr>
+ <tr>
+ <td>suppressExceptions</td>
+ <td>boolean</td>
+ <td>The default is true, causing exceptions to be internally
logged and then ignored. When set to
+ false exceptions will be percolated to the caller.</td>
+ </tr>
+ <tr>
+ <td>urlPkgPrefixes</td>
+ <td>String</td>
+ <td>A colon-separated list of package prefixes for the class
name of the factory class that will create
+ a URL context factory as defined by
+ <a
href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#URL_PKG_PREFIXES";>URL_PKG_PREFIXES</a>.</td>
+ </tr>
+ <tr>
+ <td>userName</td>
+ <td>String</td>
+ <td>The user id used to create the queue connection.</td>
+ </tr>
+ <caption align="top">JMSTopicAppender Parameters</caption>
+ </table>
+ <p>
+ Here is a sample JMSTopicAppender configuration:
+
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="warn" name="MyApp" packages="">
+ <appenders>
+ <JMSTopic name="jmsTopic" topicBindingName="MyTopic"
factoryBindingName="MyTopicConnectionFactory"/>
+ </appenders>
+ <loggers>
+ <root level="error">
+ <appender-ref ref="jmsQueue"/>
</root>
</loggers>
</configuration>
]]></source>
</p>
</subsection>
- <a name="OutputStreamAppender"/>
<subsection name="OutputStreamAppender">
The OutputStreamAppender provides the base for many of the other
Appenders such as the File and Socket
appenders that write the event to an Output Stream. It cannot be
directly configured. Support for
@@ -490,35 +611,600 @@
OutputStreamManager to handle the actual I/O, allowing the stream to
be shared by Appenders in multiple
configurations.
</subsection>
- <a name="JMSTopicAppender"/>
- <subsection name="JMSTopicAppender">
-
- </subsection>
- <a name="RewriteAppender"/>
<subsection name="RewriteAppender">
+ <p>
+ The RewriteAppender allows the LogEvent to manipulated before it
is processed by another Appender. This
+ can be used to mask sensitive information such as passwords or to
inject information into each event.
+ The RewriteAppender must be configured with a <a
href="RewritePolicy">RewritePolicy</a>.
+ </p>
+ <table border="1" width="100%">
+ <tr>
+ <th>Parameter Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>appender-ref</td>
+ <td>String</td>
+ <td>The name of the Appender to call after the LogEvent has been
manipulated.</td>
+ </tr>
+ <tr>
+ <td>filter</td>
+ <td>Filter</td>
+ <td>A Filter to determine if the event should be handled by this
Appender. More than one Filter
+ may be used by using a CompositeFilter.</td>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>String</td>
+ <td>The name of the Appender.</td>
+ </tr>
+ <tr>
+ <td>rewritePolicy</td>
+ <td>RewritePolciy</td>
+ <td>The RewritePolicy that will manipulate the LogEvent.</td>
+ </tr>
+ <tr>
+ <td>suppressExceptions</td>
+ <td>boolean</td>
+ <td>The default is true, causing exceptions to be internally
logged and then ignored. When set to
+ false exceptions will be percolated to the caller.</td>
+ </tr>
+ <caption align="top">RewriteAppender Parameters</caption>
+ </table>
+ <h4>RewritePolicy</h4>
+ <p>
+ RewritePolicy is an interface that allows implementations to
inspect and possibly modify LogEvents
+ before they are passed to Appender. RewritePolicy declares a
single method named rewrite that must
+ be implemented. The method is passed the LogEvent and can return
the same event or create a new one.
+ </p>
+ <h5>MapRewritePolicy</h5>
+ <p>
+ MapRewritePolicy will evaluate LogEvents that contain a
MapMessage and will add or update
+ elements of the Map.
+ </p>
+ <table border="1" width="100%">
+ <tr>
+ <th>Parameter Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>mode</td>
+ <td>String</td>
+ <td>"Add" or "Update"</td>
+ </tr>
+ <tr>
+ <td>keyValuePair</td>
+ <td>KeyValuePair[]</td>
+ <td>An array of keys and their values.</td>
+ </tr>
+ </table>
+ <p>
+ 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"?>
+<configuration status="warn" name="MyApp" packages="">
+ <appenders>
+ <Console name="STDOUT" target="SYSTEM_OUT">
+ <PatternLayout pattern="%m%n"/>
+ </Console>
+ <Rewrite name="rewrite">
+ <appender-ref ref="STDOUT"/>
+ <MapRewritePolicy mode="Add">
+ <KeyValuePair key="product" value="TestProduct"/>
+ </MapRewritePolicy>
+ </Rewrite>
+ </appenders>
+ <loggers>
+ <root level="error">
+ <appender-ref ref="Rewrite"/>
+ </root>
+ </loggers>
+</configuration>
+ ]]></source>
+ </p>
</subsection>
- <a name="RollingFileAppender"/>
<subsection name="RollingFileAppender">
+ <p>The RollingFileAppender is an OutputStreamAppender that writes to
the File named in the fileName parameter
+ and rolls the file over according the TriggeringPolicy and the
RolloverPolicy. The
+ RollingFileAppender uses a RollingFileManager (which extends
OutputStreamManager) to actually perform the
+ file I/O and perform the rollover. While RolloverFileAppenders
from different Configurations cannot be
+ shared, the RollingFileManagers 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>
+ <p>
+ A RollingFileAppender requires a <a
href="#TriggeringPolicies">TriggeringPolicy</a> and a
+ <a href="#RolloverStrategies">RolloverStrategy</a>. The triggering
policy determines if a rollover should
+ be performed while the RolloverStrategy defines how the rollover
should be done. If no RolloverStrategy
+ is configured, RollingFileAppender will use the <a
href="DefaultRolloverStrategy">DefaultRolloverStrategy</a>.
+ </p>
+ <p>
+ File locking is not supported by the RollingFileAppender.
+ </p>
+ <table border="1" width="100%">
+ <tr>
+ <th>Parameter Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>append</td>
+ <td>boolean</td>
+ <td>When true - the default, records will be appended to the end
of the file. When set to false,
+ the file will be cleared before new reocrds are written.</td>
+ </tr>
+ <tr>
+ <td>bufferedIO</td>
+ <td>boolean</td>
+ <td>When true - the default, records will be written to a buffer
and the data will be written to
+ disk when the buffer is full or, if immediateFlush is set,
when the record is written.
+ File locking cannot be used with bufferedIO. Performance tests
have shown that using buffered I/O
+ significantly improves performance, even if immediateFlush is
enabled.</td>
+ </tr>
+ <tr>
+ <td>filter</td>
+ <td>Filter</td>
+ <td>A Filter to determine if the event should be handled by this
Appender. More than one Filter
+ may be used by using a CompositeFilter.</td>
+ </tr>
+ <tr>
+ <td>fileName</td>
+ <td>String</td>
+ <td>The name of the file to write to. If the file, or any of its
parent directories, do not exist,
+ they will be created.</td>
+ </tr>
+ <tr>
+ <td>filePattern</td>
+ <td>String</td>
+ <td>The pattern of the file name of the archived log file. The
format of the pattern should is
+ dependent on the RolloverPolicy that is used. The
DefaultRolloverPolicy will accept both
+ a date/time pattern compatible with
+ <a
href="http://download.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html";>SimpleDateFormat</a>
+ and and/or a %d which represents an integer counter.</td>
+ </tr>
+ <tr>
+ <td>immediateFlush</td>
+ <td>boolean</td>
+ <td>When set to true, each write will be followed by a flush.
This will guarantee the data is written
+ to disk but could impact performance.</td>
+ </tr>
+ <tr>
+ <td>layout</td>
+ <td>Layout</td>
+ <td>The Layout to use to format the LogEvent</td>
+ </tr>
+
+ <tr>
+ <td>name</td>
+ <td>String</td>
+ <td>The name of the Appender.</td>
+ </tr>
+ <tr>
+ <td>policy</td>
+ <td>TriggeringPolicy</td>
+ <td>The policy to use to determine if a rollover should
occur.</td>
+ </tr>
+ <tr>
+ <td>strategy</td>
+ <td>RolloverStrategy</td>
+ <td>The strategy to use to determine the name and location of
the archive file.</td>
+ </tr>
+ <tr>
+ <td>suppressExceptions</td>
+ <td>boolean</td>
+ <td>The default is true, causing exceptions to be internally
logged and then ignored. When set to
+ false exceptions will be percolated to the caller.</td>
+ </tr>
+ <caption align="top">RollingFileAppender Parameters</caption>
+ </table>
+ <a name="TriggeringPolicies"/>
<h4>Triggering Policies</h4>
<h5>Composite Triggering Policy</h5>
+ <p>
+ The CompositeTriggeringPolicy combines multiple triggering
policies and returns true if any
+ of the configured policies return true. The
CompositeTriggeringPolicy is configured simply
+ by wrapping other policies in a "Policies" element.
+ </p>
<h5>OnStartup Triggering Policy</h5>
+ <p>
+ The OnStartup policy takes no parameters and causes a rollover
if the log file is older than the
+ current JVM's start time.
+ </p>
<h5>SizeBased Triggering Policy</h5>
+ <p>
+ Causes a rollover once the file has reached the specified
size. The size can be specified in bytes,
+ KB, MB or GB.
+ </p>
<h5>TimeBased Triggering Policy</h5>
+ <p>
+ Causes a rollover once the date/time pattern no longer applies
to the active file. This policy
+ takes no parameters.
+ </p>
+ <a name="RolloverStrategies"/>
<h4>Rollover Strategies</h4>
+ <a name="DefaultRolloverStrategy"/>
<h5>Default Rollover Strategy</h5>
+ <p>
+ The default rollover strategy accepts both a date/time pattern
and an integer. If the date/time pattern
+ is present it will be replaced with the current date and time
values. If the pattern contains an integer
+ it will be incremented on each rollover. If the pattern
contains both a date/time and integer
+ in the pattern the integer will be incremented until the
result of the date/time pattern changes. If
+ the file pattern ends with ".gz" or ".zip" the resulting
archive will be compressed using the
+ compression scheme that matches the suffix.
+ </p>
+ <table border="1" width="100%">
+ <tr>
+ <th>Parameter Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>min</td>
+ <td>integer</td>
+ <td>The minimum value of the counter. The default value is
1.</td>
+ </tr>
+ <tr>
+ <td>max</td>
+ <td>integer</td>
+ <td>The maximum value of the counter. Once this values is
reached. Older archives will be
+ deleted on subsequent rollovers.</td>
+ </tr>
+ <caption align="top">DefaultRolloverStrategy
Parameters</caption>
+ </table>
+ <p>
+ Below is a sample configuration that uses a RollingFileAppender
with both the time and size based
+ triggering policies, will create up to 7 archives on the same day
(1-7), and will compress each
+ archive using gzip:
+
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="warn" name="MyApp" packages="">
+ <appenders>
+ <RollingFile name="RollingFile" fileName="logs/app.log"
filePattern="logs/app-%d{MM-dd-yyyy}-%d.log.gz">
+ <PatternLayout>
+ <pattern>%d %p %C{1.} [%t] %m%n</pattern>
+ </PatternLayout>
+ <Policies>
+ <TimeBasedTriggeringPolicy />
+ <SizeBasedTriggeringPolicy size="250 MB"/>
+ </Policies>
+ </RollingFile>
+ </appenders>
+ <loggers>
+ <root level="error">
+ <appender-ref ref="RollingFile"/>
+ </root>
+ </loggers>
+</configuration>
+ ]]></source>
+ </p>
</subsection>
- <a name="RoutingAppender"/>
<subsection name="RoutingAppender">
+ <p>
+ The RoutingAppender evaluates LogEvents and then routes them to a
subordinate Appender. The target
+ Appender may be an appender previously configured and may be
referenced by its name or the
+ Appender can be dynamically created as needed.
+ </p>
+ <table border="1" width="100%">
+ <tr>
+ <th>Parameter Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>filter</td>
+ <td>Filter</td>
+ <td>A Filter to determine if the event should be handled by this
Appender. More than one Filter
+ may be used by using a CompositeFilter.</td>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>String</td>
+ <td>The name of the Appender.</td>
+ </tr>
+ <tr>
+ <td>rewritePolicy</td>
+ <td>RewritePolciy</td>
+ <td>The RewritePolicy that will manipulate the LogEvent.</td>
+ </tr>
+ <tr>
+ <td>routes</td>
+ <td>Routes</td>
+ <td>Contains one or more Route declarations to identify the
criteria for choosing Appenders.</td>
+ </tr>
+ <tr>
+ <td>suppressExceptions</td>
+ <td>boolean</td>
+ <td>The default is true, causing exceptions to be internally
logged and then ignored. When set to
+ false exceptions will be percolated to the caller.</td>
+ </tr>
+ <caption align="top">RoutingAppender Parameters</caption>
+ </table>
+ <h4>Routes</h4>
+ <p>
+ The Routes element accepts a single, required attribute named
"pattern". The pattern is evaluated
+ against all the registered Lookups and the result is used to
select a Route. Each Route may be
+ configured with a key. If the key matches the result of
evaluating the pattern then that Route
+ will be selected. If no key is specified on a Route then that
Route is the default. Only one Route
+ can be configured as the default.
+ </p>
+ <p>
+ Each Route must reference an Appender. If the Route contains an
appender-ref attribute then the
+ Route will reference an Appender that was defined in the
configuration. If the Route contains an
+ Appender definition then an Appender will be created within the
context of the RoutingAppender and
+ will be reused each time a matching Appender name is referenced
through a Route.
+ </p>
+ <p>
+ Below is a sample configuration that uses a RoutingFileAppender to
route all Audit events to
+ a FlumeAppender and all other events will be routed to a
RollingFileAppender that captures only
+ the specific event type. Note that the AuditAppender was
predefined while the RoutingFileAppenders
+ are created as needed.
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="warn" name="MyApp" packages="">
+ <appenders>
+ <Flume name="AuditLogger" suppressExceptions="false" compress="true">
+ <Agent host="192.168.10.101" port="8800"/>
+ <Agent host="192.168.10.102" port="8800"/>
+ <RFC5424Layout enterpriseNumber="18060" includeMDC="true"
appName="MyApp"/>
+ </Flume>
+ <Routing name="Routing">
+ <Routes pattern="$${sd:type}">
+ <Route>
+ <RollingFile name="Rolling-${sd:type}" fileName="${sd:type}.log"
+ filePattern="${sd:type}.%i.log.gz">
+ <PatternLayout>
+ <pattern>%d %p %C{1.} [%t] %m%n</pattern>
+ </PatternLayout>
+ <SizeBasedTriggeringPolicy size="500" />
+ </RollingFile>
+ </Route>
+ <Route appender-ref="AuditLogger" key="Audit"/>
+ </Routes>
+ </Routing>
+ </appenders>
+ <loggers>
+ <root level="error">
+ <appender-ref ref="Routing"/>
+ </root>
+ </loggers>
+</configuration>
+ ]]></source>
+ </p>
</subsection>
- <a name="SocketAppender"/>
<subsection name="SocketAppender">
-
+ <p>
+ The SocketAppender is an OutputStreamAppender that writes its
output to a remote destination
+ specified by a host and port. The data can be sent over either TCP
or UDP and can be sent in any format.
+ The default format is to send a Serialized LogEvent. Log4j 2.0
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%">
+ <tr>
+ <th>Parameter Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>filter</td>
+ <td>Filter</td>
+ <td>A Filter to determine if the event should be handled by this
Appender. More than one Filter
+ may be used by using a CompositeFilter.</td>
+ </tr>
+ <tr>
+ <td>host</td>
+ <td>String</td>
+ <td>The name or address of the system that is listening for log
events. This parameter is required.</td>
+ </tr>
+ <tr>
+ <td>immediateFlush</td>
+ <td>boolean</td>
+ <td>When set to true, each write will be followed by a flush.
This will guarantee the data is written
+ to disk but could impact performance.</td>
+ </tr>
+ <tr>
+ <td>layout</td>
+ <td>Layout</td>
+ <td>The Layout to use to format the LogEvent. The default is
SerializedLayout.</td>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>String</td>
+ <td>The name of the Appender.</td>
+ </tr>
+ <tr>
+ <td>port</td>
+ <td>integer</td>
+ <td>The port on the host that is listening for log events. This
parameter must be specified.</td>
+ </tr>
+ <tr>
+ <td>protocol</td>
+ <td>String</td>
+ <td>"TCP" or "UDP". This parameter is required.</td>
+ </tr>
+ <tr>
+ <td>reconnectionDelay</td>
+ <td>integer</td>
+ <td>If set to a value greater than 0, after an error the
SocketManager will attempt to reconnect to
+ the server after waiting the specified number of milliseconds.
If the reconnect fails then
+ an exception will be thrown (which can be caught by the
application if suppressExceptions is
+ set to false).</td>
+ </tr>
+ <tr>
+ <td>suppressExceptions</td>
+ <td>boolean</td>
+ <td>The default is true, causing exceptions to be internally
logged and then ignored. When set to
+ false exceptions will be percolated to the caller.</td>
+ </tr>
+ <caption align="top">SocketAppender Parameters</caption>
+ </table>
</subsection>
- <a name="SyslogAppender"/>
<subsection name="SyslogAppender">
+ <p>
+ The SyslogAppender is a SocketAppender that writes its output to a
remote destination
+ 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%">
+ <tr>
+ <th>Parameter Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>appName</td>
+ <td>String</td>
+ <td>The value to use as the APP-NAME in the RFC 5424 syslog
record.</td>
+ </tr>
+ <tr>
+ <td>charset</td>
+ <td>String</td>
+ <td>The character set to use when converting the syslog String
to a byte array. The String must be
+ a valid <a
href="http://download.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html";>Charset</a>.
+ If not specified, the default system Charset will be used.</td>
+ </tr>
+ <tr>
+ <td>enterpriseNumber</td>
+ <td>integer</td>
+ <td>The IANA enterprise number as described in
+ <a href="http://tools.ietf.org/html/rfc5424#section-7.2.2";>RFC
5424</a></td>
+ </tr>
+ <tr>
+ <td>filter</td>
+ <td>Filter</td>
+ <td>A Filter to determine if the event should be handled by this
Appender. More than one Filter
+ may be used by using a CompositeFilter.</td>
+ </tr>
+ <tr>
+ <td>facility</td>
+ <td>String</td>
+ <td>The facility is used to try to classify the message. The
facility option must be set to one of
+ "KERN", "USER", "MAIL", "DAEMON", "AUTH", "SYSLOG", "LPR",
"NEWS", "UUCP", "CRON", "AUTHPRIV",
+ "FTP", "NTP", "AUDIT", "ALERT", "CLOCK", "LOCAL0", "LOCAL1",
"LOCAL2", "LOCAL3", "LOCAL4", "LOCAL5",
+ "LOCAL6", or "LOCAL7". These values may be specified as upper
or lower case characters.</td>
+ </tr>
+ <tr>
+ <td>format</td>
+ <td>String</td>
+ <td>If set to "RFC5424" the data will be formatted in accordance
with RFC 5424. Otherwise, it will
+ be formatted as a BSD Syslog record. Note that although BSD
Syslog records are required to be
+ 1024 bytes or shorter the SyslogLayout does not truncate them.
The RFC5424Layout also does not
+ truncate records since the receiver must accept records of up
to 2048 bytes and may accept records
+ that are longer.</td>
+ </tr>
+ <tr>
+ <td>host</td>
+ <td>String</td>
+ <td>The name or address of the system that is listening for log
events. This parameter is required.</td>
+ </tr>
+ <tr>
+ <td>id</td>
+ <td>String</td>
+ <td>The default structured data id to use when formatting
according to RFC 5424. If the LogEvent contains
+ a StructuredDataMessage the id from the Message will be used
instead of this value.</td>
+ </tr>
+ <tr>
+ <td>immediateFlush</td>
+ <td>boolean</td>
+ <td>When set to true, each write will be followed by a flush.
This will guarantee the data is written
+ to disk but could impact performance.</td>
+ </tr>
+ <tr>
+ <td>includeMDC</td>
+ <td>boolean</td>
+ <td>Indicates whether data from the ThreadContextMap will be
included in the RFC 5424 Syslog record.
+ Defaults to true.</td>
+ </tr>
+ <tr>
+ <td>mdcExcludes</td>
+ <td>String</td>
+ <td>A comma separated list of mdc keys that should be excluded
from the LogEvent. This is mutually
+ exclusive with the mdcIncludes attribute. This attribute only
applies to RFC 5424 syslog records.</td>
+ </tr>
+ <tr>
+ <td>mdcIncludes</td>
+ <td>String</td>
+ <td>A comma separated list of mdc keys that should be included
in the FlumeEvent. Any keys in the MDC
+ not found in the list will be excluded. This option is
mutually exclusive with the mdcExcludes
+ attribute. This attribute only applies to RFC 5424 syslog
records.</td>
+ </tr>
+ <tr>
+ <td>mdcRequired</td>
+ <td>String</td>
+ <td>A comma separated list of mdc keys that must be present in
the MDC. If a key is not present a
+ LoggingException will be thrown. This attribute only applies
to RFC 5424 syslog records.</td>
+ </tr>
+ <tr>
+ <td>mdcPrefix</td>
+ <td>String</td>
+ <td>A string that should be prepended to each MDC key in order
to distinguish it from event attributes.
+ The default string is "mdc:". This attribute only applies to
RFC 5424 syslog records.</td>
+ </tr>
+ <tr>
+ <td>messageId</td>
+ <td>String</td>
+ <td>The default value to be used in the MSGID field of RFC 5424
syslog records. </td>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>String</td>
+ <td>The name of the Appender.</td>
+ </tr>
+ <tr>
+ <td>newLine</td>
+ <td>boolean</td>
+ <td>If true, a newline will be appended to the end of the syslog
record. The default is false.</td>
+ </tr>
+ <tr>
+ <td>port</td>
+ <td>integer</td>
+ <td>The port on the host that is listening for log events. This
parameter must be specified.</td>
+ </tr>
+ <tr>
+ <td>protocol</td>
+ <td>String</td>
+ <td>"TCP" or "UDP". This parameter is required.</td>
+ </tr>
+ <tr>
+ <td>reconnectionDelay</td>
+ <td>integer</td>
+ <td>If set to a value greater than 0, after an error the
SocketManager will attempt to reconnect to
+ the server after waiting the specified number of milliseconds.
If the reconnect fails then
+ an exception will be thrown (which can be caught by the
application if suppressExceptions is
+ set to false).</td>
+ </tr>
+ <tr>
+ <td>suppressExceptions</td>
+ <td>boolean</td>
+ <td>The default is true, causing exceptions to be internally
logged and then ignored. When set to
+ false exceptions will be percolated to the caller.</td>
+ </tr>
+ <caption align="top">SyslogAppender Parameters</caption>
+ </table>
+ <p>
+ 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"?>
+<configuration status="warn" name="MyApp" packages="">
+ <appenders>
+ <Syslog name="bsd" host="localhost" port="514" protocol="TCP"/>
+ <Syslog name="RFC5424" format="RFC5424" host="localhost" port="8514"
protocol="TCP" appName="MyApp" includeMDC="true"
+ facility="LOCAL0" enterpriseNumber="18060" newLine="true"
messageId="Audit" id="App"/>
+ </appenders>
+ <loggers>
+ <logger name="com.mycorp" level="error">
+ <appender-ref ref="RFC5424"/>
+ </logger>
+ <root level="error">
+ <appender-ref ref="bsd"/>
+ </root>
+ </loggers>
+</configuration>
+ ]]></source>
+ </p>
</subsection>
</section>
</body>
