This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project "Logback: the generic, reliable, fast and flexible logging framework.". The branch, master has been updated via ccc56bc6e079569a0bef20a2e639a3333e717ac5 (commit) from 63ee4e4e0bad23f83cffb635147b377dc2fe3f30 (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below. - Log ----------------------------------------------------------------- http://git.qos.ch/gitweb/?p=logback.git;a=commit;h=ccc56bc6e079569a0bef20a2e... http://github.com/ceki/logback/commit/ccc56bc6e079569a0bef20a2e639a3333e717a... commit ccc56bc6e079569a0bef20a2e639a3333e717ac5 Author: Ceki Gulcu <ceki@qos.ch> Date: Sat May 5 18:27:03 2012 +0200 documentation improvements diff --git a/logback-site/src/site/pages/manual/appenders.html b/logback-site/src/site/pages/manual/appenders.html index 2df02b0..31602ae 100644 --- a/logback-site/src/site/pages/manual/appenders.html +++ b/logback-site/src/site/pages/manual/appenders.html @@ -271,16 +271,6 @@ public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachabl </table> - <p>Given the structure of current hard drives and performance tests - we have conducted, it appears that turning off immediate flushing or - buffering of character to byte conversions have rather small impact - on performance. As such, as of logback version 0.9.19, the <span - class="prop">ImmediateFlush</span>, <span - class="prop">BufferedIO</span> and <span - class="prop">BufferSize</span> properties have been removed - without replacement. - </p> - <p>The <code>OutputStreamAppender</code> is the super-class of three other appenders, namely <code>ConsoleAppender</code>, <code>FileAppender</code> which in turn is the super class of @@ -473,9 +463,12 @@ public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachabl <p><span class="label notice">Immediate Flush</span> By default, each log event is immediately flushed to the underlying output - stream. For significantly increased logging throughput, you may - want to set the <span class="prop">immediateFlush</span> property - to <code>false</code> of the underlying encoder. Encoders and in + stream. This default approach is safer in the sense that logging + events are not lost in case your applicaiton exits without properly + closing appenders. However, for significantly increased logging + throughput, you may want to set the <span + class="prop">immediateFlush</span> property of the underlying + <code>Encoder</code> to <code>false</code> . Encoders and in particular <a href="encoders.html#LayoutWrappingEncoder"><code>LayoutWrappingEncoder</code></a> are described in a separate chapter.</p> diff --git a/logback-site/src/site/pages/manual/encoders.html b/logback-site/src/site/pages/manual/encoders.html index 6de5b7b..bbc504d 100644 --- a/logback-site/src/site/pages/manual/encoders.html +++ b/logback-site/src/site/pages/manual/encoders.html @@ -65,21 +65,20 @@ out. </p> - <p>At the present time (2010-03-08), - <code>PatternLayoutEncoder</code> is the only really useful - encoder. It merely wraps a <code>PatternLayout</code> which does - most of the work. Thus, it may seem that encoders do not bring much - to the table except needless complexity. However, we hope that - with the advent of new and powerful encoders this impression will - change.</p> + <p>At the present time, <code>PatternLayoutEncoder</code> is the + only really useful encoder. It merely wraps a + <code>PatternLayout</code> which does most of the work. Thus, it + may seem that encoders do not bring much to the table except + needless complexity. However, we hope that with the advent of new + and powerful encoders this impression will change.</p> <h2><a name="interface" href="#interface">Encoder interface</a></h2> <p>Encoders are responsible for transforming an incoming event into a byte array <b>and</b> writing out the resulting byte array - onto the appropriate OutputStream. Thus, encoders have total - control of what and when bytes gets written to the + onto the appropriate <code>OutputStream</code>. Thus, encoders + have total control of what and when bytes gets written to the <code>OutputStream</code> maintained by the owning appender. Here is the <a href="../xref/ch/qos/logback/core/encoder/Encoder.html">Encoder @@ -113,19 +112,18 @@ public interface Encoder<E> extends ContextAware, LifeCycle { void close() throws IOException; }</pre> - <p>As you can see, the Encoder interface consists of few methods, - but surprisingly many useful things can be accomplished with - those methods. + <p>As you can see, the <code>Encoder</code> interface consists of + few methods, but surprisingly many useful things can be + accomplished with these methods. </p> <h2><a name="LayoutWrappingEncoder" href="#LayoutWrappingEncoder">LayoutWrappingEncoder</a></h2> - <p>Until logback version 0.9.19, appenders which offered - flexibility with respect to the output format relied on - layouts. As there exists a substantial body of code based on the - layout interface, we need a way for encoders inter-operate with - layouts. <a + <p>Until logback version 0.9.19, many appenders relied on the + Layout instances to control the format of log output. As there + exists substantial amount of code based on the layout interface, + we needed a way for encoders to inter-operate with layouts. <a href="../xref/ch/qos/logback/core/encoder/LayoutWrappingEncoder.html">LayoutWrappingEncoder</a> bridges the gap between encoders and layouts. It implements the encoder interface and wraps a layout to which it delegates the @@ -167,10 +165,10 @@ public class LayoutWrappingEncoder<E> extends EncoderBase<E> { <code>OutputStream</code> given by the owning appender. By default, the <code>OutputStream</code> is immediately flushed, unless the <span class="prop">immediateFlush</span> property is - explicitly set to false. Setting the <span + explicitly set to 'false'. Setting the <span class="prop">immediateFlush</span> property to false can significantly improve logging throughput. See - <code>PatternLayoutEncoder</code> below for example. + <code>PatternLayoutEncoder</code> below for sample configuration.. </p> @@ -178,7 +176,7 @@ public class LayoutWrappingEncoder<E> extends EncoderBase<E> { href="#PatternLayoutEncoder">PatternLayoutEncoder</a></h2> <p>Given that <code>PatternLayout</code> is the most commonly used - layout, logback caters for this common use case with + layout, logback caters for this common use-case with <code>PatternLayoutEncoder</code>, an extension of <code>LayoutWrappingEncoder</code> restricted to wrapping instances of <code>PatternLayout</code>. @@ -193,6 +191,39 @@ public class LayoutWrappingEncoder<E> extends EncoderBase<E> { logback error codes</a>. </p> + <h4><span class="prop">immediateFlush</span> property</h4> + + <p>As a sub-class of <a + href="../xref/ch/qos/logback/core/encoder/LayoutWrappingEncoder.html"><code>LayoutWrappingEncoder</code></a>, + <code>PatternLayoutEncoder</code> admits the <span + class="prop">immediateFlush</span> property. The default value + for <span class="prop">immediateFlush</span> is 'true'. Immediate + flushing of the output stream ensures that logging events are + immediately written to disk and will be not lost in case your + application exits without properly closing appenders. On the + other hand, setting this property to 'false' is likely to + quadruple (your mileage may vary) logging throughput. As + mentioned previously, if <span class="prop">immediateFlush</span> + is set to 'false' and if appenders are not closed properly when + your application exits, then logging events not yet written to + disk may be lost. + </p> + + <p>Below is a sample configuration for a + <code>FileAppender</code> containing a + <code>PatternLayoutEncoder</code> with its <span + class="prop">immediateFlush</span> property set to 'false'.</p> + +<pre class="prettyprint"><appender name="FILE" class="ch.qos.logback.core.FileAppender"> + <file>foo.log</file> + <encoder> + <pattern>%d %-5level [%thread] %logger{0}: %msg%n</pattern> + <!-- this quadruples logging throughput --> + <b><immediateFlush>false</immediateFlush></b> + </encoder> +</appender></pre> + + <h4><a name="outputPatternAsHeader" href="#outputPatternAsHeader">Output pattern string as header</a></h4> <p>In order to facilitate parsing of log files, logback can insert @@ -220,30 +251,6 @@ public class LayoutWrappingEncoder<E> extends EncoderBase<E> { <p>The line starting with "#logback.classic pattern" is newly inserted pattern line.</p> - <h4><span class="prop">immediateFlush</span> property</h4> - - <p>As a sub-class of <a - href="../xref/ch/qos/logback/core/encoder/LayoutWrappingEncoder.html"><code>LayoutWrappingEncoder</code></a>, - <code>PatternLayoutEncoder</code> admits the <span - class="prop">immediateFlush</span> property. The default value - for <span class="prop">immediateFlush</span> is 'false'. However, - by setting this property to 'false', logging throughput can be - quadrupled although your mileage may vary. - </p> - - <p>Below is a sample configuration for a - <code>FileAppender</code> containing a - <code>PatternLayoutEncoder</code> with its <span - class="prop">immediateFlush</span> property set to 'false'.</p> - -<pre class="prettyprint"><appender name="FILE" class="ch.qos.logback.core.FileAppender"> - <file>foo.log</file> - <encoder> - <pattern>%d %-5level [%thread] %logger{0}: %msg%n</pattern> - <!-- this quadruples logging throughput --> - <b><immediateFlush>false</immediateFlush></b> - </encoder> -</appender></pre> ----------------------------------------------------------------------- Summary of changes: logback-site/src/site/pages/manual/appenders.html | 19 ++--- logback-site/src/site/pages/manual/encoders.html | 95 +++++++++++---------- 2 files changed, 57 insertions(+), 57 deletions(-) hooks/post-receive -- Logback: the generic, reliable, fast and flexible logging framework.