logging-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rgo...@apache.org
Subject svn commit: r1200749 - in /logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc: index.xml manual/appenders.xml
Date Fri, 11 Nov 2011 06:53:33 GMT
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>



Mime
View raw message