Author: rgoers
Date: Wed Apr 17 23:28:26 2013
New Revision: 1469101
URL: http://svn.apache.org/r1469101
Log:
LOG4J2-208 - Merge async support into core
Removed:
logging/log4j/log4j2/trunk/log4j-async/
Modified:
logging/log4j/log4j2/trunk/core/pom.xml
logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/config/LoggerConfig.java
logging/log4j/log4j2/trunk/core/src/site/xdoc/index.xml
logging/log4j/log4j2/trunk/pom.xml
logging/log4j/log4j2/trunk/src/site/pdf.xml
logging/log4j/log4j2/trunk/src/site/site.xml
logging/log4j/log4j2/trunk/src/site/xdoc/index.xml
logging/log4j/log4j2/trunk/src/site/xdoc/manual/appenders.xml
logging/log4j/log4j2/trunk/src/site/xdoc/manual/async.xml
logging/log4j/log4j2/trunk/src/site/xdoc/manual/index.xml
Modified: logging/log4j/log4j2/trunk/core/pom.xml
URL:
http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/core/pom.xml?rev=1469101&r1=1469100&r2=1469101&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/core/pom.xml (original)
+++ logging/log4j/log4j2/trunk/core/pom.xml Wed Apr 17 23:28:26 2013
@@ -44,6 +44,11 @@
<scope>provided</scope>
</dependency>
<dependency>
+ <groupId>com.lmax</groupId>
+ <artifactId>disruptor</artifactId>
+ <optional>true</optional>
+ </dependency>
+ <dependency>
<groupId>org.codehaus.jackson</groupId>
<artifactId>jackson-core-asl</artifactId>
<optional>true</optional>
Modified:
logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/config/LoggerConfig.java
URL:
http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/config/LoggerConfig.java?rev=1469101&r1=1469100&r2=1469101&view=diff
==============================================================================
---
logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/config/LoggerConfig.java
(original)
+++
logging/log4j/log4j2/trunk/core/src/main/java/org/apache/logging/log4j/core/config/LoggerConfig.java
Wed Apr 17 23:28:26 2013
@@ -23,6 +23,7 @@ import org.apache.logging.log4j.Marker;
import org.apache.logging.log4j.core.Appender;
import org.apache.logging.log4j.core.Filter;
import org.apache.logging.log4j.core.LifeCycle;
+import org.apache.logging.log4j.core.async.AsyncLoggerContextSelector;
import org.apache.logging.log4j.core.config.plugins.PluginConfiguration;
import org.apache.logging.log4j.core.filter.AbstractFilterable;
import org.apache.logging.log4j.core.helpers.Constants;
@@ -477,7 +478,7 @@ public class LoggerConfig extends Abstra
// for synchronous loggers, includeLocation default is TRUE.
private static boolean includeLocation(String includeLocationConfigValue) {
if (includeLocationConfigValue == null) {
- final boolean sync =
!"org.apache.logging.log4j.async.AsyncLoggerContextSelector"
+ final boolean sync = !AsyncLoggerContextSelector.class.getName()
.equals(System.getProperty(Constants.LOG4J_CONTEXT_SELECTOR));
return sync;
}
Modified: logging/log4j/log4j2/trunk/core/src/site/xdoc/index.xml
URL:
http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/core/src/site/xdoc/index.xml?rev=1469101&r1=1469100&r2=1469101&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/core/src/site/xdoc/index.xml (original)
+++ logging/log4j/log4j2/trunk/core/src/site/xdoc/index.xml Wed Apr 17 23:28:26
2013
@@ -26,18 +26,27 @@
<section name="Log4j 2 Implementation">
<p>
- The Log4Jj 2 implementation provides the functional components
of the logging system. Users are
- free to create their own plugins and include them in the logging
configuration.
+ The Log4Jj 2 implementation provides the functional components
+ of the logging system.
+ Users are free to create their own plugins and include them
+ in the logging configuration.
</p>
</section>
<section name="Requirements">
<p>
- Log4j 2 requires Java 5 but has will take advantage of
enhancements in Java 6 to improve performance.
- Some features may require optional dependencies. These
dependencies are
+ Log4j 2 requires Java 6.
+ Some features may require optional
+ <a href="dependencies.html">dependencies</a>. These dependencies
are
specified in the documentation for those features.
</p>
+ <ul>
+ <li>JSON configuration requires the Jackson JSON-processor.</li>
+ <li>Async Loggers require the LMAX Disruptor.</li>
+ <li>SMTPAppender requires Javax Mail.</li>
+ <li>JMSQueueAppender and JMSTopicAppender require a JMS
implementation like geronimo-jms.</li>
+ </ul>
</section>
</body>
Modified: logging/log4j/log4j2/trunk/pom.xml
URL:
http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/pom.xml?rev=1469101&r1=1469100&r2=1469101&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/pom.xml (original)
+++ logging/log4j/log4j2/trunk/pom.xml Wed Apr 17 23:28:26 2013
@@ -62,7 +62,7 @@
<name>Remko Popma</name>
<email>[email protected]</email>
<roles>
- <role>log4j-async module development, testing and documentation</role>
+ <role>Async Low-Latency Loggers, log4j JMX support</role>
</roles>
<timezone>+9</timezone>
<properties>
@@ -116,6 +116,7 @@
<Log4jReleaseVersion>2.0-beta5</Log4jReleaseVersion>
<Log4jReleaseCount>seventh</Log4jReleaseCount>
<jackson.version>1.9.2</jackson.version>
+ <disruptor.version>3.0.0</disruptor.version>
<!-- Configuration properties for the OSGi maven-bundle-plugin -->
<osgi.symbolicName>org.apache.logging.${project.artifactId}</osgi.symbolicName>
<osgi.export>org.apache.logging.log4j.*;version=${project.version};-noimport:=true</osgi.export>
@@ -261,6 +262,11 @@
<scope>provided</scope>
</dependency>
<dependency>
+ <groupId>com.lmax</groupId>
+ <artifactId>disruptor</artifactId>
+ <version>${disruptor.version}</version>
+ </dependency>
+ <dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.7</version>
@@ -386,6 +392,8 @@
</dependency>
</dependencies>
<configuration>
+ <!-- only build English site even on other language OS -->
+ <locales>en</locales>
<!-- Exclude the navigation file for Maven 1 sites
and the changes file used by the changes-plugin,
as they interfere with the site generation. -->
@@ -569,7 +577,6 @@
<module>web</module>
<module>taglib</module>
<module>samples</module>
- <module>log4j-async</module>
</modules>
<profiles>
<profile>
Modified: logging/log4j/log4j2/trunk/src/site/pdf.xml
URL:
http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/pdf.xml?rev=1469101&r1=1469100&r2=1469101&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/src/site/pdf.xml (original)
+++ logging/log4j/log4j2/trunk/src/site/pdf.xml Wed Apr 17 23:28:26 2013
@@ -37,6 +37,7 @@
<item name="Appenders" ref="/manual/appenders.html"/>
<item name="Layouts" ref="/manual/layouts.html"/>
<item name="Filters" ref="/manual/filters.html"/>
+ <item name="Async" ref="/manual/async.html" />
<item name="JMX" ref="/manual/jmx.html"/>
<item name="Logging Separation" ref="/manual/logsep.html"/>
<item name="Extending Log4j" ref="/manual/extending.html"/>
Modified: logging/log4j/log4j2/trunk/src/site/site.xml
URL:
http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/site.xml?rev=1469101&r1=1469100&r2=1469101&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/src/site/site.xml (original)
+++ logging/log4j/log4j2/trunk/src/site/site.xml Wed Apr 17 23:28:26 2013
@@ -73,6 +73,8 @@
<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="FastFile" href="/manual/appenders.html#FastFileAppender"/>
+ <item name="FastRollingFile"
href="/manual/appenders.html#FastRollingFileAppender"/>
<item name="Routing" href="/manual/appenders.html#RoutingAppender"/>
<item name="SMTP" href="/manual/appenders.html#SMTPAppender"/>
<item name="Socket" href="/manual/appenders.html#SocketAppender"/>
@@ -101,13 +103,11 @@
<item name="Time" href="/manual/filters.html#TimeFilter"/>
</item>
- <item name="Async" href="/manual/async.html" collapse="true">
+ <item name="Async Loggers" href="/manual/async.html" collapse="true">
<item name="Trade-offs" href="/manual/async.html#Trade-offs"/>
<item name="All Loggers Async" href="/manual/async.html#AllAsync"/>
<item name="Mixed Sync & Async"
href="/manual/async.html#MixedSync-Async"/>
<item name="Location" href="/manual/async.html#Location"/>
- <item name="FastFileAppender"
href="/manual/async.html#FastFileAppender"/>
- <item name="FastRollingFileAppender"
href="/manual/async.html#FastRollingFileAppender"/>
<item name="Performance" href="/manual/async.html#Performance"/>
<item name="Under The Hood" href="/manual/async.html#UnderTheHood"/>
</item>
@@ -132,7 +132,6 @@
<menu name="Components" inherit="top" img="icon-cog">
<item name="API" href="log4j-api/index.html"/>
<item name="Implementation" href="log4j-core/index.html"/>
- <item name="Async" href="log4j-async/index.html"/>
<item name="Commons Logging Bridge" href="log4j-jcl/index.html"/>
<item name="Log4J 1.2 API" href="log4j-1.2-api/index.html"/>
<item name="SLF4J Binding" href="log4j-slf4j-impl/index.html"/>
Modified: logging/log4j/log4j2/trunk/src/site/xdoc/index.xml
URL:
http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/xdoc/index.xml?rev=1469101&r1=1469100&r2=1469101&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/src/site/xdoc/index.xml (original)
+++ logging/log4j/log4j2/trunk/src/site/xdoc/index.xml Wed Apr 17 23:28:26 2013
@@ -44,7 +44,14 @@
</dd>
<dt>Improved Performance</dt>
<dd>
- Log4j 2 performs faster than Log4j 1.x in critical areas and
similarly to Logback under most circumstances.
+ Log4j 2 contains next-generation Asynchronous Loggers based
+ on the LMAX Disruptor library. In multi-threaded scenarios
+ Asynchronous Loggers have 10 times higher throughput and
+ orders of magnitude lower latency than Log4j 1.x and Logback.
+ See <a href="manual/async.html#Performance">Asynchronous Logging
Performance</a>
+ for details.
+ Otherwise, Log4j 2 performs faster than Log4j 1.x in critical
areas
+ and similarly to Logback under most circumstances.
See <a href="performance.html">Performance</a> for more
information.
</dd>
<dt>Support for multiple APIs</dt>
Modified: logging/log4j/log4j2/trunk/src/site/xdoc/manual/appenders.xml
URL:
http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/xdoc/manual/appenders.xml?rev=1469101&r1=1469100&r2=1469101&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/src/site/xdoc/manual/appenders.xml (original)
+++ logging/log4j/log4j2/trunk/src/site/xdoc/manual/appenders.xml Wed Apr 17
23:28:26 2013
@@ -1361,6 +1361,380 @@
</configuration>]]></pre>
</p>
</subsection>
+ <a name="FastFileAppender" />
+ <subsection name="FastFileAppender">
+ <p><i>Experimental, may replace FileAppender in a
future release.</i></p>
+ <p>
+ The FastFileAppender is similar to the
standard
+ <a href="#FileAppender">FileAppender</a>
+ except it is always buffered (this
cannot be switched off)
+ and internally it uses a
+ <tt>ByteBuffer + RandomAccessFile</tt>
+ instead of a
+ <tt>BufferedOutputStream</tt>.
+ We saw a 20-200% performance
improvement compared to
+ FileAppender with "bufferedIO=true" in
our
+ <a
href="async.html#FastFileAppenderPerformance">measurements</a>.
+ Similar to the FileAppender,
+ FastFileAppender uses a FastFileManager
to actually perform the
+ file I/O. While FastFileAppender
+ from different Configurations
+ cannot be shared, the FastFileManagers
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>
+ <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 records are written.
+ </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>filters</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>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.
+ This option is only
useful when using this
+ appender with
synchronous loggers. Asynchronous loggers will
+ automatically flush at
the end of a batch, which also guarantees
+ the data is written to
disk but is more efficient.
+ </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>
+ <caption align="top">FastFileAppender
Parameters</caption>
+ </table>
+ <p>
+ Here is a sample FastFile configuration:
+
+ <pre class="prettyprint
linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="warn" name="MyApp" packages="">
+ <appenders>
+ <FastFile name="MyFile" fileName="logs/app.log">
+ <PatternLayout>
+ <pattern>%d %p %c{1.} [%t] %m%n</pattern>
+ </PatternLayout>
+ </FastFile>
+ </appenders>
+ <loggers>
+ <root level="error">
+ <appender-ref ref="MyFile"/>
+ </root>
+ </loggers>
+</configuration>]]></pre>
+ </p>
+ </subsection>
+ <a name="FastRollingFileAppender" />
+ <subsection name="FastRollingFileAppender">
+ <p><i>Experimental, may replace RollingFileAppender in
a future release.</i></p>
+ <p>
+ The FastRollingFileAppender is similar
to the standard
+ <a
href="#RollingFileAppender">RollingFileAppender</a>
+ except it is always buffered (this
cannot be switched off)
+ and
+ internally it uses a
+ <tt>ByteBuffer + RandomAccessFile</tt>
+ instead of a
+ <tt>BufferedOutputStream</tt>.
+ We saw a 20-200% performance
improvement compared to
+ RollingFileAppender with
"bufferedIO=true"
+ in our
+ <a
href="async.html#FastFileAppenderPerformance">measurements</a>.
+
+ The FastRollingFileAppender writes
+ to the File named in the
+ fileName parameter
+ and rolls the file over according the
+ TriggeringPolicy
+ and the RolloverPolicy.
+
+ Similar to the RollingFileAppender,
+ FastRollingFileAppender uses a
FastRollingFileManager
+ to actually perform the
+ file I/O and perform the rollover.
While FastRollingFileAppender
+ from different Configurations cannot be
+ shared, the FastRollingFileManagers 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 FastRollingFileAppender 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, FastRollingFileAppender
will
+ use the
+ <a
href="#DefaultRolloverStrategy">DefaultRolloverStrategy</a>.
+ </p>
+ <p>
+ File locking is not supported by the
FastRollingFileAppender.
+ </p>
+ <table>
+ <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 records are written.
+ </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/or a %i which
represents an integer counter. The pattern
+ also supports
interpolation at
+ runtime so any of the
Lookups (such
+ as the
+ <a
href="./lookups.html#DateLookup">DateLookup</a>
+ can
+ be included in the
pattern.
+ </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.
+ This option is only
useful when using this
+ appender with
+ synchronous loggers.
Asynchronous loggers will
+ automatically
+ flush at the end of a
batch, which also guarantees
+ the data
+ is written to disk but
is more efficient.
+ </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">FastRollingFileAppender Parameters</caption>
+ </table>
+ <a name="FRFA_TriggeringPolicies" />
+ <h4>Triggering Policies</h4>
+ <p>
+ See
+ <a
href="#TriggeringPolicies">RollingFileAppender Triggering Policies</a>.
+ </p>
+ <a name="FRFA_RolloverStrategies" />
+ <h4>Rollover Strategies</h4>
+ <p>
+ See
+ <a
href="#RolloverStrategies">RollingFileAppender Rollover Strategies</a>.
+ </p>
+
+ <p>
+ Below is a sample configuration that
uses a FastRollingFileAppender
+ with both the time and size based
+ triggering policies, will create
+ up to 7 archives on the same day (1-7)
that
+ are stored in a
+ directory
+ based on the current year and month,
and will compress
+ each
+ archive using gzip:
+
+ <pre class="prettyprint
linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="warn" name="MyApp" packages="">
+ <appenders>
+ <FastRollingFile name="FastRollingFile" fileName="logs/app.log"
+
filePattern="logs/$${date:yyyy-MM}/app-%d{MM-dd-yyyy}-%i.log.gz">
+ <PatternLayout>
+ <pattern>%d %p %c{1.} [%t] %m%n</pattern>
+ </PatternLayout>
+ <Policies>
+ <TimeBasedTriggeringPolicy />
+ <SizeBasedTriggeringPolicy size="250 MB"/>
+ </Policies>
+ </FastRollingFile>
+ </appenders>
+ <loggers>
+ <root level="error">
+ <appender-ref ref="FastRollingFile"/>
+ </root>
+ </loggers>
+</configuration>]]></pre>
+ </p>
+ <p>
+ This second example shows a rollover
strategy that will keep up to
+ 20 files before removing them.
+ <pre class="prettyprint
linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="warn" name="MyApp" packages="">
+ <appenders>
+ <FastRollingFile name="FastRollingFile" fileName="logs/app.log"
+
filePattern="logs/$${date:yyyy-MM}/app-%d{MM-dd-yyyy}-%i.log.gz">
+ <PatternLayout>
+ <pattern>%d %p %c{1.} [%t] %m%n</pattern>
+ </PatternLayout>
+ <Policies>
+ <TimeBasedTriggeringPolicy />
+ <SizeBasedTriggeringPolicy size="250 MB"/>
+ </Policies>
+ <DefaultRolloverStrategy max="20"/>
+ </FastRollingFile>
+ </appenders>
+ <loggers>
+ <root level="error">
+ <appender-ref ref="FastRollingFile"/>
+ </root>
+ </loggers>
+</configuration>]]></pre>
+ </p>
+ <p>
+ Below is a sample configuration that
uses a FastRollingFileAppender
+ with both the time and size based
+ triggering policies, will create
+ up to 7 archives on the same day (1-7)
that
+ are stored in a
+ directory
+ based on the current year and month,
and will compress
+ each
+ archive using gzip and will roll every
6 hours when the hour is
+ divisible
+ by 6:
+
+ <pre class="prettyprint
linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="warn" name="MyApp" packages="">
+ <appenders>
+ <FastRollingFile name="FastRollingFile" fileName="logs/app.log"
+
filePattern="logs/$${date:yyyy-MM}/app-%d{yyyy-MM-dd-HH}-%i.log.gz">
+ <PatternLayout>
+ <pattern>%d %p %c{1.} [%t] %m%n</pattern>
+ </PatternLayout>
+ <Policies>
+ <TimeBasedTriggeringPolicy interval="6" modulate="true"/>
+ <SizeBasedTriggeringPolicy size="250 MB"/>
+ </Policies>
+ </FastRollingFile>
+ </appenders>
+ <loggers>
+ <root level="error">
+ <appender-ref ref="FastRollingFile"/>
+ </root>
+ </loggers>
+</configuration>]]></pre>
+ </p>
+ </subsection>
<a name="RoutingAppender"/>
<subsection name="RoutingAppender">
<p>
Modified: logging/log4j/log4j2/trunk/src/site/xdoc/manual/async.xml
URL:
http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/xdoc/manual/async.xml?rev=1469101&r1=1469100&r2=1469101&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/src/site/xdoc/manual/async.xml (original)
+++ logging/log4j/log4j2/trunk/src/site/xdoc/manual/async.xml Wed Apr 17
23:28:26 2013
@@ -11,11 +11,11 @@
language governing permissions and limitations under the License. -->
<document>
<properties>
- <title>Log4j2 Asynchronous Logging</title>
+ <title>Log4j2 Asynchronous Loggers for Low-Latency
Logging</title>
<author email="[email protected]">Remko Popma</author>
</properties>
<body>
- <section name="Asynchronous Logging">
+ <section name="Asynchronous Loggers for Low-Latency Logging">
<p>
Asynchronous logging can improve your
application's
performance by executing the I/O operations
@@ -53,7 +53,7 @@
Appenders. Under the hood, these
new appenders use a ByteBuffer +
RandomAccessFile instead
of a BufferedOutputStream. In our
testing
- this was about 10-30% faster.
+ this was about 20-200% faster.
These appenders can also be used
with synchronous loggers
and will give the same performance
benefits.
@@ -125,11 +125,11 @@
<subsection name="Making All Loggers Asynchronous">
<p>
This is simplest to configure and gives
the best performance.
- To make all loggers asynchronous, add
log4j-async.jar
- and disruptor-3.0.0.jar to the classpath
+ To make all loggers asynchronous,
+ add disruptor-3.0.0.jar to the classpath
and set the system property
<tt>Log4jContextSelector</tt>
to
-
<tt>org.apache.logging.log4j.async.AsyncLoggerContextSelector</tt>.
+
<tt>org.apache.logging.log4j.core.async.AsyncLoggerContextSelector</tt>.
</p>
<p>
By default, <a
href="#Location">location</a> is not passed to the I/O thread by
@@ -270,7 +270,7 @@
</td>
<td>
Implementation of the
-
<tt>org.apache.logging.log4j.async.Clock</tt>
+
<tt>org.apache.logging.log4j.core.async.Clock</tt>
interface that is used
for timestamping the log
events when all loggers
are asynchronous.
<br />
@@ -302,6 +302,7 @@
</subsection>
<a name="MixedSync-Async" />
<subsection name="Mixing Synchronous and Asynchronous
Loggers">
+ <p><i>Requires disruptor-3.0.0.jar on the
classpath.</i></p>
<p>
Synchronous and asynchronous loggers
can be combined in
configuration. This gives you more
flexibility at the cost
@@ -345,7 +346,8 @@
</FastFile>
</appenders>
<loggers>
- <asyncLogger name="com.foo.Bar" level="trace" includeLocation="true"><!--
pattern actually uses location, so need to include it -->
+ <!-- pattern actually uses location, so we need to include it -->
+ <asyncLogger name="com.foo.Bar" level="trace" includeLocation="true">
<appender-ref ref="FastFile"/>
</asyncLogger>
<root level="info" includeLocation="true">
@@ -469,378 +471,6 @@
<p>
</p>
</subsection>
- <a name="FastFileAppender" />
- <subsection name="FastFileAppender">
- <p>
- The FastFileAppender is similar to the
standard
- <a
href="appenders.html#FileAppender">FileAppender</a>
- except it is always buffered (this
cannot be switched off)
- and internally it uses a
- <tt>ByteBuffer + RandomAccessFile</tt>
- instead of a
- <tt>BufferedOutputStream</tt>.
- We saw a 20-200% performance
improvement compared to
- FileAppender with "bufferedIO=true" in
our
- <a
href="#FastFileAppenderPerformance">measurements</a>.
- Similar to the FileAppender,
- FastFileAppender uses a FastFileManager
to actually perform the
- file I/O. While FastFileAppender
- from different Configurations
- cannot be shared, the FastFileManagers
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>
- <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 records are written.
- </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>filters</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>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.
- This option is only
necessary when using this
- appender with
synchronous loggers. Asynchronous loggers will
- automatically flush at
the end of a batch, which also guarantees
- the data is written to
disk but is more efficient.
- </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>
- <caption align="top">FastFileAppender
Parameters</caption>
- </table>
- <p>
- Here is a sample FastFile configuration:
-
- <pre class="prettyprint
linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<configuration status="warn" name="MyApp" packages="">
- <appenders>
- <FastFile name="MyFile" fileName="logs/app.log">
- <PatternLayout>
- <pattern>%d %p %c{1.} [%t] %m%n</pattern>
- </PatternLayout>
- </FastFile>
- </appenders>
- <loggers>
- <root level="error">
- <appender-ref ref="MyFile"/>
- </root>
- </loggers>
-</configuration>]]></pre>
- </p>
- </subsection>
- <a name="FastRollingFileAppender" />
- <subsection name="FastRollingFileAppender">
- <p>
- The FastRollingFileAppender is similar
to the standard
- <a
href="appenders.html#RollingFileAppender">RollingFileAppender</a>
- except it is always buffered (this
cannot be switched off)
- and
- internally it uses a
- <tt>ByteBuffer + RandomAccessFile</tt>
- instead of a
- <tt>BufferedOutputStream</tt>.
- We saw a 20-200% performance
improvement compared to
- RollingFileAppender with
"bufferedIO=true"
- in our
- <a
href="#FastFileAppenderPerformance">measurements</a>.
-
- The FastRollingFileAppender writes
- to the File named in the
- fileName parameter
- and rolls the file over according the
- TriggeringPolicy
- and the RolloverPolicy.
-
- Similar to the RollingFileAppender,
- FastRollingFileAppender uses a
FastRollingFileManager
- to actually perform the
- file I/O and perform the rollover.
While FastRollingFileAppender
- from different Configurations cannot be
- shared, the FastRollingFileManagers 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 FastRollingFileAppender 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, FastRollingFileAppender
will
- use the
- <a
href="appenders.html#DefaultRolloverStrategy">DefaultRolloverStrategy</a>.
- </p>
- <p>
- File locking is not supported by the
FastRollingFileAppender.
- </p>
- <table>
- <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 records are written.
- </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/or a %i which
represents an integer counter. The pattern
- also supports
interpolation at
- runtime so any of the
Lookups (such
- as the
- <a
href="./lookups.html#DateLookup">DateLookup</a>
- can
- be included in the
pattern.
- </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.
- This option is only
necessary when using this
- appender with
- synchronous loggers.
Asynchronous loggers will
- automatically
- flush at the end of a
batch, which also guarantees
- the data
- is written to disk but
is more efficient.
- </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">FastRollingFileAppender Parameters</caption>
- </table>
- <a name="TriggeringPolicies" />
- <h4>Triggering Policies</h4>
- <p>
- See
- <a
href="appenders.html#TriggeringPolicies">RollingFileAppender Triggering
Policies</a>.
- </p>
- <a name="RolloverStrategies" />
- <h4>Rollover Strategies</h4>
- <p>
- See
- <a
href="appenders.html#RolloverStrategies">RollingFileAppender Rollover
Strategies</a>.
- </p>
-
- <p>
- Below is a sample configuration that
uses a FastRollingFileAppender
- with both the time and size based
- triggering policies, will create
- up to 7 archives on the same day (1-7)
that
- are stored in a
- directory
- based on the current year and month,
and will compress
- each
- archive using gzip:
-
- <pre class="prettyprint
linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<configuration status="warn" name="MyApp" packages="">
- <appenders>
- <FastRollingFile name="FastRollingFile" fileName="logs/app.log"
-
filePattern="logs/$${date:yyyy-MM}/app-%d{MM-dd-yyyy}-%i.log.gz">
- <PatternLayout>
- <pattern>%d %p %c{1.} [%t] %m%n</pattern>
- </PatternLayout>
- <Policies>
- <TimeBasedTriggeringPolicy />
- <SizeBasedTriggeringPolicy size="250 MB"/>
- </Policies>
- </FastRollingFile>
- </appenders>
- <loggers>
- <root level="error">
- <appender-ref ref="FastRollingFile"/>
- </root>
- </loggers>
-</configuration>]]></pre>
- </p>
- <p>
- This second example shows a rollover
strategy that will keep up to
- 20 files before removing them.
- <pre class="prettyprint
linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<configuration status="warn" name="MyApp" packages="">
- <appenders>
- <FastRollingFile name="FastRollingFile" fileName="logs/app.log"
-
filePattern="logs/$${date:yyyy-MM}/app-%d{MM-dd-yyyy}-%i.log.gz">
- <PatternLayout>
- <pattern>%d %p %c{1.} [%t] %m%n</pattern>
- </PatternLayout>
- <Policies>
- <TimeBasedTriggeringPolicy />
- <SizeBasedTriggeringPolicy size="250 MB"/>
- </Policies>
- <DefaultRolloverStrategy max="20"/>
- </FastRollingFile>
- </appenders>
- <loggers>
- <root level="error">
- <appender-ref ref="FastRollingFile"/>
- </root>
- </loggers>
-</configuration>]]></pre>
- </p>
- <p>
- Below is a sample configuration that
uses a FastRollingFileAppender
- with both the time and size based
- triggering policies, will create
- up to 7 archives on the same day (1-7)
that
- are stored in a
- directory
- based on the current year and month,
and will compress
- each
- archive using gzip and will roll every
6 hours when the hour is
- divisible
- by 6:
-
- <pre class="prettyprint
linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<configuration status="warn" name="MyApp" packages="">
- <appenders>
- <FastRollingFile name="FastRollingFile" fileName="logs/app.log"
-
filePattern="logs/$${date:yyyy-MM}/app-%d{yyyy-MM-dd-HH}-%i.log.gz">
- <PatternLayout>
- <pattern>%d %p %c{1.} [%t] %m%n</pattern>
- </PatternLayout>
- <Policies>
- <TimeBasedTriggeringPolicy interval="6" modulate="true"/>
- <SizeBasedTriggeringPolicy size="250 MB"/>
- </Policies>
- </FastRollingFile>
- </appenders>
- <loggers>
- <root level="error">
- <appender-ref ref="FastRollingFile"/>
- </root>
- </loggers>
-</configuration>]]></pre>
- </p>
- </subsection>
<a name="Performance" />
<subsection name="Asynchronous Logging Performance">
<p>
@@ -1141,7 +771,8 @@
<img src="../images/async-average-latency.png"
/>
</p>
<p>
- The scale of the latency comparison graphs is
logarithmic, not linear.
+ Note that the scale of the latency comparison
graphs is
+ logarithmic, not linear.
That makes it a bit difficult to see, but the
average latency of
asynchronous loggers is half to one third of
the latency of
ArrayBlockingQueue-based asynchronous appenders
in scenarios
@@ -1155,10 +786,12 @@
The graph below shows that asynchronous loggers
also do
better when comparing the maximum latency of
99.99% of
observations with other logging methods.
- The worst case latency of asynchronous loggers
remains more or
- less the same (around 10-20 microseconds) in
multi-threaded scenarios where
- ArrayBlockingQueue-based asynchronous appenders
have more outliers
- with latencies of over 100 milliseconds per
call to Logger.log.
+ When increasing the number of threads
+ the worst case latency of asynchronous loggers
remains more or
+ less the same (around 10-20 microseconds)
+ where Asynchronous Appenders start experiencing
worst-case
+ latency spikes in the 100 millisecond range, a
difference of
+ four orders of magnitude.
</p>
<p>
<img
src="../images/async-max-latency-99.99pct.png" />
Modified: logging/log4j/log4j2/trunk/src/site/xdoc/manual/index.xml
URL:
http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/xdoc/manual/index.xml?rev=1469101&r1=1469100&r2=1469101&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/src/site/xdoc/manual/index.xml (original)
+++ logging/log4j/log4j2/trunk/src/site/xdoc/manual/index.xml Wed Apr 17
23:28:26 2013
@@ -88,11 +88,13 @@
Logback exceptions in Appenders are never visible to the
application. In
Log4j 2 Appenders can be configured to allow the exception to
percolate
to the application</li>
+ <li>Log4j 2 contains next-generation Asynchronous Loggers based
+ on the LMAX Disruptor library. In multi-threaded scenarios
+ Asynchronous Loggers have 10 times higher throughput and
+ orders of magnitude lower latency than Log4j 1.x and
Logback.</li>
<li>Log4j 2 uses a Plugin system that makes it extremely easy to
extend the
framework by adding new Appenders, Filters, Layouts, Lookups,
and Pattern Converters without requiring any changes to
Log4j.</li>
- <li>The performance of Log4j 2 is similar to that of Logback. It
is slightly
- slower in some tests and faster in others.</li>
<li>Due to the Plugin system configuration is simpler. Entries in
the configuration
do not require a class name to be specified.</li>
<li>Support for Message objects. Messages allow support for
interesting and
