I think it would definitely be a good idea to mention "since 2.1" or a similar message. That's rather important since we don't maintain past versions of the website manual.
On 17 September 2014 11:13, Gary Gregory <[email protected]> wrote: > 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 > -- Matt Sicker <[email protected]>
