Author: rgoers Date: Wed Nov 9 16:51:46 2011 New Revision: 1199841 URL: http://svn.apache.org/viewvc?rev=1199841&view=rev Log: Making progress on Appender documentation
Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/appender/JMSQueueAppender.java logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/pom.xml logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/appenders.xml logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/filters.xml logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/lookups.xml Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/appender/JMSQueueAppender.java URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/appender/JMSQueueAppender.java?rev=1199841&r1=1199840&r2=1199841&view=diff ============================================================================== --- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/appender/JMSQueueAppender.java (original) +++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/appender/JMSQueueAppender.java Wed Nov 9 16:51:46 2011 @@ -64,7 +64,7 @@ public class JMSQueueAppender extends Ap @PluginAttr("userName") String userName, @PluginAttr("password") String password, @PluginElement("layout") Layout layout, - @PluginElement("filters") Filter filter, + @PluginElement("filter") Filter filter, @PluginAttr("suppressExceptions") String suppress) { String name = "JMSQueue" + factoryBindingName + "." + queueBindingName; Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/pom.xml URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/pom.xml?rev=1199841&r1=1199840&r2=1199841&view=diff ============================================================================== --- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/pom.xml (original) +++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/pom.xml Wed Nov 9 16:51:46 2011 @@ -89,8 +89,8 @@ <url>http://www.apache.org</url> </organization> <properties> - <slf4j.version>1.6.1</slf4j.version> - <logback.version>0.9.28</logback.version> + <slf4j.version>1.6.4</slf4j.version> + <logback.version>1.0.0</logback.version> <log4j.parent.dir>${basedir}</log4j.parent.dir> </properties> <dependencyManagement> @@ -116,6 +116,12 @@ <version>${logback.version}</version> </dependency> <dependency> + <groupId>ch.qos.logback</groupId> + <artifactId>logback-classic</artifactId> + <version>${logback.version}</version> + <type>test-jar</type> + </dependency> + <dependency> <groupId>org.apache.logging.rgoers</groupId> <artifactId>log4j2-api</artifactId> <version>${project.version}</version> @@ -196,6 +202,13 @@ <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-site-plugin</artifactId> <version>3.0</version> + <dependencies> + <dependency> + <groupId>org.apache.maven.wagon</groupId> + <artifactId>wagon-ssh</artifactId> + <version>1.0-beta-7</version> + </dependency> + </dependencies> <configuration> <!-- Exclude the navigation file for Maven 1 sites and the changes file used by the changes-plugin, Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml?rev=1199841&r1=1199840&r2=1199841&view=diff ============================================================================== --- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml (original) +++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml Wed Nov 9 16:51:46 2011 @@ -48,11 +48,15 @@ </item> <item name="Appenders" href="/manual/appenders.html" collapse="true"> <item name="Console" href="/manual/appenders.html@ConsoleAppender"/> + <item name="Failover" href="/manual/appenders.html@FailoverAppender"/> <item name="File" href="/manual/appenders.html#FileAppender"/> - <item name="Flume" href="/manual/appenders.html#FlumeAppender"/> + <item name="Flume" href="/manual/appenders.html#FlumeAvroAppender"/> <item name="JMSQueue" href="/manual/appenders.html#JMSQueueAppender"/> <item name="JSMTopic" href="/manual/appenders.html#JMSTopicAppender"/> + <item name="OutputStream" href="/manual/appenders.html#OutputStreamAppender"/> + <item name="Rewrite" href="/manual/appenders.html#RewriteAppender"/> <item name="RollingFile" href="/manual/appenders.html#RollingFileappender"/> + <item name="Routing" href="/manual/appenders.html#RoutingAppender"/> <item name="Socket" href="/manual/appenders.html#SocketAppender"/> <item name="Syslog" href="/manual/appenders.html#SyslogAppender"/> </item> 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=1199841&r1=1199840&r2=1199841&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 Wed Nov 9 16:51:46 2011 @@ -24,28 +24,492 @@ <body> <section name="Appenders"> + <p> + Appenders are the component responsible for delivering LogEvents to their destination. Every Appender must + implement the <a href="../log4j/log4j2-core/apidocs/org/apache/logging/log4j/core/Appender.html">Appender</a> + interface. Most Appenders will extend + <a href="../log4j/log4j2-core/apidocs/org/apache/logging/log4j/core/appender/AppenderBase.html">AppenderBase</a> + which adds <a href="../log4j/log4j2-core/apidocs/org/apache/logging/log4j/core/Lifecycle.html">Lifecycle</a> + and <a href="../log4j/log4j2-core/apidocs/org/apache/logging/log4j/core/filter/Filterable">Filterable</a> + support. Lifecycle allows components to finish initialization after configuration has completed and to + perform cleanup during shutdown. Filterable allows the component to have Filters attached to it which are + evaluated during event processing. + </p> + <p> + Appenders usually are only responsible for writing the event data to the target destination. In most cases + they delegate responsibility for formatting the event to a <a href="../layouts.html">layout</a>. Some + appenders wrap other appenders so that they can modify the LogEvent, handle a failure in an Appender, + route the event to a subordinate Appender based on advanced Filter criteria or provide similar functionality + that does not directly format the event for viewing. + </p> + <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 + being the default target. A Layout must be provided to format the LogEvent. + </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>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>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>target</td> + <td>String</td> + <td>Either "SYSTEM_OUT" or "SYSTEM_ERR". The default is "SYSTEM_ERR".</td> + </tr> + <caption align="top">ConsoleAppender Parameters</caption> + </table> + <p> + A typical Console configuration might look like: + <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> + </appenders> + <loggers + <root level="error"> + <appender-ref ref="STDOUT"/> + </root> + </loggers> +</configuration> + ]]></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> + <table border="1" width="100%"> + <tr> + <th>Parameter Name</th> + <th>Type</th> + <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 + may be used by using a CompositeFilter.</td> + </tr> + <tr> + <td>primary</td> + <td>String</td> + <td>The name of the primary Appender to use.</td> + </tr> + <tr> + <td>failovers</td> + <td>String[]</td> + <td>The names of the secondary Appenders to use.</td> + </tr> + + <tr> + <td>name</td> + <td>String</td> + <td>The name of the Appender.</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>target</td> + <td>String</td> + <td>Either "SYSTEM_OUT" or "SYSTEM_ERR". The default is "SYSTEM_ERR".</td> + </tr> + <caption align="top">FailoverAppender Parameters</caption> + </table> + <p> + A Failover configuration might look like: + + <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}.log.gz"> + <PatternLayout> + <pattern>%d %p %C{1.} [%t] %m%n</pattern> + </PatternLayout> + <TimeBasedTriggeringPolicy /> + </RollingFile> + <Console name="STDOUT" target="SYSTEM_OUT"> + <PatternLayout pattern="%m%n"/> + </Console> + <Failover name="Failover" primary="RollingFile" suppressExceptions="false"> + <Failovers> + <appender-ref ref="Console"/> + </Failovers> + </Failover> + </appenders> + <loggers + <root level="error"> + <appender-ref ref="Failover"/> + </root> + </loggers> +</configuration> + ]]></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 + FileAppenders from different Configurations cannot be shared, the FileManagers can be if the Manager is + accessible. For example, two webapps in a servlet container can have their own configuration and safely + write to the same file if Log4J is in a ClassLoader that is common to both of them.</p> + <table border="1" width="100%"> + <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>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>locking</td> + <td>boolean</td> + <td>When set to true, I/O operations will occur only while the file lock is held allowing FileAppenders + in multiple JVMs and potentially multiple hosts to write to the same file simultaneously. This + will significantly impact performance so should be used carefully. Furthermore, on many systems + the file lock is "advisory" meaning that other applications can perform operations on the file + without acquiring a lock. The default value is false.</td> + </tr> + <tr> + <td>name</td> + <td>String</td> + <td>The name of the Appender.</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">FileAppender Parameters</caption> + </table> + <p> + Here is a sample File configuration: + + <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<configuration status="warn" name="MyApp" packages=""> + <appenders> + <File name="MyFile" fileName="logs/app.log"> + <PatternLayout> + <pattern>%d %p %C{1.} [%t] %m%n</pattern> + </PatternLayout> + </File> + </appenders> + <loggers + <root level="error"> + <appender-ref ref="MyFile"/> + </root> + </loggers> +</configuration> + ]]></source> + </p> </subsection> - <a name="FlumeAppender"/> - <subsection name="FlumeAppender"> + <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 + from many different sources to a centralized data store. The FlumeAppender takes LogEvents and sends + them to a Flume agent as serialized Avro events for consumption.</p> + <table border="1" width="100%"> + <tr> + <th>Parameter Name</th> + <th>Type</th> + <th>Description</th> + </tr> + <tr> + <td>agents</td> + <td>Agent[]</td> + <td>An array of Agents to which the logging events should be sent. If more than one agent is specified + the first Agent will be the primary and subsequent Agents will be used in the order specified as + secondaries should the primary Agent fail. Each Agent definition supplies the Agents host and port.</td> + </tr> + <tr> + <td>agentRetries</td> + <td>integer</td> + <td>The number of times the agent should be retried before failing to a secondary.</td> + </tr> + <tr> + <td>compress</td> + <td>boolean</td> + <td>When set to true the message body will be compressed using gzip</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>eventPrefix</td> + <td>String</td> + <td>The character string to prepend to each event attribute in order to distinguish it from MDC attributes. + The default is an empty string.</td> + </tr> + <tr> + <td>flumeEventFactory</td> + <td>FlumeEventFactory</td> + <td>Factory that generates the Flume events from Log4j events. The default factory is the + FlumeAvroAppender itself.</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 + exclusive with the mdcIncludes attribute.</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.</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.</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:".</td> + </tr> + <tr> + <td>name</td> + <td>String</td> + <td>The name of the Appender.</td> + </tr> + <tr> + <td>reconnectionDelay</td> + <td>integer</td> + <td>The number of milliseconds the application should wait before trying again to connect to the + agent.</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">FlumeAvroAppender Parameters</caption> + </table> + <p> + A sample FlumeAvroAppender configuration that is configured with a primary and a secondary agent, + compresses the body, and formats the body using the RFC5424Layout: + <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<configuration status="warn" name="MyApp" packages=""> + <appenders> + <Flume name="eventLogger" 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> + </appenders> + <loggers + <root level="error"> + <appender-ref ref="eventLogger"/> + </root> + </loggers> +</configuration> + ]]></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%"> + <tr> + <th>Parameter Name</th> + <th>Type</th> + <th>Description</th> + </tr> + <tr> + <td>factoryBindingName</td> + <td>String</td> + <td></td> + </tr> + <tr> + <td>factoryName</td> + <td>String</td> + <td></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>password</td> + <td>String</td> + <td></td> + </tr> + <tr> + <td>providerURL</td> + <td>String</td> + <td></td> + </tr> + <tr> + <td>queueBindingName</td> + <td>String</td> + <td></td> + </tr> + <tr> + <td>securityPrincipalName</td> + <td>String</td> + <td></td> + </tr> + <tr> + <td>securityCredentials</td> + <td>String</td> + <td></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></td> + </tr> + <tr> + <td>userName</td> + <td>String</td> + <td></td> + </tr> + <caption align="top">JMSQueueAppender Parameters</caption> + </table> + <p> + Here is a sample JMSQueueAppender configuration: + <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> + </appenders> + <loggers + <root level="error"> + <appender-ref ref="MyFile"/> + </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 + immediateFlush and buffering is provided by the OutputStreamAppender. The OutputStreamAppender uses an + 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"> + + </subsection> <a name="RollingFileAppender"/> <subsection name="RollingFileAppender"> + <h4>Triggering Policies</h4> + <h5>Composite Triggering Policy</h5> + <h5>OnStartup Triggering Policy</h5> + <h5>SizeBased Triggering Policy</h5> + <h5>TimeBased Triggering Policy</h5> + <h4>Rollover Strategies</h4> + <h5>Default Rollover Strategy</h5> + </subsection> + <a name="RoutingAppender"/> + <subsection name="RoutingAppender"> </subsection> <a name="SocketAppender"/> Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/filters.xml URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/filters.xml?rev=1199841&r1=1199840&r2=1199841&view=diff ============================================================================== --- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/filters.xml (original) +++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/filters.xml Wed Nov 9 16:51:46 2011 @@ -28,6 +28,10 @@ <subsection name="BurstFilter"> </subsection> + <a name="CompositeFilter"/> + <subsection name="CompositeFilter"> + + </subsection> <a name="DynamicThresholdFilter"/> <subsection name="DynamicThresholdFilter"> Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/lookups.xml URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/lookups.xml?rev=1199841&r1=1199840&r2=1199841&view=diff ============================================================================== --- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/lookups.xml (original) +++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/lookups.xml Wed Nov 9 16:51:46 2011 @@ -28,6 +28,14 @@ <subsection name="ContextMapLookup"> </subsection> + <a name="EnvironmentLookup"/> + <subsection name="EnvironmentLookup"> + + </subsection> + <a name="MapLookup"/> + <subsection name="MapLookup"> + + </subsection> <a name="StructuredDtaLookup"/> <subsection name="StructuredDataLookup">