[logback-dev] [GIT] Logback: the generic, reliable, fast and flexible logging framework. branch master updated. v_1.0.3-3-gccc56bc
Gitbot
git-noreply at pixie.qos.ch
Sat May 5 18:27:51 CEST 2012
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=ccc56bc6e079569a0bef20a2e639a3333e717ac5
http://github.com/ceki/logback/commit/ccc56bc6e079569a0bef20a2e639a3333e717ac5
commit ccc56bc6e079569a0bef20a2e639a3333e717ac5
Author: Ceki Gulcu <ceki at 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.
More information about the logback-dev
mailing list