I do not think this should be marker "experimental". If it is brought into trunk for 2.1 and we have a beta, we can say, this and that are new, it's a beta.
Gary ---------- Forwarded message ---------- From: <[email protected]> Date: Wed, Sep 17, 2014 at 11:45 AM Subject: [1/3] git commit: LOG4J2-431 MemoryMappedFileAppender manual page To: [email protected] Repository: logging-log4j2 Updated Branches: refs/heads/LOG4J2-431 64369f3d7 -> 63aed83d6 LOG4J2-431 MemoryMappedFileAppender manual page Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/80dafe9e Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/80dafe9e Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/80dafe9e Branch: refs/heads/LOG4J2-431 Commit: 80dafe9e85c28f89d5b4d411d8b28c33642f411f Parents: 64369f3 Author: rpopma <[email protected]> Authored: Thu Sep 18 00:42:50 2014 +0900 Committer: rpopma <[email protected]> Committed: Thu Sep 18 00:42:50 2014 +0900 ---------------------------------------------------------------------- src/site/xdoc/manual/appenders.xml | 131 ++++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/80dafe9e/src/site/xdoc/manual/appenders.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/manual/appenders.xml b/src/site/xdoc/manual/appenders.xml index 032983b..7d47f78 100644 --- a/src/site/xdoc/manual/appenders.xml +++ b/src/site/xdoc/manual/appenders.xml @@ -1320,6 +1320,137 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity { ... }]]></pre> </subsection> + <a name="MemoryMappedFileAppender" /> + <subsection name="MemoryMappedFileAppender"> + <p><i>Experimental. This has been tested on several platforms, but this is + a new component (since 2.1) and does not yet have much track record.</i></p> + <p> + The MemoryMappedFileAppender maps a part of the specified file into memory + and writes log events to this memory, relying on the operating system's + virtual memory manager to synchronize the changes to the storage device. + The main benefit of doing this is I/O performance. Instead of making system + calls to write to disk, this appender can simply change the program's local memory, + which is orders of magnitude faster. Also, in most operating systems the memory + region mapped actually is the kernel's <a href=" http://en.wikipedia.org/wiki/Page_cache";>page + cache</a> (file cache), meaning that no copies need to be created in user space. + (TODO: performance tests that compare performance of this appender to + RandomAccessFileAppender and FileAppender.) + </p> + <p> + There is some overhead with mapping a file region into memory, + especially very large regions (half a gigabyte or more). + The default region size is 32 MB, which should strike a reasonable balance + between the frequency and the duration of remap operations. + (TODO: performance test remapping various sizes.) + </p> + <p> + Similar to the FileAppender and the RandomAccessFileAppender, + MemoryMappedFileAppender uses a MemoryMappedFileManager to actually perform the + file I/O. While MemoryMappedFileAppender from different Configurations + cannot be shared, the MemoryMappedFileManagers can be if the Manager is + accessible. For example, two web applications 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> + <caption align="top">MemoryMappedFileAppender Parameters</caption> + <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> + <p>When set to true, each write will be followed by a + call to <a href=" http://docs.oracle.com/javase/7/docs/api/java/nio/MappedByteBuffer.html#force() ">MappedByteBuffer.force()</a>. + This will guarantee the data is written to the storage device. + </p> + <p>The default for this parameter is <code>false</code>. + This means that the data is written to the storage device even + if the Java process crashes, but there may be data loss if the + operating system crashes. Note that manually forcing a sync on every + log event loses most of the performance benefits of using a memory mapped file.</p> + <p>Flushing after every write is only useful when using this + appender with synchronous loggers. Asynchronous loggers and + appenders will automatically flush at the end of a batch of events, + even if immediateFlush is set to false. This also guarantees + the data is written to disk but is more efficient. + </p> + </td> + </tr> + <tr> + <td>regionLength</td> + <td>int</td> + <td>The length of the mapped region, defaults to 32 MB + (32 * 1024 * 1024 bytes). This parameter must be a value + between 256 and 1,073,741,824 (1 GB or 2^30); + values outside this range will be adjusted to the closest valid + value. + Log4j will round the specified value up to the nearest power of two.</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>ignoreExceptions</td> + <td>boolean</td> + <td>The default is <code>true</code>, causing exceptions encountered while appending events to be + internally logged and then ignored. When set to <code>false</code> exceptions will be propagated to the + caller, instead. You must set this to <code>false</code> when wrapping this Appender in a + <a href="#FailoverAppender">FailoverAppender</a>.</td> + </tr> + </table> + <p> + Here is a sample MemoryMappedFile configuration: + </p> + + <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<Configuration status="warn" name="MyApp" packages=""> + <Appenders> + <MemoryMappedFile name="MyFile" fileName="logs/app.log"> + <PatternLayout> + <Pattern>%d %p %c{1.} [%t] %m%n</Pattern> + </PatternLayout> + </MemoryMappedFile> + </Appenders> + <Loggers> + <Root level="error"> + <AppenderRef ref="MyFile"/> + </Root> + </Loggers> +</Configuration>]]></pre> + </subsection> <a name="NoSQLAppender"/> <subsection name="NoSQLAppender"> <p>The NoSQLAppender writes log events to a NoSQL database using an internal lightweight provider interface. -- E-Mail: [email protected] | [email protected] Java Persistence with Hibernate, Second Edition <http://www.manning.com/bauer3/> JUnit in Action, Second Edition <http://www.manning.com/tahchiev/> Spring Batch in Action <http://www.manning.com/templier/> Blog: http://garygregory.wordpress.com Home: http://garygregory.com/ Tweet! http://twitter.com/GaryGregory
