January 2007 - logback-dev - mailman3.qos.ch

svn commit: r1266 - logback/trunk/logback-site/src/site/xdocTemplates
by noreply.seb＠qos.ch 23 Jan '07

23 Jan '07

Author: seb Date: Tue Jan 23 12:26:26 2007 New Revision: 1266 Removed: logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml Modified: logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml Log: deleted short intro and added the demo doc to the documentation page Modified: logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml Tue Jan 23 12:26:26 2007 @@ -13,12 +13,7 @@ <p>Below is a list of logback-related documentaiton currently available.</p> - <ul> - <li> - <a href="shortIntro.html"><b>A short introduction to logback-classic</b></a> - </li> - - + <ul> <li><a href="manual/index.html"><b>The logback manual</b></a></li> <li> @@ -34,6 +29,9 @@ <li> <a href="jmxConfig.html">How to use the logback JMX Configurator</a> </li> + <li> + <a href="demo.html">A step-by-step document to experience the logback-demo webApp</a> + </li> </ul> <p>Source code related documentation:</p>

1 0

svn commit: r1265 - logback/trunk/logback-site/src/site/xdocTemplates
by noreply.seb＠qos.ch 23 Jan '07

23 Jan '07

Author: seb Date: Tue Jan 23 12:10:05 2007 New Revision: 1265 Modified: logback/trunk/logback-site/src/site/xdocTemplates/demo.xml Log: minor fixes Modified: logback/trunk/logback-site/src/site/xdocTemplates/demo.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/demo.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/demo.xml Tue Jan 23 12:10:05 2007 @@ -112,8 +112,8 @@ <div class="source"><pre><filter class="ch.qos.logback.core.filter.EvaluatorFilter"> <evaluator name="loggingTaskEval"> <expression> - logger.getName().contains("LoggingTask") && - message.contains("Howdydy-diddly-ho") && + logger.getName().contains("LoggingTask") &amp;&amp; + message.contains("Howdydy-diddly-ho") &amp;&amp; (timeStamp - event.getStartTime()) >= 20000 </expression> </evaluator> @@ -238,7 +238,9 @@ <p> SLF4J allows the use of Marker objects. For example, one could use <em>TRACE</em> markers, to enrich some -specific logging statements. On the other hand, one could want that such +specific logging statements. In our demo applications, the <em>Howdydy-diddly-ho</em> +logging statements are bound to a <em>TRACE</em> marker. +On the other hand, one could want that such marked statements be dropped and not logged anywhere. <code>TurboFilter</code> objects can do that in an elegant and flexible way. Let us uncomment the <em>TurboFilter: Marker value</em> section in the <em>logback.xml</em> file as

1 0

[continuum] BUILD SUCCESSFUL: Logback Access Module
by John Noreplai 23 Jan '07

23 Jan '07

Online report : http://localhost:8090/continuum/servlet/continuum/target/ProjectBuild.vm/vi… Build statistics: State: Ok Previous State: Failed Started at: Tue, 23 Jan 2007 12:01:03 +0100 Finished at: Tue, 23 Jan 2007 12:01:17 +0100 Total time: 14s Build Trigger: Schedule Exit code: 0 Building machine hostname: pixie Operating system : Linux(unknown) Java version : 1.5.0_08(Sun Microsystems Inc.) Changes seb Better dependency management. Several dependencies are declared with scope=compile and optional=true. When a user application depends only on lb-classic, only the classic, core and slf4j-api are packaged. Any other dependency has to be managed by the user: logback does not include any other jars by itself. /logback/trunk/logback-access/pom.xml /logback/trunk/logback-classic/pom.xml /logback/trunk/logback-core/pom.xml /logback/trunk/logback-examples/pom.xml /logback/trunk/pom.xml **************************************************************************** Output: **************************************************************************** [INFO] Scanning for projects... [INFO] ---------------------------------------------------------------------------- [INFO] Building Logback Access Module [INFO] task-segment: [clean, install] [INFO] ---------------------------------------------------------------------------- [INFO] [clean:clean] [INFO] Deleting directory /opt/continuum-1.0.3/apps/continuum/working-directory/47/target [INFO] Deleting directory /opt/continuum-1.0.3/apps/continuum/working-directory/47/target/classes [INFO] Deleting directory /opt/continuum-1.0.3/apps/continuum/working-directory/47/target/test-classes [INFO] [resources:resources] [INFO] Using default encoding to copy filtered resources. [INFO] [compiler:compile] Compiling 64 source files to /opt/continuum-1.0.3/apps/continuum/working-directory/47/target/classes [INFO] [retrotranslator:translate {execution: default}] [INFO] Transforming 80 file(s) from /opt/continuum-1.0.3/apps/continuum/working-directory/47/target/classes to /opt/continuum-1.0.3/apps/continuum/working-directory/47/target/logback-access-0.8.1-SNAPSHOT-jdk14.jar. [INFO] Transformation of 80 file(s) completed successfully. [INFO] [resources:testResources] [INFO] Using default encoding to copy filtered resources. [INFO] [compiler:testCompile] Compiling 22 source files to /opt/continuum-1.0.3/apps/continuum/working-directory/47/target/test-classes [INFO] [surefire:test] [INFO] Surefire report directory: /opt/continuum-1.0.3/apps/continuum/working-directory/47/target/surefire-reports ------------------------------------------------------- T E S T S ------------------------------------------------------- Running ch.qos.logback.access.db.DBAppenderTest [Server@7bd63e39]: [Thread[main,5,main]]: checkRunning(false) entered [Server@7bd63e39]: [Thread[main,5,main]]: checkRunning(false) exited [Server@7bd63e39]: [Thread[main,5,main]]: setDatabaseName(0,test) [Server@7bd63e39]: [Thread[main,5,main]]: checkRunning(false) entered [Server@7bd63e39]: [Thread[main,5,main]]: checkRunning(false) exited [Server@7bd63e39]: [Thread[main,5,main]]: setDatabasePath(0,mem:test;sql.enforce_strict_size=true) [Server@2c76e369]: [Thread[main,5,main]]: checkRunning(false) entered [Server@2c76e369]: [Thread[main,5,main]]: checkRunning(false) exited [Server@2c76e369]: [Thread[main,5,main]]: setDatabaseName(0,test) [Server@2c76e369]: [Thread[main,5,main]]: checkRunning(false) entered [Server@2c76e369]: [Thread[main,5,main]]: checkRunning(false) exited [Server@2c76e369]: [Thread[main,5,main]]: setDatabasePath(0,mem:test;sql.enforce_strict_size=true) [Server@37bd2664]: [Thread[main,5,main]]: checkRunning(false) entered [Server@37bd2664]: [Thread[main,5,main]]: checkRunning(false) exited [Server@37bd2664]: [Thread[main,5,main]]: setDatabaseName(0,test) [Server@37bd2664]: [Thread[main,5,main]]: checkRunning(false) entered [Server@37bd2664]: [Thread[main,5,main]]: checkRunning(false) exited [Server@37bd2664]: [Thread[main,5,main]]: setDatabasePath(0,mem:test;sql.enforce_strict_size=true) [Server@10382a9]: [Thread[main,5,main]]: checkRunning(false) entered [Server@10382a9]: [Thread[main,5,main]]: checkRunning(false) exited [Server@10382a9]: [Thread[main,5,main]]: setDatabaseName(0,test) [Server@10382a9]: [Thread[main,5,main]]: checkRunning(false) entered [Server@10382a9]: [Thread[main,5,main]]: checkRunning(false) exited [Server@10382a9]: [Thread[main,5,main]]: setDatabasePath(0,mem:test;sql.enforce_strict_size=true) Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.79 sec Running ch.qos.logback.access.jetty.JettyBasicTest 2007-01-23 12:01:14.975::INFO: Logging to STDERR via org.mortbay.log.StdErrLog 2007-01-23 12:01:15.036::INFO: jetty-6.1.1 2007-01-23 12:01:15.107::INFO: Started SelectChannelConnector @ 0.0.0.0:1234 23/01/2007:12:01:15 +0100 localhost 127.0.0.1 23/01/2007:12:01:15 +0100 localhost 127.0.0.1 Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.351 sec Running ch.qos.logback.access.filter.AccessStatsTest Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.009 sec Running ch.qos.logback.access.pattern.ConverterTest Tests run: 16, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.022 sec Running ch.qos.logback.access.filter.StatsByDayTest Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.014 sec Running ch.qos.logback.access.net.URLEvaluatorTest Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.019 sec Running ch.qos.logback.access.net.SocketAppenderTest Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.135 sec Results : Tests run: 29, Failures: 0, Errors: 0, Skipped: 0 [INFO] [jar:jar] [INFO] Building jar: /opt/continuum-1.0.3/apps/continuum/working-directory/47/target/logback-access-0.8.1-SNAPSHOT.jar [INFO] Preparing source:jar [WARNING] Removing: jar from forked lifecycle, to prevent recursive invocation. [INFO] No goals needed for project - skipping [INFO] [source:jar {execution: default}] [INFO] Building jar: /opt/continuum-1.0.3/apps/continuum/working-directory/47/target/logback-access-0.8.1-SNAPSHOT-sources.jar [INFO] [jar:jar {execution: bundle-test-jar}] [INFO] [jar:test-jar {execution: bundle-test-jar}] [INFO] Building jar: /opt/continuum-1.0.3/apps/continuum/working-directory/47/target/logback-access-0.8.1-SNAPSHOT-tests.jar [INFO] [install:install] [INFO] Installing /opt/continuum-1.0.3/apps/continuum/working-directory/47/target/logback-access-0.8.1-SNAPSHOT.jar to /root/.m2/repository/ch/qos/logback/logback-access/0.8.1-SNAPSHOT/logback-access-0.8.1-SNAPSHOT.jar [INFO] Installing /opt/continuum-1.0.3/apps/continuum/working-directory/47/target/logback-access-0.8.1-SNAPSHOT-sources.jar to /root/.m2/repository/ch/qos/logback/logback-access/0.8.1-SNAPSHOT/logback-access-0.8.1-SNAPSHOT-sources.jar [INFO] Installing /opt/continuum-1.0.3/apps/continuum/working-directory/47/target/logback-access-0.8.1-SNAPSHOT-tests.jar to /root/.m2/repository/ch/qos/logback/logback-access/0.8.1-SNAPSHOT/logback-access-0.8.1-SNAPSHOT-tests.jar [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESSFUL [INFO] ------------------------------------------------------------------------ [INFO] Total time: 13 seconds [INFO] Finished at: Tue Jan 23 12:01:17 CET 2007 [INFO] Final Memory: 19M/194M [INFO] ------------------------------------------------------------------------ ****************************************************************************

1 0

svn commit: r1264 - in logback/trunk: . logback-access logback-classic logback-core logback-examples
by noreply.seb＠qos.ch 23 Jan '07

23 Jan '07

Author: seb Date: Tue Jan 23 11:42:32 2007 New Revision: 1264 Modified: logback/trunk/logback-access/pom.xml logback/trunk/logback-classic/pom.xml logback/trunk/logback-core/pom.xml logback/trunk/logback-examples/pom.xml logback/trunk/pom.xml Log: Better dependency management. Several dependencies are declared with scope=compile and optional=true. When a user application depends only on lb-classic, only the classic, core and slf4j-api are packaged. Any other dependency has to be managed by the user: logback does not include any other jars by itself. Modified: logback/trunk/logback-access/pom.xml ============================================================================== --- logback/trunk/logback-access/pom.xml (original) +++ logback/trunk/logback-access/pom.xml Tue Jan 23 11:42:32 2007 @@ -48,24 +48,28 @@ <groupId>tomcat</groupId> <artifactId>catalina</artifactId> <scope>compile</scope> + <optional>true</optional> </dependency> <dependency> <groupId>org.mortbay.jetty</groupId> <artifactId>jetty</artifactId> <scope>compile</scope> + <optional>true</optional> </dependency> <dependency> <groupId>org.mortbay.jetty</groupId> <artifactId>servlet-api-2.5</artifactId> <scope>compile</scope> + <optional>true</optional> </dependency> <dependency> <groupId>janino</groupId> <artifactId>janino</artifactId> - <scope>provided</scope> + <scope>compile</scope> + <optional>true</optional> </dependency> <dependency> @@ -77,7 +81,8 @@ <dependency> <groupId>javax.mail</groupId> <artifactId>mail</artifactId> - <scope>provided</scope> + <scope>compile</scope> + <optional>true</optional> </dependency> </dependencies> Modified: logback/trunk/logback-classic/pom.xml ============================================================================== --- logback/trunk/logback-classic/pom.xml (original) +++ logback/trunk/logback-classic/pom.xml Tue Jan 23 11:42:32 2007 @@ -36,11 +36,13 @@ <dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-core</artifactId> + <scope>compile</scope> </dependency> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-api</artifactId> + <scope>compile</scope> </dependency> <dependency> @@ -58,12 +60,15 @@ <dependency> <groupId>javax.mail</groupId> <artifactId>mail</artifactId> - <scope>provided</scope> + <scope>compile</scope> + <optional>true</optional> </dependency> <dependency> <groupId>janino</groupId> <artifactId>janino</artifactId> + <scope>compile</scope> + <optional>true</optional> </dependency> <dependency> @@ -77,6 +82,7 @@ <groupId>javax.jms</groupId> <artifactId>jms</artifactId> <scope>compile</scope> + <optional>true</optional> </dependency> </dependencies> Modified: logback/trunk/logback-core/pom.xml ============================================================================== --- logback/trunk/logback-core/pom.xml (original) +++ logback/trunk/logback-core/pom.xml Tue Jan 23 11:42:32 2007 @@ -36,17 +36,20 @@ <dependency> <groupId>janino</groupId> <artifactId>janino</artifactId> - <scope>provided</scope> + <scope>compile</scope> + <optional>true</optional> </dependency> <dependency> <groupId>javax.mail</groupId> <artifactId>mail</artifactId> - <scope>provided</scope> + <scope>compile</scope> + <optional>true</optional> </dependency> <dependency> <groupId>javax.jms</groupId> <artifactId>jms</artifactId> <scope>compile</scope> + <optional>true</optional> </dependency> </dependencies> Modified: logback/trunk/logback-examples/pom.xml ============================================================================== --- logback/trunk/logback-examples/pom.xml (original) +++ logback/trunk/logback-examples/pom.xml Tue Jan 23 11:42:32 2007 @@ -47,6 +47,13 @@ <artifactId>logback-access</artifactId> </dependency> + <dependency> + <groupId>javax.servlet</groupId> + <artifactId>servlet-api</artifactId> + <scope>compile</scope> + <optional>true</optional> + </dependency> + </dependencies> <build> Modified: logback/trunk/pom.xml ============================================================================== --- logback/trunk/pom.xml (original) +++ logback/trunk/pom.xml Tue Jan 23 11:42:32 2007 @@ -114,7 +114,12 @@ <groupId>javax.jms</groupId> <artifactId>jms</artifactId> <version>1.1</version> - </dependency> + </dependency> + <dependency> + <groupId>javax.servlet</groupId> + <artifactId>servlet-api</artifactId> + <version>2.5</version> + </dependency> </dependencies> </dependencyManagement>

1 0

svn commit: r1263 - logback/trunk/logback-site/src/site/xdocTemplates/manual
by noreply.seb＠qos.ch 22 Jan '07

22 Jan '07

Author: seb Date: Mon Jan 22 20:20:49 2007 New Revision: 1263 Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/architecture.xml logback/trunk/logback-site/src/site/xdocTemplates/manual/introduction.xml Log: minor modifications Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/architecture.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/manual/architecture.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/architecture.xml Mon Jan 22 20:20:49 2007 @@ -63,13 +63,13 @@ systems such as log4j or JDK14 Logging. The third module called <em>access</em> integrates with Servlet containers to provide HTTP-access log functionality. The access module will be covered - in a <a href="access.html">separate document</a>. + in a <a href="../access.html">separate document</a>. </p> <p> In the reminder of this document, we will write "logback" to refer to the logback classic module. </p> - + <h2>Logger, Appenders and Layouts</h2> <p> @@ -126,7 +126,7 @@ inception. Like every logger, it can be retrieved by its name, as follows: </p> - <div class="source"><pre>Logger rootLogger = LoggerFactory.getLogger(<a href="apidocs/constant-values.html#ch.qos.logback.classic.LoggerContext.ROOT_NAME">LoggerContext.<em>ROOT_NAME</em></a>);</pre></div> + <div class="source"><pre>Logger rootLogger = LoggerFactory.getLogger(<a href="../apidocs/constant-values.html#ch.qos.logback.classic.LoggerContext.ROOT_NAME">LoggerContext.<em>ROOT_NAME</em></a>);</pre></div> <p> All other loggers are also retrieved with the class static @@ -457,7 +457,7 @@ <h3>Retrieving Loggers</h3> <p> - Calling the <code><a href="/apidocs/org/slf4j/LoggerFactory.html#getLogger(java.lang.String)">LoggerFactory.getLogger</a></code> + Calling the <code><a href="../apidocs/org/slf4j/LoggerFactory.html#getLogger(java.lang.String)">LoggerFactory.getLogger</a></code> method with the same name will always return a reference to the exact same logger object. </p> @@ -521,7 +521,7 @@ <p>More than one appender can be attached to a logger.</p> - <p> The <code><a href="apidocs/ch/qos/logback/classic/Logger.html#addAppender(ch.qos.logback.core.Appender)">addAppender</a></code> method adds an appender to a + <p> The <code><a href="../apidocs/ch/qos/logback/classic/Logger.html#addAppender(ch.qos.logback.core.Appender)">addAppender</a></code> method adds an appender to a given logger. Each enabled logging request for a given logger will be forwarded to all the appenders in that logger as well as the appenders higher in the hierarchy. In other words, appenders are @@ -769,8 +769,18 @@ code. Given their number, it becomes imperative to manage these log statements without the need to modify them manually. </p> - - <p>The logback environment is fully configurable programmatically. + + <div class="highlight"> + <p> + In order to run the examples in this introduction, you need + to make sure that certain jar files are present on the + classpath. + Please refer to the <a href="../setup.html">setup page</a> + for further details. + </p> + </div> + + <p>The logback environment is fully configurable programmatically. However, it is far more flexible to configure logback using configuration files. In logback, configuration files are written in XML format. @@ -788,8 +798,8 @@ file, as the following example demonstrate. </p> - <em>Example 1.4: Logback configuration from file ((<a - href="xref/chapter2/MyAppWithConfigFile.html">logback-examples/src/main/java/chapter2/MyAppWithConfigFile.java</a>)</em> + <em>Example 2.1: Logback configuration from file (<a + href="../xref/chapter2/MyAppWithConfigFile.html">logback-examples/src/main/java/chapter2/MyAppWithConfigFile.java</a>)</em> <div class="source"><pre>package chapter2; @@ -826,7 +836,7 @@ object. The <code>Bar</code> class is listed below: </p> - <em>Example 1.3: Sample logging class (<a href="xref/chapter2/Bar.html">logback-examples/src/main/java/chapter2/Bar.java</a>)</em> + <em>Example 2.2: Sample logging class (<a href="../xref/chapter2/Bar.html">logback-examples/src/main/java/chapter2/Bar.java</a>)</em> <div class="source"><pre>package chapter2; import org.slf4j.Logger; @@ -866,7 +876,7 @@ <p>Let us configure logback with the next XML configuration file:</p> - <em>Example 1.5: Basic configuration with a xml file (logback-examples/src/main/java/chapter2/sample-config-1.xml)</em> + <em>Example 2.3: Basic configuration with a xml file (logback-examples/src/main/java/chapter2/sample-config-1.xml)</em> <div class="source"><pre><?xml version="1.0" encoding="UTF-8" ?> <configuration> @@ -911,7 +921,7 @@ configure logback so that it logs on the console, but also to a custom file.</p> -<em>Example 1.6: Configuring logback with multiple appenders (logback-examples/src/main/java/chapter2/sample-config-2.xml)</em> +<em>Example 2.4: Configuring logback with multiple appenders (logback-examples/src/main/java/chapter2/sample-config-2.xml)</em> <div class="source"><pre><?xml version="1.0" encoding="UTF-8" ?> <configuration> @@ -951,7 +961,7 @@ bold xml snippet to the configuration file, right before the <code><root></code> element.</p> -<em>Example 1.7: Configuring a specific logger (logback-examples/src/main/java/chapter2/sample-config-3.xml)</em> +<em>Example 2.5: Configuring a specific logger (logback-examples/src/main/java/chapter2/sample-config-3.xml)</em> <div class="source"><pre><?xml version="1.0" encoding="UTF-8" ?> <configuration> Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/introduction.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/manual/introduction.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/introduction.xml Mon Jan 22 20:20:49 2007 @@ -72,7 +72,7 @@ In order to run the examples in this introduction, you need to make sure that certain jar files are present on the classpath. - Please refer to the <a href="setup.html">setup page</a> + Please refer to the <a href="../setup.html">setup page</a> for further details. </p> </div>

1 0

svn commit: r1262 - in logback/trunk: logback-examples/src/main/java/chapter1 logback-examples/src/main/java/chapter2 logback-site/src/site/xdocTemplates/manual
by noreply.seb＠qos.ch 22 Jan '07

22 Jan '07

Author: seb Date: Mon Jan 22 16:58:04 2007 New Revision: 1262 Added: logback/trunk/logback-examples/src/main/java/chapter2/ logback/trunk/logback-examples/src/main/java/chapter2/Bar.java logback/trunk/logback-examples/src/main/java/chapter2/HelloWorld2.java logback/trunk/logback-examples/src/main/java/chapter2/MyAppWithConfigFile.java logback/trunk/logback-examples/src/main/java/chapter2/sample-config-1.xml logback/trunk/logback-examples/src/main/java/chapter2/sample-config-2.xml logback/trunk/logback-examples/src/main/java/chapter2/sample-config-3.xml logback/trunk/logback-site/src/site/xdocTemplates/manual/architecture.xml logback/trunk/logback-site/src/site/xdocTemplates/manual/introduction.xml Removed: logback/trunk/logback-examples/src/main/java/chapter1/Bar.java logback/trunk/logback-examples/src/main/java/chapter1/MyApp.java logback/trunk/logback-examples/src/main/java/chapter1/MyAppWithConfigFile.java logback/trunk/logback-examples/src/main/java/chapter1/sample-config-1.xml logback/trunk/logback-examples/src/main/java/chapter1/sample-config-2.xml logback/trunk/logback-examples/src/main/java/chapter1/sample-config-3.xml Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/index.xml Log: Split of the short intro into a chapter1: introduction and chapter2: architecture. Moved examples accordingly Added: logback/trunk/logback-examples/src/main/java/chapter2/Bar.java ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter2/Bar.java Mon Jan 22 16:58:04 2007 @@ -0,0 +1,21 @@ +/** + * Logback: the generic, reliable, fast and flexible logging framework. + * + * 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. + */ +package chapter2; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +class Bar { + Logger logger = LoggerFactory.getLogger(Bar.class); + + public void doIt() { + logger.debug("doing my job"); + } +} \ No newline at end of file Added: logback/trunk/logback-examples/src/main/java/chapter2/HelloWorld2.java ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter2/HelloWorld2.java Mon Jan 22 16:58:04 2007 @@ -0,0 +1,24 @@ +/** + * Logback: the generic, reliable, fast and flexible logging framework. + * + * 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. + */ +package chapter2; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +import ch.qos.logback.classic.util.LoggerStatusPrinter; + +public class HelloWorld2 { + + public static void main(String[] args) { + Logger logger = LoggerFactory.getLogger("chapter2.HelloWorld2"); + logger.debug("Hello world."); + LoggerStatusPrinter.printStatusInDefaultContext(); + } +} Added: logback/trunk/logback-examples/src/main/java/chapter2/MyAppWithConfigFile.java ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter2/MyAppWithConfigFile.java Mon Jan 22 16:58:04 2007 @@ -0,0 +1,41 @@ +/** + * Logback: the generic, reliable, fast and flexible logging framework. + * + * 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. + */ +package chapter2; + +//Import SLF4J classes. +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +import ch.qos.logback.classic.LoggerContext; +import ch.qos.logback.classic.joran.JoranConfigurator; +import ch.qos.logback.core.joran.spi.JoranException; +import ch.qos.logback.core.util.StatusPrinter; + +public class MyAppWithConfigFile { + + public static void main(String[] args) { + Logger logger = LoggerFactory.getLogger(MyAppWithConfigFile.class); + LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); + + try { + JoranConfigurator configurator = new JoranConfigurator(); + lc.shutdownAndReset(); + configurator.setContext(lc); + configurator.doConfigure(args[0]); + } catch (JoranException je) { + StatusPrinter.print(lc.getStatusManager()); + } + logger.info("Entering application."); + Bar bar = new Bar(); + bar.doIt(); + logger.info("Exiting application."); + + } +} Added: logback/trunk/logback-examples/src/main/java/chapter2/sample-config-1.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter2/sample-config-1.xml Mon Jan 22 16:58:04 2007 @@ -0,0 +1,16 @@ +<?xml version="1.0" encoding="UTF-8" ?> + +<configuration> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration> Added: logback/trunk/logback-examples/src/main/java/chapter2/sample-config-2.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter2/sample-config-2.xml Mon Jan 22 16:58:04 2007 @@ -0,0 +1,25 @@ +<?xml version="1.0" encoding="UTF-8" ?> + +<configuration> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern>%-4relative [%thread] %-5level %class - %msg%n</pattern> + </layout> + </appender> + + <appender name="FILE" + class="ch.qos.logback.core.FileAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern>%-4relative [%thread] %-5level %class - %msg%n</pattern> + </layout> + <File>sample-log.txt</File> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + <appender-ref ref="FILE" /> + </root> +</configuration> Added: logback/trunk/logback-examples/src/main/java/chapter2/sample-config-3.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter2/sample-config-3.xml Mon Jan 22 16:58:04 2007 @@ -0,0 +1,29 @@ +<?xml version="1.0" encoding="UTF-8" ?> + +<configuration> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern>%-4relative [%thread] %-5level %class - %msg%n</pattern> + </layout> + </appender> + + <appender name="FILE" + class="ch.qos.logback.core.FileAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern>%-4relative [%thread] %-5level %class - %msg%n</pattern> + </layout> + <File>sample-log.txt</File> + </appender> + + <logger name="chapter2"> + <level value="info" /> + </logger> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + <appender-ref ref="FILE" /> + </root> +</configuration> Added: logback/trunk/logback-site/src/site/xdocTemplates/manual/architecture.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/architecture.xml Mon Jan 22 16:58:04 2007 @@ -0,0 +1,1037 @@ +<document> +  + + + <body> + <h2>Chapter 2: Architecture</h2> + <div class="author"> + Authors: Ceki Gülcü, Sébastien Pennec + </div> + + + <table> + <tr> + <td valign="top" align="top"> + <a rel="license" + href="http://creativecommons.org/licenses/by-nc-sa/2.5/"> + <img alt="Creative Commons License" + style="border-width: 0" + src="http://creativecommons.org/images/public/somerights20.png" /> + </a> + </td> + <td> + <p>Copyright © 2000-2006, QOS.ch</p> + + <p> +  + This work is licensed under a + <a rel="license" + href="http://creativecommons.org/licenses/by-nc-sa/2.5/"> + Creative Commons + Attribution-NonCommercial-ShareAlike 2.5 + License + </a> + . +  + </p> + </td> + </tr> + </table> + + + <h2>Logback architecture</h2> + + <p> + Logback's basic architecture is sufficiently generic so as to + apply under different circumstances. At present time, logback is + divided into three modules, Core, Classic and Access. + </p> + + <p> + The <em>core</em> module lays the groundwork for the other two + modules. The <em>classic</em> module extends <em>core</em>. The + classic module corresponds to a significantly improved + version of log4j. Logback-classic natively implements the <a + href="http://www.slf4j.org">SLF4J API</a> so that you can + readily switch back and forth between logback and other logging + systems such as log4j or JDK14 Logging. The third module called + <em>access</em> integrates with Servlet containers to provide + HTTP-access log functionality. The access module will be covered + in a <a href="access.html">separate document</a>. + </p> + <p> + In the reminder of this document, we will write "logback" to refer to the + logback classic module. + </p> + + <h2>Logger, Appenders and Layouts</h2> + + <p> + Logback has three main types: <code>Logger</code>, + <code>Appender</code> and <code>Layout</code>. These three types of components work + together to enable developers to log messages according to + message type and level, and to control at runtime how these + messages are formatted and where they are reported. + </p> + <p> + The Logger class is part of the classic module. On the other + hand, the <code>Appender</code> and <code>Layout</code> interfaces + are part of the core module. For the sake of genericity, + logback-core has no notion of loggers. + </p> + + <h3>Logger context</h3> + + <p>The first and foremost advantage of any logging API over plain + <code>System.out.println</code> resides in its ability to disable + certain log statements while allowing others to print + unhindered. This capability assumes that the logging space, that + is, the space of all possible logging statements, is categorized + according to some developer-chosen criteria. In logback, this + categorization is an inherent part of loggers. + </p> + + <p> + Loggers are named entities. Their names are case-sensitive and + they follow the hierarchical naming rule: + </p> + <div class="definition"> + <div class="deftitle">Named Hierarchy</div> + <p> + A logger is said to be an ancestor of another logger if + its name followed by a dot is a prefix of the descendant + logger name. A logger is said to be a parent of a child + logger if there are no ancestors between itself and the + descendant logger. + </p> + </div> + + <p> + For example, the logger named <code>"com.foo"</code> + is a parent of the logger named <code>"com.foo.Bar"</code>. + Similarly, <code>"java"</code> + is a parent of <code>"java.util"</code> and an ancestor of + <code>"java.util.Vector"</code>. + This naming scheme should be familiar to most developers. + </p> + <p> + The root logger resides at the top of the logger hierarchy. It + is exceptional in that it is part of every hierarchy at its + inception. Like every logger, it can be retrieved by its name, + as follows: + </p> + <div class="source"><pre>Logger rootLogger = LoggerFactory.getLogger(<a href="apidocs/constant-values.html#ch.qos.logback.classic.LoggerContext.ROOT_NAME">LoggerContext.<em>ROOT_NAME</em></a>);</pre></div> + + <p> + All other loggers are also retrieved with the class static + <code>getLogger</code> method found in the <a + href="http://www.slf4j.org/api/org/slf4j/Logger.html">org.slf4j.LoggerFactory</a> + class. This method takes the name of the desired logger as a + parameter. Some of the basic methods in the <code>Logger</code> + interface are listed below. + </p> + + <div class="source"><pre>package org.slf4j; +public interface Logger { + + // Printing methods: + public void debug(String message); + public void info(String message); + public void warn(String message); + public void error(String message); + public void fatal(String message); +}</pre></div> + + <p> + Loggers may be assigned levels. The set of possible levels, that + is DEBUG, INFO, WARN and ERROR are defined in the + <code>ch.qos.logback.classic.Level</code> class. Note that in + logback, the level class is final and cannot be derived, as a + much more flexible approach exist in the form of Marker objects. + </p> + + <p> + If a given logger is not assigned a level, then it inherits + one from its closest ancestor with an assigned level. More + formally: + </p> + + <div class="definition"> + <div class="deftitle">Level Inheritance</div> + <p> + The effective level for a given logger <em>L</em>, is equal to + the first non-null level in its hierarchy, starting at + <em>L</em> itself and proceeding upwards in the hierarchy + towards the root logger. + </p> + </div> + + <p> + To ensure that all loggers can eventually inherit a level, the + root logger always has an assigned level. By default, this level + is DEBUG. + </p> + <p> + Below are four examples with various assigned level values and + the resulting effective (inherited) levels according to the + level inheritance rule. + </p> + + <em>Example 1</em> + <table> + <tr> + <th> + Logger name + </th> + <th> + Assigned level + </th> + + <th> + Effective level + </th> + </tr> + <tr> + <td>root</td> + <td>DEBUG</td> + <td>DEBUG</td> + </tr> + <tr> + <td>X</td> + <td>none</td> + <td>DEBUG</td> + </tr> + + <tr> + <td>X.Y</td> + <td>none</td> + <td>DEBUG</td> + </tr> + <tr> + <td>X.Y.Z</td> + <td>none</td> + <td>DEBUG</td> + </tr> + </table> + + <p> In example 1 above, only the root logger is assigned a level. + This level value, <code>DEBUG</code>, is inherited by the other + loggers <code>X</code>, <code>X.Y</code> and <code>X.Y.Z</code> + </p> + + <em>Example 2</em> + <table> + <tr> + <th> + Logger name + </th> + <th> + Assigned level + </th> + + <th> + Effective level + </th> + </tr> + <tr align="left"> + <td>root</td> + <td>ERROR</td> + <td>ERROR</td> + </tr> + <tr align="left"> + <td>X</td> + <td>INFO</td> + <td>INFO</td> + </tr> + + <tr align="left"> + <td>X.Y</td> + <td>DEBUG</td> + <td>DEBUG</td> + </tr> + <tr align="left"> + <td>X.Y.Z</td> + <td>WARN</td> + <td>WARN</td> + </tr> + </table> + + <p>In example 2 above, all loggers have an assigned level value. + Level inheritence does not come into play. + </p> + + <em>Example 3</em> + <table> + <tr> + <th> + Logger name + </th> + <th> + Assigned level + </th> + <th> + Effective level + </th> + </tr> + <tr align="left"> + <td>root</td> + <td>DEBUG</td> + <td>DEBUG</td> + </tr> + + <tr align="left"> + <td>X</td> + <td>INFO</td> + <td>INFO</td> + </tr> + <tr align="left"> + <td>X.Y</td> + <td>none</td> + <td>INFO</td> + </tr> + <tr align="left"> + <td>X.Y.Z</td> + <td>ERROR</td> + <td>ERROR</td> + </tr> + </table> + <p> + In example 3 above, the loggers <code>root</code>, <code>X</code> + and <code>X.Y.Z</code> are assigned the levels <code>DEBUG</code>, + <code>INFO</code> and <code>ERROR</code> + respectively. Logger <code>X.Y</code> + inherits its level value from its parent <code>X</code>. + </p> + <em>Example 4</em> + <table> + + <tr> + <th> + Logger name + </th> + <th> + Assigned level + </th> + <th> + Effective level + </th> + </tr> + <tr align="left"> + <td>root</td> + <td>DEBUG</td> + <td>DEBUG</td> + </tr> + + <tr align="left"> + <td>X</td> + <td>INFO</td> + <td>INFO</td> + </tr> + <tr align="left"> + <td>X.Y</td> + <td>none</td> + <td>INFO</td> + </tr> + <tr align="left"> + <td>X.Y.Z</td> + <td>none</td> + <td>INFO</td> + </tr> + </table> + + + <p>In example 4 above, the loggers <code>root</code> and + <code>X</code> and are assigned the levels <code>DEBUG</code> and + <code>INFO</code> respectively. The loggers <code>X.Y</code> and + <code>X.Y.Z</code> inherit their level value from their nearest + parent <code>X</code>, which has an assigned level. + </p> + + <h3>Printing methods</h3> + + <p>By definition, the printing method determines the level of a + logging request. For example, if <code>L</code> is a logger + instance, then the statement <code>L.info("..")</code> is a + logging statement of level INFO. + </p> + + <p>A logging request is said to be <em>enabled</em> if its level + is higher than or equal to the level of its logger. Otherwise, the + request is said to be <em>disabled</em>. A logger without an + assigned level will inherit one from the context. This rule is + summarized below. + </p> + + <div class="definition"> + <div class="deftitle">Basic Selection Rule</div> + + <p>A log request of level <em>p</em> in a logger with an + effective level <em>q</em>, is enabled if <em>p >= q</em>. + </p> + </div> + + <p> + This rule is at the heart of logback. It assumes + that levels are ordered as follows: + <code>DEBUG < INFO < WARN < ERROR< OFF</code>. + </p> + + <p>In a more graphic way, here is how the selection rule works. In + the following table, the vertical header shows the the level of + the logging request, designated by <em>p</em>, while the + horizontal header shows effective level of the logger, designated + by <em>q</em>. + </p> + + <table> + <tr> + <th><span style="align:center"><em>p</em>/<em>q</em></span></th> + <th>DEBUG</th> + <th>INFO</th> + <th>WARN</th> + <th>ERROR</th> + <th>OFF</th> + </tr> + <tr> + <th>DEBUG</th> + <td><span class="greenBold">YES</span></td> + <td><span class="redBold">NO</span></td> + <td><span class="redBold">NO</span></td> + <td><span class="redBold">NO</span></td> + <td><span class="redBold">NO</span></td> + </tr> + <tr> + <th>INFO</th> + <td><span class="greenBold">YES</span></td> + <td><span class="greenBold">YES</span></td> + <td><span class="redBold">NO</span></td> + <td><span class="redBold">NO</span></td> + <td><span class="redBold">NO</span></td> + </tr> + <tr> + <th>WARN</th> + <td><span class="greenBold">YES</span></td> + <td><span class="greenBold">YES</span></td> + <td><span class="greenBold">YES</span></td> + <td><span class="redBold">NO</span></td> + <td><span class="redBold">NO</span></td> + </tr> + <tr> + <th>ERROR</th> + <td><span class="greenBold">YES</span></td> + <td><span class="greenBold">YES</span></td> + <td><span class="greenBold">YES</span></td> + <td><span class="greenBold">YES</span></td> + <td><span class="redBold">NO</span></td> + </tr> + </table> + + <p>Here is an example of the basic selection rule.</p> + + <div class="source"><pre>// get a logger instance named "com.foo", with an <span class="blue">INFO</span> level. +Logger logger = LoggerFactory.getLogger("com.foo"); +//set its Level to <span class="blue">INFO</span> +logger.setLevel(Level. <span class="blue">INFO</span>); +Logger barlogger = LoggerFactory.getLogger("com.foo.Bar"); + +// This request is enabled, because <span class="green bold">WARN</span> >= <span class="blue">INFO</span> +logger.<span class="green bold">warn</span>("Low fuel level."); + +// This request is disabled, because <span class="green bold">DEBUG</span> < <span class="blue">INFO</span>. +logger.<span class="green bold">debug</span>("Starting search for nearest gas station."); + +// The logger instance barlogger, named "com.foo.Bar", +// will inherit its level from the logger named +// "com.foo" Thus, the following request is enabled +// because <span class="green bold">INFO</span> >= <span class="blue">INFO</span>. +barlogger.<span class="green bold">info</span>("Located nearest gas station."); + +// This request is disabled, because <span class="green bold">DEBUG</span> < <span class="blue">INFO</span>. +barlogger.<span class="green bold">debug</span>("Exiting gas station search");</pre></div> + + <h3>Retrieving Loggers</h3> + <p> + Calling the <code><a href="/apidocs/org/slf4j/LoggerFactory.html#getLogger(java.lang.String)">LoggerFactory.getLogger</a></code> + method with the same name will always return a reference to + the exact same logger object. + </p> + + <p>For example, in</p> + <div class="source"><pre>Logger x = LoggerFactory.getLogger("wombat"); +Logger y = LoggerFactory.getLogger("wombat");</pre></div> + + <p> + <code>x</code> and <code>y</code> refer to + <em>exactly</em> the same logger object. + </p> + + <p> + Thus, it is possible to configure a logger and then to + retrieve the same instance somewhere else in the code + without passing around references. In fundamental + contradiction to biological parenthood, where parents always + preceed their children, logback loggers can be + created and configured in any order. In particular, a + "parent" logger will find and link to its descendants even + if it is instantiated after them. + </p> + <p> + Configuration of the logback environment is typically done + at application initialization. The preferred way is by + reading a configuration file. This approach will be + discussed shortly. + </p> + <p> + Logback makes it easy to name loggers by <em>software + component</em>. This can be accomplished by instantiating a + logger in each class, with the logger name equal to the fully + qualified name of the class. This is a useful and + straightforward method of defining loggers. As the log output + bears the name of the generating logger, this naming strategy + makes it easy to identify the origin of a log message. However, + this is only one possible, albeit common, strategy for naming + loggers. Logback does not restrict the possible set of + loggers. As a developer, you are free to name loggers as you + wish. + </p> + + <p>Nevertheless, naming loggers after the class where they are + located seems to be the best general strategy known so far. + </p> + + <h3>Appenders and Layouts</h3> + + <p> + The ability to selectively enable or disable logging requests + based on their logger is only part of the picture. Logback + allows logging requests to print to multiple destinations. In + logback speak, an output destination is called an + appender. Currently, appenders exist for the console, files, + remote socket servers, to MySQL, PostgreSQL, Oracle and other + databases, JMS, and remote UNIX Syslog daemons. + +  + </p> + + <p>More than one appender can be attached to a logger.</p> + + <p> The <code><a href="apidocs/ch/qos/logback/classic/Logger.html#addAppender(ch.qos.logback.core.Appender)">addAppender</a></code> method adds an appender to a + given logger. Each enabled logging request for a given logger + will be forwarded to all the appenders in that logger as well as + the appenders higher in the hierarchy. In other words, appenders are + inherited additively from the logger hierarchy. For example, if a + console appender is added to the root logger, then all enabled + logging requests will at least print on the console. If in + addition a file appender is added to a logger, say <em>L</em>, + then enabled logging requests for <em>L</em> and <em>L</em>'s + children will print on a file <em>and</em> on the console. It is + possible to override this default behavior so that appender + accumulation is no longer additive by setting the additivity flag + of a logger to false. + </p> + + <p> + The rules governing appender additivity are summarized + below. + </p> + <div class="definition"> + + <div class="deftitle">Appender Additivity</div> + + <p> + The output of a log statement of logger <em>L</em> + will go to all the appenders in <em>L</em> + and its ancestors. This is the meaning of the term + "appender additivity". + </p> + + <p> + However, if an ancestor of logger <em>L</em>, say + <em>P</em>, has the additivity flag set to false, then + <em>L</em>'s output will be directed to all the appenders in + <em>L</em> and it's ancestors upto and including + <em>P</em> but not the appenders in any of the ancestors of + <em>P</em>. + </p> + + <p> + Loggers have their additivity flag set to true by + default. + </p> + + </div> + The table below shows an example: + + <table class="bodyTable"> + <tr> + <th>Logger Name</th> + <th>Attached Appenders</th> + <th>Additivity Flag</th> + <th>Output Targets</th> + <th>Comment</th> + </tr> + <tr> + <td>root</td> + <td>A1</td> + <td>not applicable</td> + <td>A1</td> + + <td>Since the root logger stands at the top of the logger + hiearchy, the additivity flag does not apply to it. + </td> + </tr> + <tr> + <td>x</td> + <td>A-x1, A-x2</td> + <td>true</td> + <td>A1, A-x1, A-x2</td> + <td>Appenders of "x" and of root.</td> + </tr> + <tr> + <td>x.y</td> + <td>none</td> + <td>true</td> + <td>A1, A-x1, A-x2</td> + <td>Appenders of "x" and of root.</td> + </tr> + <tr> + <td>x.y.z</td> + <td>A-xyz1</td> + <td>true</td> + <td>A1, A-x1, A-x2, A-xyz1</td> + <td>Appenders of "x.y.z", "x" and of root.</td> + </tr> + <tr> + <td>security</td> + <td>A-sec</td> + <td class="blue"><span class="blue">false</span></td> + <td>A-sec</td> + + <td> + No appender accumulation since the additivity flag is set to + <code>false</code>. Only appender A-sec will be used. + </td> + </tr> + <tr> + <td>security.access</td> + <td>none</td> + <td>true</td> + <td>A-sec</td> + <td> + Only appenders of "security" because the additivity + flag in "security" is set to + <code>false</code>. + </td> + </tr> + </table> + + + <p> + More often than not, users wish to customize not only the + output destination but also the output format. This is + accomplished by associating a <em>layout</em> + with an appender. The layout is responsible for formatting + the logging request according to the user's wishes, whereas + an appender takes care of sending the formatted output to + its destination. The <code>PatternLayout</code>, part of the standard + logback distribution, lets the user specify the output + format according to conversion patterns similar to the C + language <code>printf</code> + function. + </p> + + <p> + For example, the PatternLayout with the conversion pattern + "%-4relative [%thread] %-5level %logger{32} - %msg%n" will output something akin to: + </p> + + <div class="source"><pre>176 [main] DEBUG chapter2.HelloWorld2 - Hello world.</pre></div> + + <p> + The first field is the number of milliseconds elapsed since + the start of the program. The second field is the thread + making the log request. The third field is the level of the + log request. The fourth field is the name of the logger + associated with the log request. The text after the '-' is + the message of the request. + </p> + + <h3>Parameterized logging</h3> + + <p> + Given that loggers in logback-classic implement the <a + href="http://www.slf4j.org/api/org/slf4j/Logger.html">SLF4J's + Logger interface</a>, certain printing methods admit more than + one parameter. These printing method variants are mainly + intended to improve performance while minimizing the impact on + the readability of the code. + </p> + + <p> + For some Logger <code>logger</code>, writing, + </p> + + <div class="source"><pre>logger.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));</pre></div> + + <p> + incurs the cost of constructing the message parameter, that + is converting both integer <code>i</code> and <code>entry[i]</code> + to a String, and concatenating intermediate strings. This, + regardless of whether the message will be logged or not. + </p> + + <p> + One possible way to avoid the cost of parameter construction + is by surrounding the log statement with a test. Here is an + example. + </p> + + <div class="source"><pre>if(logger.isDebugEnabled()) { + logger.debug("Entry number: " + i + " is " + String.valueOf(entry[i])); +}</pre></div> + + + <p> + This way you will not incur the cost of parameter + construction if debugging is disabled for <code>logger</code>. + On the other hand, if the logger is enabled for the DEBUG + level, you will incur the cost of evaluating whether the + logger is enabled or not, twice: once in <code>debugEnabled</code> + and once in <code>debug</code>. + This is an insignificant overhead because evaluating a + logger takes less than 1% of the time it takes to actually + log a request. + </p> + + + + <h4>Better alternative</h4> + + <p> + There exists a convenient alternative based on message + formats. Assuming <code>entry</code> is an object, you can write: + </p> + + + <div class="source"><pre>Object entry = new SomeObject(); +logger.debug("The entry is {}.", entry);</pre></div> + + <p> + After evaluting whether to log or not, and only if the decision + is positive, will the logger implementation format the message + and replace the '{}' pair with the string value of + <code>entry</code>. In other words, this form does not incur + the cost of parameter construction in case the log statement is + disabled. + </p> + + + <p> + The following two lines will yield the exact same output. + However, in case of a <em>disabled</em> + logging statement, the second variant will outperform the first variant by a + factor of at least 30. + </p> + + <div class="source"><pre>logger.debug("The new entry is "+entry+"."); +logger.debug("The new entry is {}.", entry);</pre></div> + + + <p> + A two argument variant is also availalble. For example, you + can write: + </p> + + <div class="source"><pre>logger.debug("The new entry is {}. It replaces {}.", entry, oldEntry);</pre></div> + + <p>If three or more arguments need to be passed, an + <code>Object[]</code> variant is also availalble. For example, you + can write: + </p> + + + <div class="source"><pre>Object[] paramArray = {newVal, below, above}; +logger.debug("Value {} was inserted between {} and {}.", paramArray);</pre></div> + + <h3>Configuration</h3> + + <p>Inserting log requests into the application code requires a + fair amount of planning and effort. Observation shows that + approximately four percent of code is dedicated to + logging. Consequently, even moderately sized applications will + contain thousands of logging statements embedded within its + code. Given their number, it becomes imperative to manage these + log statements without the need to modify them manually. + </p> + + <p>The logback environment is fully configurable programmatically. + However, it is far more flexible to configure logback using + configuration files. In logback, configuration files are written + in XML format. + </p> + + <p>Existing log4j users can convert their + <em>log4j.properties</em> files to <em>logback.xml</em> using our <a + href="http://logback.qos.ch/translator/">PropertiesTranslator</a> + web-application. + </p> + + <p> + Configuring logback from a XML file is an easy task. One just needs to + instanciate a <code>JoranConfigurator</code> and pass the configuration + file, as the following example demonstrate. + </p> + + <em>Example 1.4: Logback configuration from file ((<a + href="xref/chapter2/MyAppWithConfigFile.html">logback-examples/src/main/java/chapter2/MyAppWithConfigFile.java</a>)</em> + +<div class="source"><pre>package chapter2; + +//Import SLF4J classes. +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +import ch.qos.logback.classic.LoggerContext; +import ch.qos.logback.classic.joran.JoranConfigurator; +import ch.qos.logback.core.util.StatusPrinter; + +public class MyAppWithConfigFile { + + public static void main(String[] args) { + Logger logger = LoggerFactory.getLogger(MyAppWithConfigFile.class); + LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); + + JoranConfigurator configurator = new JoranConfigurator(); + configurator.setContext(lc); + configurator.doConfigure(args[0]); + + logger.info("Entering application."); + Bar bar = new Bar(); + bar.doIt(); + logger.info("Exiting application."); + + StatusPrinter.print(lc.getStatusManager()); + } +}</pre></div> + + + <p>This class defines a logger instance variable. + It then instantiates a <code>Bar</code> + object. The <code>Bar</code> class is listed below: + </p> + + <em>Example 1.3: Sample logging class (<a href="xref/chapter2/Bar.html">logback-examples/src/main/java/chapter2/Bar.java</a>)</em> +<div class="source"><pre>package chapter2; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +class Bar { + + Logger logger = LoggerFactory.getLogger(Bar.class); + + public void doIt() { + logger.debug("doing my job"); + } +}</pre></div> + + <p><em>MyAppWithConfigFile</em> configures logback by using the + <code>JoranConfigurator</code>. Joran is a XML interpreter, similar to the + commons-digester API, but offering several advantages over + commons-digester. Here, it parses the xml file and runs actions + depending on the tags it finds. To setup the <code>JoranConfigurator</code> + properly, we passed the <code>LoggerContext</code>. A + <code>LoggerContext</code> is the class that creates and manages + Loggers in logback. It is also the class that implements the + <code>org.slf4j.ILoggerFactory</code> interface. + </p> + <p> + All + other classes only need to retrieve an instance of + <code>org.slf4j.Logger</code> by calling + <code>LoggerFactory.getLogger()</code>, and then log away. For + example, the only dependence of the <code>Bar</code> class is on + <code>org.slf4j.Logger</code> and + <code>org.slf4j.LoggerFactory</code>. Except code that configures + logback (if such code exists) user code does not need to depend on + logback, but on SLF4J instead. + </p> + + <p>Let us configure logback with the + next XML configuration file:</p> + + <em>Example 1.5: Basic configuration with a xml file (logback-examples/src/main/java/chapter2/sample-config-1.xml)</em> +<div class="source"><pre><?xml version="1.0" encoding="UTF-8" ?> + +<configuration> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> + + <p>We first created an <code>Appender</code>, named <em>STDOUT</em> + that is of <code>ConsoleAppender</code> type. Its layout is managed + by a <code>PatternLayout</code>, that uses the value of the <em>pattern</em> parameter + to generate the logging statement. We then configured the root + logger, set its level to DEBUG, and linked the newly configured + <code>ConsoleAppender</code> to the root logger.</p> + + <p>Note that we've set the root logger level explicitly. Since root + logger have a DEBUG level by default we could have omitted this.</p> + + <p>To run this example, use this command:</p> + +<div class="source"><pre>java chapter2.MyAppWithConfigFile src/main/java/chapter2/sample-config-1.xml</pre></div> + + <p> + Here is what you should see in the console: + </p> + +<div class="source"><pre>18:15:26.718 [main] INFO chapter2.MyAppWithConfigFile - Entering application. +18:15:26.718 [main] DEBUG chapter2.Bar - doing my job +18:15:26.718 [main] INFO chapter2.MyAppWithConfigFile - Exiting application.</pre></div> + + + <p>Logging to the console is a rather simple example. Let's now + configure logback so that it logs on the console, but also to a + custom file.</p> + +<em>Example 1.6: Configuring logback with multiple appenders (logback-examples/src/main/java/chapter2/sample-config-2.xml)</em> +<div class="source"><pre><?xml version="1.0" encoding="UTF-8" ?> + +<configuration> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern>%-4relative [%thread] %-5level %class - %msg%n</pattern> + </layout> + </appender> + + <appender name="FILE" + class="ch.qos.logback.core.FileAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern>%-4relative [%thread] %-5level %class - %msg%n</pattern> + </layout> + <File>sample-log.txt</File> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + <appender-ref ref="FILE" /> + </root> +</configuration></pre></div> + + <p>Now, all the logging statements are directed to the console and + to a file named <em>sample-log.txt</em>. As you can see, the + configuration needed to add an Appender is rather small. The options + are declared as xml element, in either Appender configuration. They are + read and their value are assigned to the corresponding attribute in + the specified java class. + </p> + + <p>Suppose that we do not want to see the DEBUG level statements in + the chapter2 package anymore. This is done by adding the following + bold xml snippet to the configuration file, right before the + <code><root></code> element.</p> + +<em>Example 1.7: Configuring a specific logger (logback-examples/src/main/java/chapter2/sample-config-3.xml)</em> +<div class="source"><pre><?xml version="1.0" encoding="UTF-8" ?> + +<configuration> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern>%-4relative [%thread] %-5level %class - %msg%n</pattern> + </layout> + </appender> + + <appender name="FILE" + class="ch.qos.logback.core.FileAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern>%-4relative [%thread] %-5level %class - %msg%n</pattern> + </layout> + <File>sample-log.txt</File> + </appender> +<b> + <logger name="chapter2"> + <level value="info" /> + </logger> +</b> + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + <appender-ref ref="FILE" /> + </root> +</configuration> +</pre></div> + + <p>Once done, the output is modified to show only statements of level INFO and higher:</p> + +<div class="source"><pre>0 [main] INFO chapter2.MyAppWithConfigFile - Entering application. +0 [main] INFO chapter2.MyAppWithConfigFile - Exiting application.</pre></div> + + <p>Note that to obtain these different logging behaviors we did not need to recompile code. + We could just as easily have logged to a UNIX Syslog daemon, redirected all chapter2 output + to a log visualizer, or forwarded logging events to a remote logback server, + which would log according to local server policy, for example by forwarding the log event + to a second logback server.</p> + + + <p> + Until now, we always had to specifically load the configuration file and pass it + to a logback component. However, this step is not necessary in most cases. When logback + is not configured by instanciating <code>JoranConfigurator</code> objects, it follows + a simple policy to configure itself. + </p> + + <ul> + <p>Logback first tries to find a file called <em>logback.xml</em> within the classpath.</p> + <p>If no such file is found, it checks for another file called <em>logback-test.xml</em>.</p> + <p>In case none of these files are found, logback configures itself automatically using the + <a href="../xref/ch/qos/logback/classic/BasicConfigurator.html"><code>BasicConfigurator</code> + </a> class.</p> + </ul> + + <p> + The first two checks allow for two environments to cooperate nicely. When the application + using logback is in development and test process, a special file can be used to setup + a logging environment that is developer-friendly. Once in production environment, the + presence of a <em>logback.xml</em> file overrides any <em>logback-test.xml</em> + configuration. + </p> + + <p> + The last step is meant to provide very basic logging functionnality in case no configuration + file is provided. In that case, the logging requests are output to the console. + </p> + + <p> + Letting logback load its configuration file is the most often used way of + configuring. It allows the user to only import SLF4J classes in her code. + </p> + + <p> + The last step of logback's configuration policy permits the use of a minimal + logging configuration right out of the box. Remember the very first example of + this short introduction. The output was generated due to this feature. + </p> + </body> +</document> Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/index.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/manual/index.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/index.xml Mon Jan 22 16:58:04 2007 @@ -61,6 +61,12 @@ <ul> <li><p> + <a href="introduction.html"><b>Chapter 1: Introduction to logback</b></a> + </p></li> + <li><p> + <a href="joran.html"><b>Chapter 2: Architecture</b></a> + </p></li> + <li><p> <a href="joran.html"><b>Chapter 3: Logback configuration with Joran</b></a> </p></li> Added: logback/trunk/logback-site/src/site/xdocTemplates/manual/introduction.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/introduction.xml Mon Jan 22 16:58:04 2007 @@ -0,0 +1,265 @@ +<document> +  + + + <body> + <h2>Introduction</h2> + <div class="author"> + Authors: Ceki Gülcü, Sébastien Pennec + </div> + + + <table> + <tr> + <td valign="top" align="top"> + <a rel="license" + href="http://creativecommons.org/licenses/by-nc-sa/2.5/"> + <img alt="Creative Commons License" + style="border-width: 0" + src="http://creativecommons.org/images/public/somerights20.png" /> + </a> + </td> + <td> + <p>Copyright © 2000-2006, QOS.ch</p> + + <p> +  + This work is licensed under a + <a rel="license" + href="http://creativecommons.org/licenses/by-nc-sa/2.5/"> + Creative Commons + Attribution-NonCommercial-ShareAlike 2.5 + License + </a> + . +  + </p> + </td> + </tr> + </table> + + + <h2>Introduction</h2> + + <p> + Logback is intended as a successor to the popular log4j project. + It was designed by Ceki Gülcü, the log4j founder. + It builds upon a decade long experience gained in + designing industrial-strength logging systems. The resulting + product, logback is faster with a smaller footprint than all + existing logging systems, sometimes by a wide margin. Logback + also offers unique and rather useful features such as Markers, + parameterized logging statements, conditional stack tracing and + powerful event filtering. These are only few examples of useful + features logback has to offer. For its own error reporting, + logback relies on <code>Status</code> objects, which greatly + facilitate troubleshooting. You may wish to rely on Status + objects in contexts other than logging. Logback-core bundles + Joran, a powerful and generic configuration system, which can be + put to use in your own projects to great effect. + </p> + + <h2>First Baby Step</h2> + + <div class="highlight"> + <p> + In order to run the examples in this introduction, you need + to make sure that certain jar files are present on the + classpath. + Please refer to the <a href="setup.html">setup page</a> + for further details. + </p> + </div> + + <h3>Requirements</h3> + + <p>Logback-classic module requires the presence + <em>slf4j-api.jar</em>, <em>logback-core.jar</em> in addition to + <em>logback-classic.jar</em> on the classpath. + </p> + + + <p>Let us now begin experimenting with logback.</p> + +<em>Example 1.1: Basic template for logging (<a href="xref/chapter1/HelloWorld1.html">logback-examples/src/main/java/chapter1/HelloWorld1.java</a>)</em> +<div class="source"><pre>package chapter1; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +public class HelloWorld1 { + + public static void main(String[] args) { + + Logger logger = LoggerFactory.getLogger("chapter1.HelloWorld1"); + logger.debug("Hello world."); + + } +}</pre></div> + + <p> + The <code>HelloWorld</code> class is defined in the + <code>chapter1</code> package. It starts by importing the <code>Logger</code> + and <code>LoggerFactory</code> + classes defined in the SLF4J API, more specifically within the <code>org.slf4j</code> + package. + </p> + + + <p> + On the first line of the main() method, the variable named <code>logger</code> + is assigned a <code>Logger</code> + instance retreived by invoking the static method <code>getLogger</code> + in the <code>LoggerFactory</code> class. + This logger is named "chapter1.HelloWorld1". The main method proceeds to call the + <code>debug</code> method of this logger passing "Hello World" as an argument. + We say that the main + method contains a logging statement of level debug with the message "Hello world". + </p> + + <p> + You will note that the above example does not reference any + logback classes. In most cases, as far as logging is + concerned, your classes will need to import only SLF4J + classes. In principle, you will have to import logback + classes only for configuring logback. Thus, the vast + majority of your classes will only be cognizant of SLF4J API + and oblivious to the existence of logback. + </p> + + + <p>You can launch the first + sample application, <em>chapter1.HelloWord1</em> with the command: + </p> + <div class="source"><pre>java chapter1.HelloWorld1</pre></div> + + <p> + Launching the <code>HelloWorld1</code> + application will output a single line on the console. By virtue of + to logback's default configuration policy, when no default file + is found to configure logback explicitely, logback will add a + <code>ConsoleAppender</code> to the root logger. + </p> + +<div class="source"><pre>20:49:07.962 [main] DEBUG chapter1.HelloWorld1 - Hello world.</pre></div> + + <p> + Logback can report information about its internal state + using a built-in status system. Important events occuring + during logback's lifetime can be accessed through a + <code>StatusManager</code>. For the time being, let us instruct logback to print its + internal state. This is accomplished by a static method in + the <code>LoggerStatusPrinter</code> + class. + </p> + +<em>Example 1.2: Printing Logger Status (<a href="xref/chapter1/HelloWorld2.html">logback-examples/src/main/java/chapter1/HelloWorld2.java</a>)</em> +<div class="source"><pre>package chapter1; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +<b>import ch.qos.logback.classic.util.LoggerStatusPrinter;</b> + +public class HelloWorld2 { + + public static void main(String[] args) { + Logger logger = LoggerFactory.getLogger("chapter1.HelloWorld2"); + logger.debug("Hello world."); + <b>LoggerStatusPrinter.printStatusInDefaultContext();</b> + } +}</pre></div> + + + <p>Running the <code>HelloWorld2</code> application will produce + the following output:</p> + +<div class="source"><pre>20:49:07.962 [main] DEBUG chapter1.HelloWorld2 - Hello world. +|-INFO in ch.qos.logback.classic.BasicConfigurator@1c1ea29 - Setting up default configuration.</pre></div> + + + <p> + Logback explains that it configured itself using its default + policy, which is a basic <code>ConsoleAppender</code>. + An <code>Appender</code> is a class that can be + seen as an output destination. Appenders exist for many different + destinations including the console, files, Syslog, TCP Socket, JMS and + many more. Users can also easily create their own Appenders as + appropriate for their specific situation. + </p> + + <p> + The previous examples are rather simple. However, actual logging + in a larger application would not be any different. The general + pattern logging statements will not change. Only the configuration + process will be different since you will certainly need a more + specific configuration than what logback provides by default. + As you will see later on in this document, + configuring logback can be done in different flexible and + powerfull ways. Note that, normally, you won't need to invoke + <code>LoggerStatusPrinter</code> + after your log statements. + </p> + + <p> + Here is a list of the three required steps in order to enable + logging in your application. + </p> + + <ol> + + <li>Configure the logback environment. You can do so in several + more or less sophisticated ways. More on this later.</li> + + <li>In every class where you wish to perform logging, retrieve a + <code>Logger</code> instance by invoking the + <code>org.slf4j.LoggerFactory</code> class' + <code>getLogger()</code> method, passing the current class name + or the class itself as parameter.</li> + + <li>Use this logger instance by invoking its printing methods, + namely the debug(), info(), warn() and error(). This will + produce logging output on the configured appenders.</li> + </ol> + + <h2>Building logback</h2> + +<p> +Like many java applications today, logback relies on <a href="http://maven.apache.org"> +Maven 2</a> as its build tool. Maven 2 is a free open source build tool that requires +one or more build files names <em>pom.xml</em> which already ship with logback +distributions. +</p> + +<p> +Building all logback components is mostly done by issuing the <em>mvn compile</em> +line in a terminal or command window. Maven 2 will automatically download the required +external libraries and use them. However, a library cannot be downloaded from +the Maven 2 repository. Libraries such as <code>JMS</code> +from sun require a separate download and to issue a command to install their +jars into your local repository. The required command will be presented +by Maven 2 in your console when trying to compile logback. +</p> + +<p> +Logback distributions contain complete source code such that you can modify parts +of logback library and build your own version of it. You may even +redistribute the modified version, as long as you adhere to the conditions +of the LGPL License. In particular you may not call the modified version <em>logback</em> +or claim that it is endorsed by the QOS.ch. +</p> + + + + + + + + + </body> +</document>

1 0

svn commit: r1261 - logback/trunk/logback-site/src/site/xdocTemplates
by noreply.seb＠qos.ch 22 Jan '07

22 Jan '07

Author: seb Date: Mon Jan 22 16:24:29 2007 New Revision: 1261 Modified: logback/trunk/logback-site/src/site/xdocTemplates/demo.xml Log: Improved documentation about the demo Modified: logback/trunk/logback-site/src/site/xdocTemplates/demo.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/demo.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/demo.xml Mon Jan 22 16:24:29 2007 @@ -13,16 +13,18 @@ <p> Welcome to the logback demo! This document will take you to a tour - that will show you some of the most useful possibilities of logback. + that will show you some of the major possibilities of logback. </p> +<h3>Installation</h3> + <p> First, please download the logback demo. You will need to install a <a href="http://subversion.tigris.org/">Subversion</a> client - and issue the following command in a command/terminal window: + and issue the following line in a command/terminal window: </p> -<div class="source"><pre>svn co http://svn.qos.ch/repos/logback-demo logback-demo</pre></div> +<div class="source"><pre>svn co http://svn.qos.ch/repos/logback-demo/trunk logback-demo</pre></div> <p> This will checkout a copy of the logback demonstration web-app to a directory called @@ -46,6 +48,8 @@ <p>image main page</p> +<h3>Logback Classic</h3> + <p> For now, logback uses two components: one <code>ConsoleAppender</code> and one <code>RollingFileAppender</code>. The <code>RollingFileAppender</code> sends logging events @@ -53,7 +57,11 @@ the active file every minute. The old file will be renamed and compressed to <em>zip</em> file. The <code>ConsoleAppender</code> will output the logging requests to the console, and shorten the logger names to gain some space in the console window, without making the -names unreadable. You can study the configuration file that is used by editing the +names unreadable. For example, <code>ch.qos.logback.demo.prime.NumberCruncherImpl +</code> will be displayed as <code>c.q.l.d.prime.NumberCruncherImpl</code>. +</p> + +<p>You can study the configuration file that is used by editing the file called <em>logback.xml</em>, located in the <em>src/main/resources/</em> directory of the demo. You might want to keep this file in an editor window, since we will modify its content several times thoughout the demo. @@ -68,13 +76,15 @@ expected. </p> -<p>image statii page</p> - <p> -Visiting the <em>View logs</em> page does not impress much at the moment. Let us uncomment -the two parts of the config file that are below the <em>Part I: Cyclic buffer</em> comment. +After you're back to the main window, visiting the <em>View logs</em> page does +not impress much at the moment. Let us uncomment +the <strong>two</strong> parts of the config file that are below the <em>Cyclic buffer</em> comment. A <code>CyclicBuffer</code> is a class that keeps track of logging events and holds these -objects for immediate or differed display. +objects for immediate or differed display. The first element that you will need to uncomment +is the <em>appender</em> element. This element describes and configures the <code>CyclicBuffer</code>. +The second element, found at the end of the configuration file, is a <em>appender-ref</em> element. +It is used to link the appender to a given logger. Now reload the web-app by exiting the previous command with <em>CTRL-C</em> and issuing it again: <em>mvn package jetty:run</em>. </p> @@ -83,16 +93,17 @@ Now, the <em>View logs</em> page looks prettier. By virtue of the <code>CyclicBufferAppender</code>, this page can fetch the last events and present them through a servlet. We see that each 3 seconds a line is added to the logs. The formatting of this page is made with -a <code>HTMLLayout</code>. This component creates a nice readable table containing the logging +a <code>HTMLLayout</code>. This component creates a nice and readable table containing the logging events, based on a pattern that describes the information one wants to see in the table. </p> <p> -Having the logs that we see on the web page cluttered with scheduled messages +Having the logs that we see on the web page cluttered with scheduled +<em>Howdydy-diddly-ho</em> messages is not very comfortable. To get rid of these logs, now that we've verified that they work, we can add an <code>EvaluatorFilter</code> to the Appender. Uncomment the -parts named <em>PART II: Cyclic buffer with Evaluator</em>. You may then -comment or delete the first Basic Cyclic buffer elements. +part named <em>Cyclic buffer with Evaluator</em>. You may then +comment or delete the first Basic Cyclic buffer <em>appender</em> element. </p> <p> Let's take a look at the filter we've just added: @@ -125,15 +136,18 @@ <p> After a restart, the <em>Vew logs</em> page shows the -<em>Howdydy-diddly-ho</em> logs for the first 20 seconds only. +<em>Howdydy-diddly-ho</em> logs for the first 20 seconds only. Trying a prime calculations +on the <em>Prime number</em> page will add several lines to the <em>View logs</em> page. </p> +<h4>Turbo Filters</h4> + <p> Logback ships with a special category of filters: <code>TurboFilter</code> objects are ultra-fast, context-wide filters. They reveals themselves very useful to test MDC values, for examples and to add context-wide conditions to allow or deny logging events. Let's uncomment the part named -<em>PART III: TurboFilter: MDC value</em> in the <em>logback.xml</em> file. +<em>TurboFilter: MDC value</em> in the <em>logback.xml</em> file. </p> <p> This part adds a <code>TurboFilter</code> object to the context. It allows to @@ -164,6 +178,8 @@ demo, using the <em>logout</em> button on the left. </p> +<h4>Parametrized logging</h4> + <p> Parametrized logging is a feature that will be a great asset for any performance-critical system. Usually, a logging request is issued like this: @@ -176,7 +192,7 @@ log request is not processed. For example, using the <code>debug()</code> method when, as we've just done, the root level is any value higher that <em>DEBUG</em> will result in a loss of time because all calls to the <code>debug()</code> method will -be eventually dropped. +eventually be dropped. </p> <p> @@ -201,8 +217,8 @@ <p> Now let us edit the <code>NumberCruncherImpl</code> class, to switch the log methods. You will find this class in the <em>src/main/java/ch/qos/logback/demo/prime/</em> -directory. On line 54 and 55, just umcomment the parametrized logging line and -and comment out the other line. Restart the server with <em>mvn package jetty:run</em> +directory. On line 54 and 55, just uncomment the parametrized logging line and +comment out the other line. Restart the server with <em>mvn package jetty:run</em> and re-run the calculations you tried beforehand. </p> @@ -210,35 +226,39 @@ The durations should be obviously different. Remember that we had turned off all logging in the previous step of this demo. With the initial formatting method, we were constructing the logging message (<em>"Trying "+i+" as a factor."</em>) -a huge amount of time, actually each time a factor was tried for these big numbers. +a huge amount of times, actually each time a factor was tried for these big numbers. With the paramatrized logging, the construction of the message was postponed and, since logging was turned off, not processed. We see here that the cost of the <b>non-</b>logging was taken down to a very small figure, dividing the total cost of the calculation by a non-negligeable factor. </p> +<h4>Markers</h4> + <p> SLF4J allows the use of Marker objects. For example, one could use <em>TRACE</em> markers, to enrich some specific logging statements. On the other hand, one could want that such marked statements be dropped and not logged anywhere. <code>TurboFilter</code> objects can do that in an elegant and flexible way. Let us uncomment the -<em>PART V: TurboFilter: Marker value</em> section in the <em>logback.xml</em> file, +<em>TurboFilter: Marker value</em> section in the <em>logback.xml</em> file as +well as set the root logger's level back to <em>DEBUG</em>, and reload via the <em>Reload configuration</em> page. </p> <p> The logging statements that contained the <em>Howdydy-diddly-ho</em> do not appear anymore because they were associated with a <em>TRACE</em> marker. You -can check that by visiting the <em>View Logs</em> page. +can check that by visiting the <em>View Logs</em> page and reloading it every three +seconds for several times. </p> +<h3>Logback Access</h3> + <p> -Access logging is another important feature offered by logback. The first -step will be to simply read what appears on the console while +Access logging is another important feature offered by logback. Give a +look at what appears on the console while browsing the logback-demo website. Each access is logged to the console, -with some information about the access. To achieve this situation, we simply -used a <code>ConsoleAppender</code> and a <code>PatternLayout</code>, just like -we would do in a classic logging configuration. The configuration file +with some information about the event. The configuration file that we will edit in the next few steps is called <em>logback-access.xml</em> and is located in the <em>src/etc/</em> directory. The necessary configuration is listed below: @@ -258,6 +278,42 @@ </configuration></pre></div> <p> +To see more clearly the output produced by logback access, +you might want set the root logger's level to <em>OFF</em>, in the first +logback configuration file, called +<em>logback.xml</em> and located in <em>src/main/resources/</em>. It will clear +the console from the logs made by the demo application and only display those +that are generated by logback access. +</p> + +<p> +To see the logs produced by logback access, just visit a few pages and +look at your console. The information contained in each line has been +specified in the configuration file. The <code>ConsoleAppender</code> +named <em>STDOUT</em> contains a <code>PatternLayout</code> component. +This very component that one uses in logback classic to display either +the message, logger name or level of the request is used in logback +access to display the request method, requested page, status code and many others. +</p> + +<p>Here is a sample output of this appender.</p> + +<div class="source"><pre>127.0.0.1 - - 22/01/2007:14:35:40 +0100 GET /logback-demo/ViewStatii.do HTTP/1.1 200 3660 +127.0.0.1 - - 22/01/2007:14:35:41 +0100 GET /logback-demo/index.jsp HTTP/1.1 200 2389 +127.0.0.1 - - 22/01/2007:14:35:42 +0100 GET /logback-demo/lastLog/ HTTP/1.1 200 948 +127.0.0.1 - - 22/01/2007:14:35:42 +0100 GET /logback-demo/index.jsp HTTP/1.1 200 2389 +127.0.0.1 - - 22/01/2007:14:35:43 +0100 GET /logback-demo/prime.jsp HTTP/1.1 200 1296 +127.0.0.1 - - 22/01/2007:14:35:44 +0100 GET /logback-demo/index.jsp HTTP/1.1 200 2389 +127.0.0.1 - - 22/01/2007:14:35:45 +0100 GET /logback-demo/lottery.jsp HTTP/1.1 200 1209 +127.0.0.1 - - 22/01/2007:14:35:46 +0100 GET /logback-demo/index.jsp HTTP/1.1 200 2389 +127.0.0.1 - - 22/01/2007:14:35:48 +0100 GET /logback-demo/reload.jsp HTTP/1.1 200 1335 +127.0.0.1 - - 22/01/2007:14:35:49 +0100 GET /logback-demo/index.jsp HTTP/1.1 200 2389 +127.0.0.1 - - 22/01/2007:14:35:54 +0100 GET /logback-demo/login.jsp HTTP/1.1 200 1214 +127.0.0.1 - - 22/01/2007:14:35:55 +0100 GET /logback-demo/Logout.do HTTP/1.1 200 1000</pre></div> + +<h4>Filtering</h4> + +<p> In this next part, we are going to add some information to the console. Let us imagine that we want to log the numbers that are tried on the <em>Lottery</em> page. We will need a second <code>ConsoleAppender</code> @@ -275,10 +331,10 @@ <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> <evaluator name="lotto_eval"> <Expression> - url.matches(request.getRequestURL().toString()) + url.matches(event.getRequestURL().toString()) </Expression> <matcher name="url"> - <regex>lotto.do</regex> + <regex>Lottery.do</regex> <caseSensitive>false</caseSensitive> </matcher> </evaluator> @@ -287,7 +343,7 @@ </filter> <layout class="ch.qos.logback.access.PatternLayout"> <Pattern> - LOTTO: %A [%r] Guess=%reqParameter{guessed_number} + LOTTERY: %A [%r] Guess=%reqParameter{guessed_number} </Pattern> </layout> </appender></pre></div> @@ -302,27 +358,48 @@ to display anything when the access' request url does not match the given expression. You can see that it is easy to specify a RegExp, name it and use it in the expression that will be evaluated. In that case, we only -entered the name of the <em>lotto.do</em> action. +entered the name of the <em>lottery.do</em> action. </p> <p> -Before shutting down the server and starting it again with the new configuration, -you might want to comment the appender named <em>STDOUT</em>, as well as its -<em>appender-ref</em> element, in the first logback configuration file, called -<em>logback.xml</em> and located in <em>src/main/resources/</em>. It will clear -the console from the logs made by the demo application and only display those -that are generated by logback access. +Let us uncomment the two elements with the <em>Lottery to Console</em> comments and +restart the server. Now, try to play the lottery. You will see more lines in the +Console that you've seen until now. At every try, logback will produce a log +as shown below: </p> +<div class="source"><pre>LOTTERY: 192.168.1.6 [POST /logback-demo/Lottery.do HTTP/1.1] Guess=321</pre></div> + +<h4>Sending emails</h4> +<p> +Logback access provides several components that are usually used by the classic +module. For example, a <code>SMTPAppender</code> can be used to send an email when +a specific event occurs. Here, we will contact the lottery administrator each time +a winner is detected. To achieve this, we will add a <code>SMTPAppender</code> to +the existing configuration. Please uncomment the part of <em>logback-access.xml</em> +named <em>Lottery to Email</em>. Do not forget to uncomment the +<em>appender-ref</em> element, at the end of the configuration file, referencing +the appender called <em>SMTP</em>. In the appender element, notice the use of a +<code>URLEvaluator</code>. This evaluator allows us to only specify one or more URLs +that have to be watched. When one of them are accessed, an email is sent. +</p> <p> - SMTP and +A reload of the configuration has to be done before we can test this new +component. Once done, try to play the lottery with the number <em>99</em>. +You should see a congratulation message but, most importantly, the +specified recipients should have a new mail in their mailbox. The content +of the email is a nicely formatted HTML table with informations about +the access that have occured before the triggering event. </p> +<h3>JMX</h3> + <p> Logback publishes several components via JMX. This allows you to see the status of certain objects, and change several configuration parameters. +Publishing logback's components via JMX is possible with Jetty and Tomcat. </p> <p> @@ -354,7 +431,7 @@ </p> <p> -By refreshing the loaded previously JMX page, you should see a new component, +By refreshing the previously loaded JMX page, you should see a new component, under the domain <em>ch.qos.logback.classic</em>. It is the <code>JMXConfigurator</code>. Clicking on it reveals its content. Its possibilities are listed below: </p> @@ -384,13 +461,37 @@ </p> <p> -Let us test the configurator. If you try to use the <em>Prime Number</em> page and -look at the <em>View logs</em> page after, you should see two types of logs. When the +Checking the level of a logger is an easy task. Enter the name of the logger in +the appropriate field and click the <em>Invoke</em> button. You should be able +to verify that the logger named <em>root</em> has its level set to <em>OFF</em>. +</p> + + +<p> +Let us test the level setting possibility of the configurator. +The <em>Prime Number</em> page requests two types of logs. When the calculation checks if a number is a factor, a <em>DEBUG</em> log is displayed. When -the calculation has found a factor, a <em>INFO</em> log is displayed. If you set the level -of the <em>ch.qos.logback.demo.prime</em> logger to <em>INFO</em>, and run a prime calculation +the calculation has found a factor, a <em>INFO</em> log is displayed. +</p> + +<p> +Let us first set the level of the logger named <em>ch.qos.logback.demo.prime</em> +to <em>DEBUG</em>. Run a prime calculation directly, without restarting the server. The +<em>View logs</em> page should show the <em>DEBUG</em> and <em>INFO</em> logs. +</p> + +<p> +Now, if you set the level of the <em>ch.qos.logback.demo.prime</em> logger to +<em>INFO</em>, and run a prime calculation again, you should not see the <em>DEBUG</em> level logs anymore. </p> +<p> +This demo of logback is now over. Do not hesitate to play around with the configuration files. +You might want to check the <a href="http://logback.qos.ch/documentation.html"> +logback documentation page</a> for more information about any component +you'd like to test. +</p> + </body> </document> \ No newline at end of file

1 0

svn commit: r1260 - in logback-demo/trunk/src: etc main/resources
by noreply.seb＠qos.ch 22 Jan '07

22 Jan '07

Author: seb Date: Mon Jan 22 16:23:51 2007 New Revision: 1260 Modified: logback-demo/trunk/src/etc/logback-access.xml logback-demo/trunk/src/main/resources/logback.xml Log: Updates after doc modifications Modified: logback-demo/trunk/src/etc/logback-access.xml ============================================================================== --- logback-demo/trunk/src/etc/logback-access.xml (original) +++ logback-demo/trunk/src/etc/logback-access.xml Mon Jan 22 16:23:51 2007 @@ -7,7 +7,7 @@ </layout> </appender> -  -  -  -  Modified: logback-demo/trunk/src/main/resources/logback.xml ============================================================================== --- logback-demo/trunk/src/main/resources/logback.xml (original) +++ logback-demo/trunk/src/main/resources/logback.xml Mon Jan 22 16:23:51 2007 @@ -32,14 +32,14 @@ </layout> </appender> -  -  -  -  -

1 0

svn commit: r1259 - in logback-demo/trunk/src: etc main/resources
by noreply.seb＠qos.ch 22 Jan '07

22 Jan '07

Author: seb Date: Mon Jan 22 14:57:19 2007 New Revision: 1259 Modified: logback-demo/trunk/src/etc/logback-access.xml logback-demo/trunk/src/main/resources/logback.xml Log: start state for the demo Modified: logback-demo/trunk/src/etc/logback-access.xml ============================================================================== --- logback-demo/trunk/src/etc/logback-access.xml (original) +++ logback-demo/trunk/src/etc/logback-access.xml Mon Jan 22 14:57:19 2007 @@ -7,13 +7,13 @@ </layout> </appender> -  +  -  @@ -58,9 +58,12 @@ <appender-ref ref="STDOUT" /> -  +  + +  -  </configuration> \ No newline at end of file Modified: logback-demo/trunk/src/main/resources/logback.xml ============================================================================== --- logback-demo/trunk/src/main/resources/logback.xml (original) +++ logback-demo/trunk/src/main/resources/logback.xml Mon Jan 22 14:57:19 2007 @@ -2,6 +2,10 @@ <configuration> +  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <layout class="ch.qos.logback.classic.PatternLayout"> @@ -10,7 +14,7 @@ </pattern> </layout> </appender> - + <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> <File>logFile.log</File> @@ -35,13 +39,13 @@ </appender> --> -  +  + +  + -->  -  - + <root> <level value="DEBUG" /> + <appender-ref ref="STDOUT" /> - <appender-ref ref="FILE" /> -  + <appender-ref ref="FILE" /> + +  + </root> </configuration>

1 0

svn commit: r1258 - logback-demo/trunk
by noreply.seb＠qos.ch 22 Jan '07

22 Jan '07

Author: seb Date: Mon Jan 22 14:20:12 2007 New Revision: 1258 Modified: logback-demo/trunk/pom.xml Log: Updated version numbers Modified: logback-demo/trunk/pom.xml ============================================================================== --- logback-demo/trunk/pom.xml (original) +++ logback-demo/trunk/pom.xml Mon Jan 22 14:20:12 2007 @@ -26,7 +26,7 @@ <dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-classic</artifactId> - <version>0.8-SNAPSHOT</version> + <version>0.8.1-SNAPSHOT</version> <scope>compile</scope> <exclusions> <exclusion> @@ -37,16 +37,9 @@ </dependency> <dependency> - <groupId>janino</groupId> - <artifactId>janino</artifactId> - <version>2.4.3</version> - <scope>provided</scope> - </dependency> - - <dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-access</artifactId> - <version>0.8-SNAPSHOT</version> + <version>0.8.1-SNAPSHOT</version> <scope>provided</scope> </dependency> </dependencies> @@ -65,7 +58,9 @@ <plugin> <groupId>org.mortbay.jetty</groupId> - <artifactId>maven-jetty-plugin</artifactId> + <artifactId>maven-jetty-plugin</artifactId> +  + <version>6.1.1</version> <configuration> <scanIntervalSeconds>0</scanIntervalSeconds> <jettyConfig>${basedir}/src/etc/jetty.xml</jettyConfig> @@ -75,13 +70,13 @@ <dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-access</artifactId> - <version>0.8-SNAPSHOT</version> + <version>0.8.1-SNAPSHOT</version> <scope>runtime</scope> </dependency> <dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-core</artifactId> - <version>0.8-SNAPSHOT</version> + <version>0.8.1-SNAPSHOT</version> <scope>runtime</scope> </dependency> <dependency>

1 0