Shall I replace "Experimental" with "Beta" in the docs for this component then until 2.1 final? I'm fine with that.
On Thu, Sep 18, 2014 at 12:48 AM, Gary Gregory <[email protected]> wrote: > 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 >
