I would say nothing, otherwise, we should go around all of the docs and put "beta" on all the new stuff. I think the docs maybe could say "since 2.1" or "new" for the new stuff. But it is says "new" or "beta" you have to go edit that again when we release. I think it is best to have a "what's new section" that tracks what was added in each version.
Gary On Wed, Sep 17, 2014 at 12:02 PM, Remko Popma <[email protected]> wrote: > 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 >> > > -- 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
