September 2007 - logback-dev

[Bug 99] New: logback 0.9.8 keeps dropping and recreating connections
by bugzilla-daemon＠pixie.qos.ch 26 Sep '07

26 Sep '07

http://bugzilla.qos.ch/show_bug.cgi?id=99 Summary: logback 0.9.8 keeps dropping and recreating connections Product: logback-general Version: unspecified Platform: All OS/Version: All Status: NEW Severity: blocker Priority: P1 Component: build-structure AssignedTo: logback-dev(a)qos.ch ReportedBy: joern(a)huxhorn.de I have a serious problem with logback 0.9.8 that forced me to downgrade to 0.9.7 again. The socket-appender keeps dropping and recreating connections, missing log-events in the process. It does so at least once, i.e. creating a connection without writing a single event and then closing it again immeditaly. I tried to reporduce the behaviour in a simple test program but didn't succeed. Everything is fine in a simple test. In both of our "real" applications, however, this problem is definitly reproducible and just vanishes after a downgrade to 0.9.7. I suspect that the problem is connected to log4j-over-slf4j because that's one of the differences to my small test. We have the following dependencies: <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-api</artifactId> <scope>compile</scope> </dependency> <dependency> <groupId>commons-logging</groupId> <artifactId>commons-logging</artifactId> <scope>provided</scope> </dependency> <dependency> <groupId>org.slf4j</groupId> <artifactId>jcl104-over-slf4j</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>org.slf4j</groupId> <artifactId>log4j-over-slf4j</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>log4j</groupId> <artifactId>log4j</artifactId> <scope>provided</scope> </dependency> <dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-core</artifactId> <scope>compile</scope> </dependency> <dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-classic</artifactId> <scope>compile</scope> </dependency> with slf4j 1.4.3 and logback 0.9.8 as version. We use several third-party jars in our apps, e.g. spring, commons-stuff etc., so we have to map both commons-logging as well as log4j to logback. This worked perfectly up to version 0.9.7 but doesn't work anymore! I'm sorry about this rather obscure error report but I'm really quite clueless about the problem myself. I just checked the svn repos and the last socket appender change was done 4 month ago so that can't be responsible... I'll try to investigate this some more but you might already know what's wrong since you know what changed between 0.9.7 and 0.9.8. The problem exists on at least Windows and Solaris, btw. -- Configure bugmail: http://bugzilla.qos.ch/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are the assignee for the bug, or are watching the assignee.

1 2

Eclipse plugin
by Vicente Ferrer 26 Sep '07

26 Sep '07

Hi to all, I'm having some problems with logback eclipse plugin... ¿somebody has used the logback eclipse plugin with success? Thanks a lot.

2 3

[Bug 97] New: Avoid printing stack traces under certain conditions
by bugzilla-daemon＠pixie.qos.ch 19 Sep '07

19 Sep '07

http://bugzilla.qos.ch/show_bug.cgi?id=97 Summary: Avoid printing stack traces under certain conditions Product: logback-classic Version: unspecified Platform: PC OS/Version: Windows Status: NEW Severity: enhancement Priority: P1 Component: Other AssignedTo: logback-dev(a)qos.ch ReportedBy: noreply.ceki(a)qos.ch It would be useful if under certain very specific conditions, logback avoided printing stack traces. In particular, in server applications IOEXceptions are thrown under normal conditions, such as when the client closes its connection to the server. Typical code would look like: try { event = (AuditEvent) ois.readObject(); } catch (java.io.EOFException e) { logger.info("Caught java.io.EOFException closing connection.", e); break; } catch (IOException e) { logger.info("Caught java.io.IOException: ", e); break; } catch (ClassNotFoundException e) { logger.error("Unexpected ClassNotFoundException.", e); writeResponse(e); break; } Most of the time we would like to avoid printing the stack trace for the two exceptions but not the third. Possible solution: Marker ignoreST = MarkerFactgory.getMarker("IGNORE_STACK_TRACE"); logger.info(ignoreST, "Caught java.io.EOFException closing connection.", e); Note that even if most of the time we would like to avoid printing the stack trace, it should still be possible to allow st printing by overriding some parameter. -- Configure bugmail: http://bugzilla.qos.ch/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are the assignee for the bug, or are watching the assignee.

1 1

[Bug 96] New: Make ContextSelectors truely pluggable/configurable
by bugzilla-daemon＠pixie.qos.ch 18 Sep '07

18 Sep '07

http://bugzilla.qos.ch/show_bug.cgi?id=96 Summary: Make ContextSelectors truely pluggable/configurable Product: logback-classic Version: unspecified Platform: PC OS/Version: Windows Status: NEW Severity: major Priority: P1 Component: Other AssignedTo: logback-dev(a)qos.ch ReportedBy: lars(a)koedderitzsch.net Currently the ContextSelectors in Logback are limited to Default and JNDI, whereas a system property leads to ContextJNDISelector being pulled. This stuff is all hardcoded therefore not configurable. I cannot use ContextJNDISelector because of a bug(?) in Websphere 6.1. In WS 6.1. env-entry values are seemingly bound to the JNDI at a very late point. This leads to that the JNDI lookups fail because Logback initializes (through jlc-over-sl4j) way earlier in the application startup phase. It boils down to that I cannot use ContextJNDISelector in WS 6.1. For this reason I wanted to provide a custom ContextSelector to Logback, which is currently not possible. -- Configure bugmail: http://bugzilla.qos.ch/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are the assignee for the bug, or are watching the assignee.

1 2

[Bug 84] New: LoggerContextFilter is useless (org.slf4j.Loggerfactory bug ++)
by bugzilla-daemon＠pixie.qos.ch 18 Sep '07

18 Sep '07

http://bugzilla.qos.ch/show_bug.cgi?id=84 Summary: LoggerContextFilter is useless (org.slf4j.Loggerfactory bug ++) Product: logback-core Version: unspecified Platform: All OS/Version: All Status: NEW Severity: normal Priority: P1 Component: Other AssignedTo: logback-dev(a)qos.ch ReportedBy: jel(a)linofee.org Since LoggerFactory obtains the LoggerContext to use in its static init stage, using a LoggerContextFilter as described in Chapter 8 is completely useless, since the JNDI selector is never consulted again. Digging deeper on that issue reveals, that using a ContextJNDISelector (even if it would work) rarely leads to the intended behavior (e.g. webapp related logging), and is probably not thread safe wrt. common practice and intended logging. E.g. in tomcat we have two different cases: a) each webapp provides its own slfj4*.jar as well as *logback*.jar b) slfj4*.jar as well as *logback*.jar are shared via tomcat/common/lib or tomcat/share/lib c) a und b mixed Well, to get things right, one can say case c) is unsupported ;-). In case a) logback has its own playground, so using JNDI doesn't make sense at all, since the webapp/logback has its own playground - doesn't interfere with other web apps since loaded via its dedicated classloader. However case b) is a little bit more challenging. Here the LoggerFactory and other classes are !shared! between several webapps, since loading is delegated from the dedicated webapp classloader to the shared webapp classloader, which picks up everything in share/lib , common/lib. So right now in 0.9.7, even if one uses JNDISelector a per webapp logging is impossible: The first webapp, which asks for a LoggerFactory always wins! All other webapps, which ask later for a LoggerFactory.getLogger() will get a Logger from the LoggerContext associated with the first webapp, since the context is "cached", i.e. the JNDI selector gets never consulted again. Assuming the LoggerFactory problem gets fixed by using e.g. public static Logger getLogger(* *) { return StaticLoggerBinder.SINGLETON.getLoggerFactory().getLogger(**); } there is still a problem wrt. common practice aka log* usage pattern and webapp shared classes, which can not be resolved by JNDI: Today most developer use something like: public class XY { private static [final] Logger log = LoggerFactory.getLogger(XY.class); ... } That implies the same problem, as with the current LoggerFactory bug: The class gets the Logger from the context associated with the first webapp, which needs the shared class. And that's why all other webapps, which later need this class will use the the logger context of the first webapp. So e.g. if webapp A is configured to log to /var/log/a.log and another webapp B is configured to log to /var/log/b.log the loging output of shared classes will always go to /var/log/a.log if webapp used the classes in question first, no matter on which thread aka in which webapp the shared classes are used. So even if LoggerFactory gets fixed, JNDI selector is of little use, if one wants to have a webapp dedicated log as soon as shared classes are involved. The only way to solve the didcated webapp log problem a can think of, to introduce another level of indirection in the Logger.log* etc. method, which takes care of thread local settings and the settings of its parent threads (e.g. an application may start other threads, which do not inherit the thread local settings from the current thread ...). But this would probably influence the performance of logback in a rather negative way. Another idea might be an architecture re-design: sharing Loggers would be no problem because of thread local AppenderContext soft ref, which points to an Appender in the global AppenderStore singleton ... RFE: These problems should be reflected chapter 8 of the logback manual to avoid further confusion ... -- Configure bugmail: http://bugzilla.qos.ch/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are the assignee for the bug, or are watching the assignee.

1 3

svn commit: r1593 - logback/trunk/logback-classic/src/main/java/org/slf4j/impl
by noreply.ceki＠qos.ch 18 Sep '07

18 Sep '07

Author: ceki Date: Tue Sep 18 22:43:32 2007 New Revision: 1593 Modified: logback/trunk/logback-classic/src/main/java/org/slf4j/impl/StaticLoggerBinder.java Log: Allowing the user to specify a custom ContextSelector as requested in bug 96. http://bugzilla.qos.ch/show_bug.cgi?id=96 Modified: logback/trunk/logback-classic/src/main/java/org/slf4j/impl/StaticLoggerBinder.java ============================================================================== --- logback/trunk/logback-classic/src/main/java/org/slf4j/impl/StaticLoggerBinder.java (original) +++ logback/trunk/logback-classic/src/main/java/org/slf4j/impl/StaticLoggerBinder.java Tue Sep 18 22:43:32 2007 @@ -9,6 +9,9 @@ */ package org.slf4j.impl; +import java.lang.reflect.Constructor; +import java.lang.reflect.InvocationTargetException; + import org.slf4j.ILoggerFactory; import org.slf4j.LoggerFactory; import org.slf4j.helpers.Util; @@ -22,6 +25,7 @@ import ch.qos.logback.classic.util.ContextInitializer; import ch.qos.logback.core.CoreGlobal; import ch.qos.logback.core.joran.spi.JoranException; +import ch.qos.logback.core.util.Loader; import ch.qos.logback.core.util.OptionHelper; import ch.qos.logback.core.util.StatusPrinter; @@ -70,6 +74,9 @@ } else if (contextSelectorStr.equals("JNDI")) { // if jndi is specified, let's use the appropriate class contextSelector = new ContextJNDISelector(defaultLoggerContext); + } else { + contextSelector = dynamicalContextSelector(defaultLoggerContext, + contextSelectorStr); } } catch (Throwable t) { // we should never get here @@ -78,6 +85,14 @@ } } + static ContextSelector dynamicalContextSelector( + LoggerContext defaultLoggerContext, String contextSelectorStr) throws ClassNotFoundException, SecurityException, NoSuchMethodException, IllegalArgumentException, InstantiationException, IllegalAccessException, InvocationTargetException { + Class contextSelectorClass = Loader.loadClass(contextSelectorStr); + Constructor cons = contextSelectorClass + .getConstructor(new Class[] { LoggerContext.class }); + return (ContextSelector) cons.newInstance(defaultLoggerContext); + } + public ILoggerFactory getLoggerFactory() { if (contextSelector == null) { throw new IllegalStateException(

1 0

Unexpected problem with logback
by Vicente Ferrer 17 Sep '07

17 Sep '07

Hi, I´m an habitual user of log4j and I´m trying to port my application to logback. The first impression of this new tool was very good; the pluggin for Eclipse IDE has a good apparience. But I´m experiencing a little worrisomely problem: some logging lines cause the Eclipse plugin stops to write the rest of logging lines. If I activate a ConsoleAppender, I can view the rest of the logging lines at the standard console, but the Eclipse plugins don´t show that lines. The line causing the Eclipse plugin stops to work is: Method[] methods = clazz.getDeclaredMethods(); log.debug("method: {}", methods[i]); I´ve seen an error on the Error Log eclipse´s view saying that java.lang.reflect.Method is not Serializable, and the plugin do not show the rest of the logging lines. I´ve experimented similar error when I try to log a message line that contains an own object such as a bean. In this case, the error is a ClassNotFoundException because of the logback eclipse plugin can´t find the bean class. The bean class is in my proyect classpath and in the application server, logback goes fine because it can reach the bean class. How can I make accesible my classes to the logback plugin. Could be these two bugs of the plugin? If you need it, I can post the stacktrace of the error that appears at Eclipse Error Log View. Thanks a lot. P.D.: I´ve sent this message to the logback user´s list, but later I´ve thought the most appropiate list for this problem should be the dev list.

1 1

svn commit: r1592 - in logback/trunk/logback-core/src: main/java/ch/qos/logback/core test/java/ch/qos/logback/core
by noreply.ceki＠qos.ch 14 Sep '07

14 Sep '07

Author: ceki Date: Fri Sep 14 09:20:03 2007 New Revision: 1592 Added: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/StopWatch.java logback/trunk/logback-core/src/test/java/ch/qos/logback/core/StopWatchTest.java Log: - Adding StopWatch functionaliry to logback core Added: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/StopWatch.java ============================================================================== --- (empty file) +++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/StopWatch.java Fri Sep 14 09:20:03 2007 @@ -0,0 +1,87 @@ +package ch.qos.logback.core; + +import java.text.DecimalFormat; + +public class StopWatch { + + private static final int STARTED = 1; + private static final int STOPPED = 2; + private static final int NANOS_IN_ONE_MICROSECOND = 1000; + private static final int NANOS_IN_ONE_MILLISECOND = 1000*1000; + private static final int NANOS_IN_ONE_SECOND = 1000*1000*1000; + private static final DecimalFormat DECIMAL_FORMAT = new DecimalFormat("0.000"); + + final String name; + final long startTime; + long stopTime; + int status; + + StopWatch(String name) { + this.name = name; + this.startTime = System.nanoTime(); + this.status = STARTED; + } + + StopWatch stop() { + this.status = STOPPED; + this.stopTime = System.nanoTime(); + return this; + } + + @Override + public String toString() { + StringBuffer buf = new StringBuffer(); + buf.append("StopWatch ["); + buf.append(name); + buf.append("] "); + + switch (status) { + case STARTED: + buf.append("STARTED"); + break; + case STOPPED: + buf.append("STOPPED at "); + if(getResultInNanos() < 10*NANOS_IN_ONE_MICROSECOND) { + buf.append(getResultInNanos()); + buf.append(" nanoseconds."); + } + else if (getResultInNanos() < 10*NANOS_IN_ONE_MILLISECOND) { + buf.append(getResultInMicros()); + buf.append(" microseconds."); + } else if (getResultInNanos() < 5*NANOS_IN_ONE_SECOND) { + + buf.append(getResultInMillis()); + buf.append(" milliseconds."); + } else { + double seconds = getResultInSeconds(); + buf.append(DECIMAL_FORMAT.format(seconds)); + buf.append(" seconds."); + + } + break; + default: + new IllegalStateException("Status " + status + " is not expected"); + } + return buf.toString(); + } + + public final long getResultInNanos() { + if (status == STARTED) { + return 0; + } else { + return stopTime - startTime; + } + } + + public final long getResultInMicros() { + return getResultInNanos() / NANOS_IN_ONE_MICROSECOND; + } + + public final long getResultInMillis() { + return getResultInNanos() / NANOS_IN_ONE_MILLISECOND; + } + + public final double getResultInSeconds() { + return ((double) getResultInNanos() / NANOS_IN_ONE_SECOND); + } +} Added: logback/trunk/logback-core/src/test/java/ch/qos/logback/core/StopWatchTest.java ============================================================================== --- (empty file) +++ logback/trunk/logback-core/src/test/java/ch/qos/logback/core/StopWatchTest.java Fri Sep 14 09:20:03 2007 @@ -0,0 +1,28 @@ +package ch.qos.logback.core; + +import junit.framework.TestCase; + +public class StopWatchTest extends TestCase { + + public StopWatchTest(String name) { + super(name); + } + + protected void setUp() throws Exception { + super.setUp(); + } + + protected void tearDown() throws Exception { + super.tearDown(); + } + + public void testBasic() throws InterruptedException { + StopWatch sw = new StopWatch("testBasic"); + + Thread.sleep(55100); + System.out.println(sw.stop().toString()); + + + } + +}

1 0

svn commit: r1591 - in logback/trunk: logback-core/src/main/java/ch/qos/logback/core/rolling logback-examples/src/main/java/chapter4 logback-examples/src/main/java/chapter4/conf logback-site/src/site/pages logback-site/src/site/pages/manual
by noreply.ceki＠qos.ch 13 Sep '07

13 Sep '07

Author: ceki Date: Thu Sep 13 23:23:37 2007 New Revision: 1591 Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/rolling/FixedWindowRollingPolicy.java logback/trunk/logback-examples/src/main/java/chapter4/ConfigurationTester.java logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-RollingSizeBased.xml logback/trunk/logback-site/src/site/pages/codes.html logback/trunk/logback-site/src/site/pages/manual/appenders.html Log: - ongoing work on chapter4 (appenders) Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/rolling/FixedWindowRollingPolicy.java ============================================================================== --- logback/trunk/logback-core/src/main/java/ch/qos/logback/core/rolling/FixedWindowRollingPolicy.java (original) +++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/rolling/FixedWindowRollingPolicy.java Thu Sep 13 23:23:37 2007 @@ -61,7 +61,7 @@ if (getParentFileName() == null) { addWarn("The File name option must be set before using this rolling policy."); addWarn(SEE_PARENT_FN_NOT_SET); - throw new IllegalStateException("The ActiveFileName option must be set."); + throw new IllegalStateException("The \"File\" option must be set."); } if (maxIndex < minIndex) { 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 Thu Sep 13 23:23:37 2007 @@ -55,6 +55,7 @@ MDC.put("testKey2", "value2"); for (int i = 0; i < 10; i++) { logger.debug("logging statement " + i); + Thread.sleep(1000); } Bar bar = new Bar(); bar.createLoggingRequest(); Modified: logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-RollingSizeBased.xml ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-RollingSizeBased.xml (original) +++ logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-RollingSizeBased.xml Thu Sep 13 23:23:37 2007 @@ -1,16 +1,16 @@ <configuration> <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> - <File>testFile.log</File> + <File>test.log</File> <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy"> - <FileNamePattern>testFile.%i.log.zip</FileNamePattern> + <FileNamePattern>tests.%i.log.zip</FileNamePattern> <MinIndex>1</MinIndex> <MaxIndex>3</MaxIndex> </rollingPolicy> <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"> - <MaxFileSize>5MB</MaxFileSize> + <MaxFileSize>1KB</MaxFileSize> </triggeringPolicy> <layout class="ch.qos.logback.classic.PatternLayout"> <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</Pattern> Modified: logback/trunk/logback-site/src/site/pages/codes.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/codes.html (original) +++ logback/trunk/logback-site/src/site/pages/codes.html Thu Sep 13 23:23:37 2007 @@ -7,7 +7,7 @@ </head> <body> - <script > + <script> prefix=''; </script> @@ -37,8 +37,9 @@ </li> <li> - <a href="#fwrp_parentFileName_not_set">The File name option - must be set before <code>FixedWindowRollingPolicy</code> + <a href="#fwrp_parentFileName_not_set">The File option must be set before + <code>FixedWindowRollingPolicy</code> </a> </li> @@ -131,19 +132,20 @@ <dt> <a name="fwrp_parentFileName_not_set"> - The File name option must be set before <code>FixedWindowRollingPolicy</code> + The File option must be set before + <code>FixedWindowRollingPolicy</code> </a> </dt> <dd> The File option is mandatory with - <code>FixedWindowRollingPolicy</code>. Moreover, the File option - must be set before the declaration configuring - <code>FixedWindowRollingPolicy</code>. + <code>FixedWindowRollingPolicy</code>. Moreover, the File option must be set before the + <code>FixedWindowRollingPolicy</code> element. - See the logback manual's chapter about - <a href="http://logback.qos.ch/manual/appenders.html#FixedWindowRollingPolicy"> + Refer to the logback manual on + <a href="manual/appenders.html#FixedWindowRollingPolicy"> FixedWindowRollingPolicy </a> for more information. 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 Thu Sep 13 23:23:37 2007 @@ -523,10 +523,8 @@ actual source code. -  - - Configuring <code>FileAppender</code> can be done the following - way: + Below is an example of a cconfiguration file for + <code>FileAppender</code>: Example 4.3: FileAppender configuration (logback-examples/src/main/java/chapter4/conf/logback-fileAppender.xml) @@ -547,9 +545,9 @@ </root> </configuration></pre></div> - - To run this example, use the provided <code>ConfigurationTester</code> by - issuing the following command, once in the logback-examples/target/classes: + After changing the current directory to + logback-examples, run this example by lauching the + following command: <div class="source"><pre>java chapter4.ConfigurationTester src/main/java/chapter4/conf/logback-fileAppender.xml</pre></div> @@ -558,28 +556,32 @@ <a name="RollingFileAppender"></a> <h3>RollingFileAppender</h3> - - <a href="../xref/ch/qos/logback/core/rolling/RollingFileAppender.html"><code>RollingFileAppender</code></a> - extends <code>FileAppender</code> by - allowing rolling from a log file to another. For example, - <code>RollingFileAppender</code> can log to a log.txt file and, - once a certain condition is met, change its logging target to another file. - - - There are two important logback componenents that interact with - <code>RollingFileAppender</code>. First, <code>RollingPolicy</code> - implementations define the procedure that will be followed when - the rollover happens. The second componenent is - <code>TriggeringPolicy</code> implementations that are used - to check wether the rollover must happen or not at a given time. - - - - To be of any use, a <code>RollingFileAppender</code> must have - both a <code>RollingPolicy</code> and a <code>TriggeringPolicy</code> - set up. However, if its <code>RollingPolicy</code> also implements the - <code>TriggeringPolicy</code> interface, then only the former needs to be - set up. + <a + href="../xref/ch/qos/logback/core/rolling/RollingFileAppender.html"><code>RollingFileAppender</code></a> + extends <code>FileAppender</code> with the capability to roll log + files. For example, <code>RollingFileAppender</code> can log to a + file named log.txt file and, once a certain condition is + met, change its logging target to another file. + + + There are two important logback componenents that interact with + <code>RollingFileAppender</code>. First, a + <code>RollingPolicy</code> instance attached to the + <code>RollingFileAppender</code> is responsible for undertaking the + action for perfoming a rollover. Second, a + <code>TriggeringPolicy</code> instance attached to a + <code>RollingFileAppender</code> will determine if and exactly when + rollover happens Thus, <code>RollingPolicy</code> is responsible for + the what and <code>TriggeringPolicy</code> is responsible + for the when. + + + To be of any use, a <code>RollingFileAppender</code> must have + both a <code>RollingPolicy</code> and a + <code>TriggeringPolicy</code> set up. However, if its + <code>RollingPolicy</code> also implements the + <code>TriggeringPolicy</code> interface, then only the former needs + to be set up. Here are the available options for <code>RollingFileAppender</code>: @@ -623,10 +625,9 @@ <tr class="b"> <td>RollingPolicy</td> <td><code>RollingPolicy</code></td> - <td> - This option is the component that will dictate - <code>RollingFileAppender</code>'s behaviour when rollover - occurs. See more information below. + <td>This option is the component that will dictate + <code>RollingFileAppender</code>'s behaviour when rollover + occurs. See more information below. </td> </tr> <tr class="a"> @@ -642,9 +643,10 @@ <h3>Rolling policies</h3> - <a href="../xref/ch/qos/logback/core/rolling/RollingPolicy.html"><code>RollingPolicy</code></a> - implementations are responsible for the - rollover procedure. They manage file renaming and in occasion file deleting. + <a + href="../xref/ch/qos/logback/core/rolling/RollingPolicy.html"><code>RollingPolicy</code></a> + is responsible for the rollover procedure. It manages file renaming + and in occasion file deleting. The <code>RollingPolicy</code> interface is presented below: @@ -660,33 +662,33 @@ public void setParent(FileAppender appender); }</pre></div> - - The <code>rollover</code> method proceeds to the file change, renaming or deletion. - The <code>getNewActiveFileName()</code> method is called to compute a new file name, with - respect to the configuration elements that were injected in the <code>RollingPolicy</code>. - Lastly, a <code>RollingPolicy</code> knows about its parent. + The <code>rollover</code> method proceeds to the file change, + renaming or deletion. The <code>getNewActiveFileName()</code> + method is called to compute a new file name, with respect to the + configuration elements that were injected into the + <code>RollingPolicy</code>. Lastly, a <code>RollingPolicy</code> is + given a reference to its parent via the <code>setParent</code> + method. <a name="FixedWindowRollingPolicy"></a> <h4>FixedWindowRollingPolicy</h4> - - When rolling over, <a href="../xref/ch/qos/logback/core/rolling/FixedWindowRollingPolicy.html"> - <code>FixedWindowRollingPolicy</code></a> - renames files according to a fixed window algorithm as described below. + When rolling over, <a + href="../xref/ch/qos/logback/core/rolling/FixedWindowRollingPolicy.html"> + <code>FixedWindowRollingPolicy</code></a> renames files according to + a fixed window algorithm as described below. - - The File option, which is configured in the - <code>FileAppender</code> element, is required. It represents the name of the file - to write to. The FileNamePattern - option represents the file name pattern for the archived (rolled over) log files. - The FileNamePattern option, which is also required, must include - an integer token, that is the string %i - somewhere within the pattern. + + The FileNamePattern option represents + the file name pattern for the archived (rolled over) log files. The + FileNamePattern option, which is also + required, must include an integer token, that is the string + %i somewhere within the pattern. - - Here are the available options for <code>FixedWindowRollingPolicy</code> + Here are the available options for + <code>FixedWindowRollingPolicy</code> <table class="bodyTable"> @@ -696,176 +698,141 @@ <th>Description</th> </tr> <tr class="b"> - <td>FileNamePattern</td> - <td><code>String</code></td> + <td>MinIndex</td> + <td><code>int</code></td> <td> - - This option represents the pattern that will be followed by - the <code>FixedWindowRollingPolicy</code> when renaming the - log files. If must contain the string %i, which will - indicate the position where to insert the file's index. - - - For example, using MyLogFile%i.log, associated with - minimum and maximum values of 1 and 3 will produce - files named MyLogFile1.log, MyLogFile2.log and - MyLogFile3.log. - - - File compression is also specified in the - FileNamePattern option. - MyLogFile%i.log.zip will indicate to the - <code>FixedWindowRollingPolicy</code> that the archived file - must be compressed using the zip format. The gz - format is also supported. + This option represents the lower bound for the window's + index. </td> - </tr> - <tr class="a"> - <td>MaxIndex</td> - <td><code>int</code></td> + </tr> + <tr class="a"> + <td>MaxIndex</td> + <td><code>int</code></td> <td> - - This option represents the maximum border of the window algorithm. + This option represents the upper bound for the window's + index. </td> </tr> <tr class="b"> - <td>MinIndex</td> - <td><code>int</code></td> + <td>FileNamePattern</td> + <td><code>String</code></td> <td> - - This option represents the minimum border of the window algorithm. + This option represents the pattern that will be followed by + the <code>FixedWindowRollingPolicy</code> when renaming the + log files. If must contain the string %i, which will + indicate the position where the value of the current window + index will be inserted. + + For example, using MyLogFile%i.log, associated + with minimum and maximum values of 1 and 3 + will produce archive files named MyLogFile1.log, + MyLogFile2.log and MyLogFile3.log. + + Note that file compression is also specified via the FileNamePattern option. For example, the + file name pattern MyLogFile%i.log.zip will indicate + to the <code>FixedWindowRollingPolicy</code> that the archived + file must be compressed using the zip format; + gz format is also supported. </td> - </tr> + </tr> + </table> - - Given that this rollover algorithm requires as many file - renaming operations as the window size, large window sizes are - discouraged. The current implementation will automatically - reduce the window size to 12 when larger values are specified by - the user. + Given that the fixed window rolling policy requires as many file + renaming operations as the window size, large window sizes are + strongly discouraged. The current implementation will automatically + reduce the window size to 12, when larger values are specified by + the user. - - Here is an example of file handling by <code>FixedWindowRollingPolicy</code>. - We suppose that the MinIndex is set to 1 and - MaxIndex is set to 3. The - FileNamePattern option is set to foo%i.log, and - the FileNamePattern - option is set to foo.log. + Let us go over a more concrete example of the fixed windows + rollover policy. Suppose that the MinIndex is set to 1, MaxIndex set to 3, that FileNamePattern option is set to + foo%i.log, and that FileNamePattern option is set to + foo.log. <table class="bodyTable"> <tr class="a"> - <th> - Steps - </th> - <th> - Active file name - </th> - <th> - Archived file names - </th> + <th>Number of rollovers</th> + <th>Active output target</th> + <th>Archived log files</th> <th>Description</th> </tr> <tr class="b"> - <td> - 0 - </td> - <td> - foo.log - </td> - <td> - - - </td> - <td> - No rollover has happened yet, logback logs - into the initial file. + <td>0</td> + <td>foo.log</td> + <td>-</td> + <td>No rollover has happened yet, logback logs into the initial + file. </td> </tr> <tr class="a"> - <td> - 1 - </td> - <td> - foo.log - </td> - <td> - foo1.log - </td> - <td> - First rollover. foo.log is renamed into foo1.log and - a new foo.log file is created and used for the output. + <td>1</td> + <td>foo.log</td> + <td>foo1.log</td> + <td>First rollover. foo.log is renamed as + foo1.log. A new foo.log file is created and + becomes the active output target. </td> </tr> <tr class="b"> - <td> - 2 - </td> - <td> - foo.log - </td> - <td> - foo2.log, foo1.log - </td> - <td> - Second rollover. foo.log is renamed into foo1.log and - the old foo1.log is renamed into foo2.log. - Again, a new foo.log file is created and used for the output. + <td>2</td> + <td>foo.log</td> + <td>foo1.log, foo2.log</td> + <td>Second rollover. foo1.log is renamed as + foo2.log. foo.log is renamed as + foo1.log. A new foo.log file is created and + becomes the active output target. </td> </tr> <tr class="a"> - <td> - 3 - </td> - <td> - foo.log - </td> - <td> - foo3.log, foo2.log, foo1.log - </td> - <td> - Third rollover. foo.log is renamed into foo1.log and - the old foo1.log is renamed into foo2.log. As well, the - old foo2.log is renamed into foo3.log. - A new foo.log file is created and used for the output. + <td>3</td> + <td>foo.log</td> + <td>foo1.log, foo2.log, foo3.log</td> + <td>Third rollover. foo2.log is renamed as + foo3.log. foo1.log is renamed as + foo2.log. foo.log is renamed as + foo1.log. A new foo.log file is created and + becomes the active output target. </td> </tr> <tr class="b"> - <td> - 4 - </td> - <td> - foo.log - </td> - <td> - foo3.log, foo2.log, foo1.log - </td> - <td> - From the fourth rollover, the old foo3.log file is deleted. The files - are all renamed with an increment to their index, and a new foo.log - file is created and used for the output. - From this moment on, there will always be 4 log files available, each being present - for the time of 3 rollovers and being deleted afterwards. + <td>4</td> + <td>foo.log</td> + <td>foo1.log, foo2.log, foo3.log</td> + <td>In this and subsequent rounds, the rollover begins by + deleting foo3.log. Otherfiles are renamed by + incrementing their index as shown in previous steps. In this and + subsequent rollovers, there will be three archive logs and one + active log file. </td> </tr> </table> - - Here is a sample configuration to use <code>RollingFileAppender</code> - and <code>FixedWindowRollingPolicy</code>. + The configuration file below gives an example of configuring + <code>RollingFileAppender</code> and + <code>FixedWindowRollingPolicy</code>. Note that the File option is mandatory even if it contains + some of the same information as conveyed with the FileNamePattern option. Example 4.4: Sample configuration of a <code>RollingFileAppender</code> using a <code>FixedWindowRollingPolicy</code> (logback-examples/src/main/java/chapter4/conf/logback-RollingFixedWindow.xml) <div class="source"><pre><configuration> <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> - <File>testFile.log</File> + <File>test.log</File> + <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy"> - <FileNamePattern>testFile.%i.log.zip</FileNamePattern> + <FileNamePattern>tests.%i.log.zip</FileNamePattern> <MinIndex>1</MinIndex> <MaxIndex>3</MaxIndex> </rollingPolicy> @@ -888,28 +855,26 @@ <h4>TimeBasedRollingPolicy</h4> <a href="../xref/ch/qos/logback/core/rolling/TimeBasedRollingPolicy.html"> - <code>TimeBasedRollingPolicy</code></a> is both easy to configure and quite powerful. - It allows the rollover to be made based on time conditions. It is possible to specify - that the rollover must occur each day, or month, for example. - - - <code>TimeBasedRollingPolicy</code>'s only option is the - FileNamePattern. - - - - In order to use - <code>TimeBasedRollingPolicy</code>, the - FileNamePattern option must be set. It basically - specifies the name of the rolled log files. The value - FileNamePattern should consist of the name of the file, - plus a suitably placed %d conversion specifier. - The %d conversion specifier may contain a date and time pattern as - specified by the <code>java.text.SimpleDateFormat</code> class. - If the date and time pattern is omitted, then the default pattern - of yyyy-MM-dd is assumed. The following examples should - clarify the point. + <code>TimeBasedRollingPolicy</code></a> is probably the most + popular rolling polciy. It allows defines a rollover policy based + on time, say by day or month. + + + <code>TimeBasedRollingPolicy</code>'s has only one mandatory + option, namely FileNamePattern. + + + FileNamePattern option defines the + name of the rolled (archived) log files. Its value FileNamePattern should consist of the name of + the file, plus a suitably placed %d conversion specifier. + The %d conversion specifier may contain a date and time + pattern as specified by the <code>java.text.SimpleDateFormat</code> + class. If the date and time pattern is omitted, then the default + pattern of yyyy-MM-dd is assumed. The following examples + should clarify the point. + <table class="bodyTable"> <tr class="a"> <th> @@ -919,20 +884,18 @@ <th>Example</th> </tr> <tr class="b"> - <td class="small"> + <td class="small"> /wombat/folder/foo.%d </td> - <td> - Daily rollover (at midnight). Due to the omission of the - optional time and date pattern for the %d token - specifier, the default pattern of yyyy-MM-dd is - assumed, which corresponds to daily rollover. - </td> - <td> - During November 23rd, 2006, logging output will go to - the file /wombat/foo.2006-11-23. - At midnight and for the rest of the 24th, logging - output will be directed to /wombat/foo.2006-11-24. + <td>Daily rollover (at midnight). Due to the omission of the + optional time and date pattern for the %d token + specifier, the default pattern of yyyy-MM-dd is + assumed, which corresponds to daily rollover. + </td> + <td>During November 23rd, 2006, logging output will go to the + file /wombat/foo.2006-11-23. At midnight and for the + rest of the 24th, logging output will be directed to + /wombat/foo.2006-11-24. </td> </tr> <tr class="a"> @@ -940,26 +903,25 @@ /wombat/foo.%d{yyyy-MM}.log </td> <td>Rollover at the beginning of each month.</td> - <td> - During the month of October 2006, logging output will go - to /wombat/foo.2006-10.log. - After midnight of October 31st and for the rest of - November, logging output will be directed to - /wombat/foo.2006-11.log. + <td>During the month of October 2006, logging output will go to + /wombat/foo.2006-10.log. After midnight of October + 31st and for the rest of November, logging output will be + directed to /wombat/foo.2006-11.log. </td> </tr> <tr class="b"> <td class="small"> /wombat/foo.%d{yyyy-ww}.log </td> - <td>Rollover at the first day of each week. Note that the first - day of the week depends on the locale.</td> - <td> - During the 23rd week of 2006, the file /wombat/foo.2006-23.log - will contain the actual logging output. - Logging for the 24th week of 2006 will be output to - /wombat/foo.2006-24.log - until it is rolled over at the beginning of the next week. + + <td>Rollover at the first day of each week. Note that the first + day of the week depends on the locale.</td> + + <td>During the 23rd week of 2006, the file + /wombat/foo.2006-23.log will contain the actual logging + output. Logging for the 24th week of 2006 will be output to + /wombat/foo.2006-24.log until it is rolled over at the + beginning of the next week. </td> </tr> <tr class="a"> @@ -967,11 +929,11 @@ /wombat/foo.    / %d{yyyy-MM-dd-a}.log </td> <td>Rollover at midnight and midday of each day.</td> - <td> - During the first 12 hours of November 3rd, 2006, the logging - will be output to /wombat/foo.2006-11-03-AM.log. - After noon, and until midnight, the logging will be output to - /wombat/foo.2006-11-03-PM.log. + + <td>During the first 12 hours of November 3rd, 2006, the logging + will be output to /wombat/foo.2006-11-03-AM.log. After + noon, and until midnight, the logging will be output to + /wombat/foo.2006-11-03-PM.log. </td> </tr> <tr class="b"> @@ -979,11 +941,11 @@ /wombat/foo.   / %d{yyyy-MM-dd_HH}.log </td> <td>Rollover at the top of each hour.</td> - <td> - Between 11.00,001 and 11.59,999, on November 3rd, 2006, the logging - will be output to /wombat/foo.2006-11-03_11.log. - After that, and until 12.59,999, the logging will be output to - /wombat/foo.2006-11-03_12.log. + <td>Between 11.00,001 and 11.59,999, on November 3rd, 2006, the + logging will be output to + /wombat/foo.2006-11-03_11.log. After that, and until + 12.59,999, the logging will be output to + /wombat/foo.2006-11-03_12.log. </td> </tr> <tr class="a"> @@ -991,34 +953,36 @@ /wombat/foo.    / %d{yyyy-MM-dd_HH-mm}.log </td> <td>Rollover at the beggining of every minute.</td> - <td> - Between 11.32,001 and 11.32,999, on November 3rd, 2006, the logging - will be output to /wombat/foo.2006-11-03_11-32.log. - After that, and until 12.33,999, the logging will be output to - /wombat/foo.2006-11_12-33.log. + <td>Between 11.32,001 and 11.32,999, on November 3rd, 2006, the + logging will be output to + /wombat/foo.2006-11-03_11-32.log. After that, and + until 12.33,999, the logging will be output to + /wombat/foo.2006-11_12-33.log. </td> </tr> </table> - - Any characters in the pattern outside the ranges ['a'..'z'] and ['A'..'Z'] - will be treated as quoted text. For instance, characters like '.', ' ', - '#' and '@' will appear in the resulting time text even when they are not - enclosed within single quotes. Nevertheless, we would recommend against - using the colon ":" character anywhere within the - FileNamePattern option. - The text before the colon is interpreted as the protocol specification of a - URL, which is most probably not what you intend. The slash "/" character, a - common date field separator, must also be avoided. It is taken as a file - separator causing the rollover operation to fail because the target file cannot - be created. Although less common, the backslash character "\" is equally troublesome. - - - - Just like <code>FixedWindowRollingPolicy</code>, <code>TimeBasedRollingPolicy</code> - supports automatic file compression. - This feature is enabled if the value of the FileNamePattern option - ends with .gz or .zip. + Any characters in the pattern outside the ranges + ['a'..'z'] and ['A'..'Z'] will be treated as + quoted text. For instance, characters like '.', ' + ', '#' and '@' will appear in the resulting + time text even when they are not enclosed within single + quotes. Nevertheless, we recommend against using the colon + ":" character anywhere within the FileNamePattern option. The text before the + colon is interpreted as the protocol specification of a URL, which + is most probably not what you intend. The slash "/" + character, a common date field separator, must also be avoided. It + is taken as a file separator causing the rollover operation to fail + because the target file cannot be created. Although less common, the + backslash character "\" is equally troublesome. + + + Just like <code>FixedWindowRollingPolicy</code>, + <code>TimeBasedRollingPolicy</code> supports automatic file + compression. This feature is enabled if the value of the FileNamePattern option ends with .gz + or .zip. <table class="bodyTable"> <tr class="a"> @@ -1040,59 +1004,59 @@ </tr> </table> - - As we have seen, the FileNamePattern serves two purposes. First, - by studying the pattern, logback computes the requested rollover periodicity. Second, - it computes each files' name based on the pattern. It is entirely possible for two different - file name patterns to specify the same periodicity. - The date patterns yyyy-MM and yyyy@MM both specify monthly - rollover periodicity, although the rolled files will carry different names. - - - - Given the use of the FileNamePattern, we see that the - <code>TimeBasedRollingPolicy</code> is responsible for the rollover as well as for - the triggering of said rollover. Therefore, <code>TimeBasedTriggeringPolicy</code> - implements both <code>RollingPolicy</code> and <code>TriggeringPolicy</code> - interfaces. A <code>RollingFileAppender</code> that uses - <code>TimeBasedRollingPolicy</code> can be started and used correctly even - if its configuration does not contain any reference to a <code>TriggeringPolicy</code>. - - - - With <code>TimeBasedRollingPolicy</code>, it is possible to - decouple the location of the active log file and the archived log files - - - The File option defines the log file - for the current period whereas archived files are those files - which have been rolled over in previous periods. - - - By setting the File option you can - decouple the location of the active log file and the location - of the archived log files. The actual logging will be done in the - file specified by the File option. This way, - the active file name will never change. By not setting the - File option, logback uses the - FileNamePattern to name the active file, - whose name will change each time a rollover occurs. - - - - For various efficiency reasons, rollovers are not time-driven - but depend on the arrival of logging events. For example, on 8th of March 2002, - assuming the FileNamePattern is set to - yyyy-MM-dd (daily rollover), the arrival of the first - event after midnight will trigger rollover. If there are no logging events - during, say 23 minutes and 47 seconds after midnight, - then rollover will occur at 00:23'47 AM on March 9th and not at 0:00 AM. - Thus, depending on the arrival rate of events, rollovers might be triggered - with some latency. However, regardless of the delay, the rollover algorithm - is known to be correct, in the sense that all logging events generated - during a certain period will be output in the correct file delimiting that period. + The FileNamePattern serves a dual + purposes. First, by studying the pattern, logback computes the + requested rollover periodicity. Second, it computes each file's + name. It is entirely possible for two different patterns to specify + the same periodicity. The (date) patterns yyyy-MM and + yyyy@MM both specify monthly rollover, although the + resulting archive files will carry different names. + + + Thus, <code>TimeBasedRollingPolicy</code> caries a responsiblity + for rollover as well as for the triggering of said rollover. Put + differently, <code>TimeBasedTriggeringPolicy</code> implements both + <code>RollingPolicy</code> and <code>TriggeringPolicy</code> + interfaces. A <code>RollingFileAppender</code> owning a child + <code>TimeBasedRollingPolicy</code> can be started and used + correctly even if its does not contain a reference to a + <code>TriggeringPolicy</code>. + + + As with <code>FixedWindowRollingPolicy</code>, + <code>TimeBasedRollingPolicy</code> decouples the location of the + active log file and the archived log files. The File option defines the log file for the + current period whereas archived files are those files which + have been rolled over in previous periods. + + + By setting the File option you can + decouple the location of the active log file and the location of the + archived log files. The logging output will be targeted into the + file specified by the File option. It + follows that the name of the active log file will not change over + time. However, if you choose to omit the File option, then the active file will be + computed anew for each period based on the value of FileNamePattern. + + + For various reasons, rollovers are not clock-driven but depend on + the arrival of logging events. For example, on 8th of March 2002, + assuming the FileNamePattern is set to + yyyy-MM-dd (daily rollover), the arrival of the first event + after midnight will trigger a rollover. If there are no logging + events during, say 23 minutes and 47 seconds after midnight, then + rollover will actually occur at 00:23'47 AM on March 9th and not at + 0:00 AM. Thus, depending on the arrival rate of events, rollovers + might be triggered with some latency. However, regardless of the + delay, the rollover algorithm is known to be correct, in the sense + that all logging events generated during a certain period will be + output in the correct file delimiting that period. +  Here is a sample configuration of a <code>RollingFileAppender</code> which uses a <code>TimeBasedRollingPolicy</code> @@ -1505,14 +1469,16 @@ - One or more <code>JMSTopicSink</code> or <code>JMSQueueSink</code> applications - can register to a JMS server and consume the serialized events. - The consumer of JMS appenders generated events need not be only <code>JMSTopicSink</code> - or <code>JMSQueueSink</code> applications. Any application or MessageDrivenBean - capable of subscribing to the appropriate topic or queue and consuming serialized - logging event messages would be suitable. - Additional consumers could be quickly built based on the <code>JMSTopicSink</code> or - <code>JMSQueueSink</code> model. + One or more <code>JMSTopicSink</code> or + <code>JMSQueueSink</code> applications can register to a JMS + server and consume the serialized events. The consumer of JMS + appenders generated events need not be only + <code>JMSTopicSink</code> or <code>JMSQueueSink</code> + applications. Any application or MessageDrivenBean capable of + subscribing to the appropriate topic or queue and consuming + serialized logging event messages would be suitable. Additional + consumers could be quickly built based on the + <code>JMSTopicSink</code> or <code>JMSQueueSink</code> model.

1 0

svn commit: r1590 - in logback/trunk: logback-core/src/main/java/ch/qos/logback/core logback-examples/src/main/java/chapter4 logback-examples/src/main/java/chapter4/conf logback-site/src/site/pages/manual
by noreply.ceki＠qos.ch 12 Sep '07

12 Sep '07

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> - - 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. + 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. Example 4.1: Exiting an application without flushing (<a href="../xref/chapter4/ExitWoes1.html">logback-examples/src/main/java/chapter4/ExitWoes1.java</a>) @@ -325,31 +324,29 @@ } }</pre></div> - - 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 - exitWoes1.log - 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. + 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 + exitWoes1.log 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. - - 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. + 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. <img src="images/chapter4/fileAppenderUML.png" alt="A UML diagram showing FileAppender"/> @@ -357,15 +354,16 @@ <a name="ConsoleAppender"></a> <h3>ConsoleAppender</h3> - - 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 System.out or System.err, the former - being the default target. <code>ConsoleAppender</code> formats events with - a layout specified by the user. Both System.out and System.err - 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. + 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 System.out or + System.err, 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 System.out and System.err 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. <table class="bodyTable"> @@ -394,8 +392,8 @@ </tr> </table> - - Here is a sample configuration that uses <code>ConsoleAppender</code>. + Here is a sample configuration that uses + <code>ConsoleAppender</code>. Example 4.2: ConsoleAppender configuration (logback-examples/src/main/java/chapter4/conf/logback-Console.xml) @@ -414,29 +412,32 @@ </root> </configuration></pre></div> - - To run this example, just issue the following command, - once in the logback-examples directory: + After you have set your current path to the + logback-examples directory, you can give the above + configuration file a whirl by issuing the following command: - -<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> - - 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 File option. - If the file already exists, it is either appended to, or truncated - depending on the value of the Append 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 BufferedIO option to true - which effectively wraps the <code>OutputStreamWriter</code> with - a <code>BufferedWriter</code>. Options for <code>FileAppender</code> are summarized below. + 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 File option. If the file already exists, it + is either appended to, or truncated depending on the value of the + Append 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 BufferedIO option to true which + effectively wraps the <code>OutputStreamWriter</code> with a + <code>BufferedWriter</code>. Options for <code>FileAppender</code> + are summarized below. <table class="bodyTable"> @@ -448,9 +449,11 @@ <tr class="b"> <td>Append</td> <td><code>boolean</code></td> - <td>If true, events are appended at the end of an existing file. - Otherwise, if Append is false, any existing - file is truncated. The Append option is set to true by default.</td> + <td>If true, events are appended at the end of an existing file. + Otherwise, if Append is false, any + existing file is truncated. The Append option is set to true by + default.</td> </tr> <tr class="a"> <td>Encoding</td> @@ -460,17 +463,18 @@ <tr class="b"> <td>BufferedIO</td> <td><code>boolean</code></td> - <td> - The BufferedIO 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 BufferedIO to true automatically - sets the ImmediateFlush option to false. - The name BufferedIO is slightly misleading because - buffered IO is already supported by <code>OutputStreamWriter</code>. - Setting BufferedIO 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 BufferedIO 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 BufferedIO to true automatically sets the + ImmediateFlush option to false. The + name BufferedIO is slightly + misleading because buffered IO is already supported by + <code>OutputStreamWriter</code>. Setting BufferedIO 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>File</td> <td><code>String</code></td> - <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 c:\temp\test.log is not likely to be interpreted - properly as '\t' is an escape sequence interpreted as a single - tab character (\u0009). - Correct values can be specified as c:/temp/test.log or - alternatively as c:\\temp\\test.log. - The File 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 c:\temp\test.log is not likely to be interpreted + properly as '\t' is an escape sequence interpreted as a + single tab character (\u0009). Correct values can be + specified as c:/temp/test.log or alternatively as + c:\\temp\\test.log. The File option has no default value. </td> </tr> <tr class="a"> <td>ImmediateFlush</td> <td><code>boolean</code></td> - <td> - See <code>WriterAppender</code> options. - </td> + <td>See <code>WriterAppender</code> options.</td> </tr> </table> - - By default, <code>FileAppender</code> performs a flush operation for - each event, ensuring that events are immediately written to disk. - Setting the ImmediateFlush 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 - BufferedIO - option, that is buffering character to byte conversions, increases - performance by an additional 10% to 40% compared to only disk - I/O buffering (ImmediateFlush=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"> - logback-examples/src/main/java/chapter4/IO.java</a> - for actual source code. + By default, <code>FileAppender</code> performs a flushes each + event, ensuring that events are immediately written to disk. + Setting the ImmediateFlush 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 BufferedIO option, that is buffering character + to byte conversions, increases performance by an additional 10% to + 40% compared to only disk I/O buffering (ImmediateFlush=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"> + logback-examples/src/main/java/chapter4/IO.java</a> for + actual source code. - - Configuring <code>FileAppender</code> can be done the following way: +  + + Configuring <code>FileAppender</code> can be done the following + way: Example 4.3: FileAppender configuration (logback-examples/src/main/java/chapter4/conf/logback-fileAppender.xml) @@ -531,9 +535,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>

1 0