Author: ceki Date: Wed Sep 12 23:20:15 2007 New Revision: 1590 Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/ConsoleAppender.java logback/trunk/logback-examples/src/main/java/chapter4/ConfigurationTester.java logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-fileAppender.xml logback/trunk/logback-site/src/site/pages/manual/appenders.html Log: - minor changes - better docs in appenders.html Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/ConsoleAppender.java ============================================================================== --- logback/trunk/logback-core/src/main/java/ch/qos/logback/core/ConsoleAppender.java (original) +++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/ConsoleAppender.java Wed Sep 12 23:20:15 2007 @@ -1,11 +1,11 @@ /** - * LOGBack: the reliable, fast and flexible logging library for Java. - * - * Copyright (C) 1999-2006, QOS.ch - * - * This library is free software, you can redistribute it and/or - * modify it under the terms of the GNU Lesser General Public License as - * published by the Free Software Foundation. + * Logback: the generic, reliable, fast and flexible logging framework. + * + * Copyright (C) 1999-2007, QOS.ch + * + * This library is free software, you can redistribute it and/or modify it under + * the terms of the GNU Lesser General Public License as published by the Free + * Software Foundation. */ package ch.qos.logback.core; @@ -31,7 +31,7 @@ protected String target = SYSTEM_OUT; /** - * As in most cases, the default constructor does nothing. + * As in most logback components, the default constructor does nothing. */ public ConsoleAppender() { } Modified: logback/trunk/logback-examples/src/main/java/chapter4/ConfigurationTester.java ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter4/ConfigurationTester.java (original) +++ logback/trunk/logback-examples/src/main/java/chapter4/ConfigurationTester.java Wed Sep 12 23:20:15 2007 @@ -1,3 +1,12 @@ +/** + * Logback: the generic, reliable, fast and flexible logging framework. + * + * Copyright (C) 1999-2007, QOS.ch + * + * This library is free software, you can redistribute it and/or modify it under + * the terms of the GNU Lesser General Public License as published by the Free + * Software Foundation. + */ package chapter4; import org.slf4j.Logger; @@ -37,6 +46,10 @@ } catch (JoranException je) { je.printStackTrace(); } + // After we've called Joran, let's print information about the + // internal status of logback + StatusPrinter.print(lc.getStatusManager()); + logger.debug("**Hello {}", new Bar()); MDC.put("testKey", "testValueFromMDC"); MDC.put("testKey2", "value2"); @@ -45,7 +58,5 @@ } Bar bar = new Bar(); bar.createLoggingRequest(); - - StatusPrinter.print(lc.getStatusManager()); } } Modified: logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-fileAppender.xml ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-fileAppender.xml (original) +++ logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-fileAppender.xml Wed Sep 12 23:20:15 2007 @@ -3,9 +3,6 @@ <appender name="FILE" class="ch.qos.logback.core.FileAppender"> <File>testFile.log</File> <Append>true</Append> - <Encoding>UTF-8</Encoding> - <BufferedIO>false</BufferedIO> - <ImmediateFlush>true</ImmediateFlush> <layout class="ch.qos.logback.classic.PatternLayout"> <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</Pattern> Modified: logback/trunk/logback-site/src/site/pages/manual/appenders.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/appenders.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/appenders.html Wed Sep 12 23:20:15 2007 @@ -286,10 +286,9 @@ </tr> </table> - <p> - In general, if you disable immediate flushing, then make sure to flush - any output streams when your application exits. Otherwise, log messages - will be lost as illustrated by the next example. + <p>In general, if you disable immediate flushing, then make sure to + flush any output streams when your application exits. Otherwise, log + messages will be lost as illustrated by the next example. </p> <em>Example 4.1: Exiting an application without flushing (<a href="../xref/chapter4/ExitWoes1.html">logback-examples/src/main/java/chapter4/ExitWoes1.java</a>)</em> @@ -325,31 +324,29 @@ } }</pre></div> - <p> - This example creates a <code>WriterAppender</code> that uses an - <code>OutputStreamWriter</code> - wrapping a <code>FileOutputStream</code> as its underlying <code>Writer</code> object, - with immediate flushing disabled. It then proceeds to log a single debug message. - According to <code>OutputStreamWriter</code> javadocs, each invocation of a - <code>write()</code> - method causes the encoding converter to be invoked on the given character(s). - The resulting bytes are accumulated in a buffer before being written - to the underlying output stream. As astonishing as this may seem, - running <code>ExitWoes1</code> will not produce any output in the file - <em>exitWoes1.log</em> - because the Java VM does not flush output streams when it exits. - Calling the <code>shutdownAndReset()</code> method of a <code>LoggerContext</code> - ensures that all - appenders in the hierarchy are closed and their buffers are flushed. The - <code>ExitWoes2</code> class uses this statement and outputs a logging - request. + <p>This example creates a <code>WriterAppender</code> that uses an + <code>OutputStreamWriter</code> wrapping a + <code>FileOutputStream</code> as its underlying <code>Writer</code> + object, with immediate flushing disabled. It then proceeds to log a + single debug message. According to <code>OutputStreamWriter</code> + javadocs, each invocation of a <code>write()</code> method causes + the encoding converter to be invoked on the given character(s). The + resulting bytes are accumulated in a buffer before being written to + the underlying output stream. As astonishing as this may seem, + running <code>ExitWoes1</code> will not produce any data in the file + <em>exitWoes1.log</em> because the Java VM does not flush output + streams when it exits. Calling the <code>shutdownAndReset()</code> + method of a <code>LoggerContext</code> ensures that all appenders in + the hierarchy are closed and their buffers are flushed. The <code><a + href="../xref/chapter4/ExitWoes2.html">ExitWoes2</a></code> class + uses this statement and outputs a logging request. </p> - <p> - The <code>WriterAppender</code> is the super class of four other appenders, - namely <code>ConsoleAppender</code>, <code>FileAppender</code> which in turn is - the super class of <code>RollingFileAppender</code>. The next figure illustrates - the class diagram for <code>WriterAppender</code> and its subclasses. + <p>The <code>WriterAppender</code> is the super class of three other + appenders, namely <code>ConsoleAppender</code>, + <code>FileAppender</code> which in turn is the super class of + <code>RollingFileAppender</code>. The next figure illustrates the + class diagram for <code>WriterAppender</code> and its subclasses. </p> <img src="images/chapter4/fileAppenderUML.png" alt="A UML diagram showing FileAppender"/> @@ -357,15 +354,16 @@ <a name="ConsoleAppender"></a> <h3>ConsoleAppender</h3> - <p> - The <a href="../xref/ch/qos/logback/core/ConsoleAppender.html"> - <code>ConsoleAppender</code></a>, as the name indicates, appends on the console, - or more precisely on <em>System.out</em> or <em>System.err</em>, the former - being the default target. <code>ConsoleAppender</code> formats events with - a layout specified by the user. Both <em>System.out</em> and <em>System.err</em> - are <code>java.io.PrintStream</code> objects. - Consequently, they are wrapped inside an <code>OutputStreamWriter</code> - which buffers I/O operations but not character conversions. + <p>The <a href="../xref/ch/qos/logback/core/ConsoleAppender.html"> + <code>ConsoleAppender</code></a>, as the name indicates, appends on + the console, or more precisely on <em>System.out</em> or + <em>System.err</em>, the former being the default + target. <code>ConsoleAppender</code> formats events with a layout + specified by the user. Layouts will be discussed in the next + chapter. Both <em>System.out</em> and <em>System.err</em> are + <code>java.io.PrintStream</code> objects. Consequently, they are + wrapped inside an <code>OutputStreamWriter</code> which buffers I/O + operations but not character conversions. </p> <table class="bodyTable"> @@ -394,8 +392,8 @@ </tr> </table> - <p> - Here is a sample configuration that uses <code>ConsoleAppender</code>. + <p>Here is a sample configuration that uses + <code>ConsoleAppender</code>. </p> <em>Example 4.2: ConsoleAppender configuration (logback-examples/src/main/java/chapter4/conf/logback-Console.xml)</em> @@ -414,29 +412,32 @@ </root> </configuration></pre></div> - <p> - To run this example, just issue the following command, - once in the <em>logback-examples</em> directory: + <p>After you have set your current path to the + <em>logback-examples</em> directory, you can give the above + configuration file a whirl by issuing the following command: </p> - -<div class="source"><pre>java chapter4.ConfigurationTester src/main/java/chapter4/conf/logback-Console.xml</pre></div> + +<div class="source"><pre>java <a +href="../xref/chapter4/ConfigurationTester.html">chapter4.ConfigurationTester</a> src/main/java/chapter4/conf/logback-Console.xml</pre></div> <a name="FileAppender"></a> <h3>FileAppender</h3> - <p> - The <a href="../xref/ch/qos/logback/core/FileAppender.html"><code>FileAppender</code></a>, - a subclass of <code>WriterAppender</code>, - appends log events into a file. The file to write to is specified by - the <span class="option">File</span> option. - If the file already exists, it is either appended to, or truncated - depending on the value of the <span class="option">Append</span> option. - It uses a <code>FileOutputStream</code> which is wrapped by an <code>OutputStreamWriter</code>. - Note that <code>OutputStreamWriter</code> buffers I/O operations - but not character conversions. To optimize character conversions one - can set the <span class="option">BufferedIO</span> option to true - which effectively wraps the <code>OutputStreamWriter</code> with - a <code>BufferedWriter</code>. Options for <code>FileAppender</code> are summarized below. + <p>The <a + href="../xref/ch/qos/logback/core/FileAppender.html"><code>FileAppender</code></a>, + a subclass of <code>WriterAppender</code>, appends log events into a + file. The target fileis specified by the <span + class="option">File</span> option. If the file already exists, it + is either appended to, or truncated depending on the value of the + <span class="option">Append</span> option. + <code>FileAppender</code> uses a <code>FileOutputStream</code> which + is wrapped by an <code>OutputStreamWriter</code>. Note that + <code>OutputStreamWriter</code> buffers I/O operations but not + character conversions. To optimize character conversions one can set + the <span class="option">BufferedIO</span> option to true which + effectively wraps the <code>OutputStreamWriter</code> with a + <code>BufferedWriter</code>. Options for <code>FileAppender</code> + are summarized below. </p> <table class="bodyTable"> @@ -448,9 +449,11 @@ <tr class="b"> <td><b><span class="option">Append</span></b></td> <td><code>boolean</code></td> - <td>If true, events are appended at the end of an existing file. - Otherwise, if <span class="option">Append</span> is false, any existing - file is truncated. The <span class="option">Append</span> option is set to true by default.</td> + <td>If true, events are appended at the end of an existing file. + Otherwise, if <span class="option">Append</span> is false, any + existing file is truncated. The <span + class="option">Append</span> option is set to true by + default.</td> </tr> <tr class="a"> <td><b><span class="option">Encoding</span></b></td> @@ -460,17 +463,18 @@ <tr class="b"> <td><b><span class="option">BufferedIO</span></b></td> <td><code>boolean</code></td> - <td> - The <span class="option">BufferedIO</span> option is set to false by default. - If set to true, the underlying <code>OutputStreamWriter</code> is wrapped - by a <code>BufferedWriter</code> object. - Setting <span class="option">BufferedIO</span> to true automatically - sets the <span class="option">ImmediateFlush</span> option to false. - The name <span class="option">BufferedIO</span> is slightly misleading because - buffered IO is already supported by <code>OutputStreamWriter</code>. - Setting <span class="option">BufferedIO</span> to true has the effect of - buffering I/O as well as character to raw byte conversions, saving a few - CPU cycles in the process. + <td>The <span class="option">BufferedIO</span> option is set to + false by default. If set to true, the underlying + <code>OutputStreamWriter</code> is wrapped by a + <code>BufferedWriter</code> object. Setting <span + class="option">BufferedIO</span> to true automatically sets the + <span class="option">ImmediateFlush</span> option to false. The + name <span class="option">BufferedIO</span> is slightly + misleading because buffered IO is already supported by + <code>OutputStreamWriter</code>. Setting <span + class="option">BufferedIO</span> to true has the effect of + buffering I/O as well as character to raw byte conversions, + saving a few CPU cycles in the process. </td> </tr> <tr class="a"> @@ -481,48 +485,48 @@ <tr class="b"> <td><b><span class="option">File</span></b></td> <td><code>String</code></td> - <td> - The name of the file to write to. If the file does not exist, it is created. <br /> - On the MS Windows platform users frequently forget to escape back slashes. - For example, the value <em>c:\temp\test.log</em> is not likely to be interpreted - properly as <em>'\t'</em> is an escape sequence interpreted as a single - tab character <em>(\u0009)</em>. - Correct values can be specified as <em>c:/temp/test.log</em> or - alternatively as <em>c:\\temp\\test.log</em>. - The <span class="option">File</span> option has no default value. + <td>The name of the file to write to. If the file does not + exist, it is created. On the MS Windows platform users + frequently forget to escape back slashes. For example, the + value <em>c:\temp\test.log</em> is not likely to be interpreted + properly as <em>'\t'</em> is an escape sequence interpreted as a + single tab character <em>(\u0009)</em>. Correct values can be + specified as <em>c:/temp/test.log</em> or alternatively as + <em>c:\\temp\\test.log</em>. The <span + class="option">File</span> option has no default value. </td> </tr> <tr class="a"> <td><b><span class="option">ImmediateFlush</span></b></td> <td><code>boolean</code></td> - <td> - See <code>WriterAppender</code> options. - </td> + <td>See <code>WriterAppender</code> options.</td> </tr> </table> - <p> - By default, <code>FileAppender</code> performs a flush operation for - each event, ensuring that events are immediately written to disk. - Setting the <span class="option">ImmediateFlush</span> option to false can drastically reduce - I/O activity by letting <code>OutputStreamWriter</code> buffer bytes - before writing them on disk. For short messages, we have observed 2 or 3 - fold increases in logging throughput, i.e. the number of logs output - per unit of time. For longer messages, the throughput gains are somewhat - less dramatic, and range between 1.4 and 2 fold. Enabling the - <span class="option">BufferedIO</span> - option, that is buffering character to byte conversions, increases - performance by an additional 10% to 40% compared to only disk - I/O buffering (<span class="option">ImmediateFlush</span>=false). - Performance varies somewhat depending on the host machine as well as JDK version. - Throughput measurements are based on the <code>chapter4.IO</code> application. - Please refer to <a href="../xref/chapter4/IO.html"> - <em>logback-examples/src/main/java/chapter4/IO.java</em></a> - for actual source code. + <p>By default, <code>FileAppender</code> performs a flushes each + event, ensuring that events are immediately written to disk. + Setting the <span class="option">ImmediateFlush</span> option to + false can drastically reduce I/O activity by letting + <code>OutputStreamWriter</code> buffer bytes before writing them on + disk. For short messages, we have observed 2 or 3 fold increases in + logging throughput, i.e. the number of logs output per unit of + time. For longer messages, the throughput gains are somewhat less + dramatic, and range between 1.4 and 2 fold. Enabling the <span + class="option">BufferedIO</span> option, that is buffering character + to byte conversions, increases performance by an additional 10% to + 40% compared to only disk I/O buffering (<span + class="option">ImmediateFlush</span>=false). Performance varies + somewhat depending on the host machine as well as JDK version. + Throughput measurements are based on the <code>chapter4.IO</code> + application. Please refer to <a href="../xref/chapter4/IO.html"> + <em>logback-examples/src/main/java/chapter4/IO.java</em></a> for + actual source code. </p> - <p> - Configuring <code>FileAppender</code> can be done the following way: + <!-- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX --> + + <p>Configuring <code>FileAppender</code> can be done the following + way: </p> <em>Example 4.3: FileAppender configuration (logback-examples/src/main/java/chapter4/conf/logback-fileAppender.xml)</em> @@ -531,9 +535,6 @@ <b><appender name="FILE" class="ch.qos.logback.core.FileAppender"> <File>testFile.log</File> <Append>true</Append> - <Encoding>UTF-8</Encoding> - <BufferedIO>false</BufferedIO> - <ImmediateFlush>true</ImmediateFlush> <layout class="ch.qos.logback.classic.PatternLayout"> <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</Pattern>