Author: ceki Date: Sun Aug 6 13:18:05 2006 New Revision: 391 Modified: logback/classic/trunk/src/site/xdocTemplates/shortIntro.xml Log: various improvements Modified: logback/classic/trunk/src/site/xdocTemplates/shortIntro.xml ============================================================================== --- logback/classic/trunk/src/site/xdocTemplates/shortIntro.xml (original) +++ logback/classic/trunk/src/site/xdocTemplates/shortIntro.xml Sun Aug 6 13:18:05 2006 @@ -44,111 +44,112 @@ <h2>Introduction</h2> - <p> - Logging is a low-tech way of debugging your code. It might - also be the only way, when debuggers are not available or - applicable. Logback classic can help you insert logging - functionalities in your code without polluting its - readability with useless statements, or diminishing its - performance. - </p> - <p> + <p> Logback is intended as a successor to the popular log4j - project. It was also designed by Ceki Gülcü, the - founder of the log4j project. It builds upon experience - gained in building industrial-strength logging systems going - back as far as 1999. + project. It was designed by Ceki Gülcü, the founder of + the log4j project. It builds upon a decade long experience + gained in designing industrial-strength logging systems. The + resulting product is at faster and has a smaller footprint than + all the 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, to cite a few. For + its own error reporting, logback relies on <code>Status</code> + objects which come in handy in contexts other than logging. </p> - <p> - Before rushing to install and configure logback classic on - your own application, here is a presentation of how things - work. + + <p>This document presents the more basic concepts in logback, + probably just enough to get you started. </p> <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>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 Core module lays the groundwork for the other two - modules. The Classic module extends the core module, it can be + modules. The Classic module extends Core. Classic can be assimilated to an improved version of log4j. Logback Classic - natively implements the SLF4J API so that you can readily switch - back and forth between logback and other logging systems such as - log4j or JDK14 Logging. The Access module also extends the core - functionnalities and integrates with Servlet containers to provide - HTPP-access log functionality. + 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 Access module integrates with Servlet containers to + provide HTPP-access log functionality. The Access module will be + covered in a separate document. </p> - <p>Note that you can easily build your own modules on top of the - Core module. - </p> - - <h2>First Baby Steps</h2> - - <p> After you have added the jar fiiles <em>logback-core.jar</em> - and <em>logback-classic.jar</em> to your classpath, you can start - testing a small program that uses logback. - </p> - -<div class="source"> -package chapter1; - -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; - -public class BabySteps1 { + <h2>First Baby Step</h2> - - public static void main(String[] args) { - - Logger logger = LoggerFactory.getLogger(BabySteps1.class); - logger.debug("Hello world."); - - } -} + <p>After you have added the jar fiiles <em>logback-core.jar</em> + and <em>logback-classic.jar</em> to your classpath, we can start + experimenting with logback. + </p> + +<div class="source">1 package chapter1; +2 +3 import org.slf4j.Logger; +4 import org.slf4j.LoggerFactory; +5 +6 public class HelloWorld1 { +7 +8 public static void main(String[] args) { +9 +10 Logger logger = LoggerFactory.getLogger(BabyStep1.class); +11 logger.debug("Hello world."); +12 +13 } +14 } </div> - <p> - This is the basic, yet usual way of using logback classic. - It starts by importing the Logger and LoggerFactory from SLF4J. - You will note that, for the sake of compatibility with SLF4J and - implementation-freedom, no actual reference to any of the logback - classic classes is required. - You only import and use SLF4J classes for usual logging. - </p> - <p> - Then a static variable gets a Logger that is initialised with the - <code>BabySteps.class</code>. - The main method then invokes the debug method of the received Logger. - It gives the method a simple String with the message to log. - Put differently, the main method contains a logging statement of - level debug containing the message “Hello world”. + <!-- STOPPED HERE: COGNIZANT? --> + + <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 as + defined in the SLF4J API, more specifically in the + <code>org.slf4j</code> package. 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>Then a static variable gets a Logger that is initialised with + the <code>HelloWorld</code> class. The main method then invokes the + debug method of the received Logger. It gives the method a simple + String with the message to log. Put differently, the main method + contains a logging statement of level debug containing the message + “Hello world”. </p> + <p> You can compile and run this class as follows: </p> - <div class="source">java ch.qos.logback.classic.examples.BabySteps1</div> - <p> - This will not produce any logging output. What happened? - Well, a powerful tool in logback is the Status and associated classes. - It keeps track of any events of importance that happen during the use - of logback. A simple statement can help us see why nothing was logged: + + <div class="source">java ch.qos.logback.classic.examples.HelloWorld1</div> + + <p>This will not produce any logging output. What happened? + Well, a powerful tool in logback is the Status and associated + classes. It keeps track of any events of importance that happen + during the use of logback. A simple statement can help us see why + nothing was logged: </p> -<div class="source"> -package ch.qos.logback.classic.examples; + +<div class="source">package ch.qos.logback.classic.examples; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import ch.qos.logback.classic.util.LoggerStatusPrinter; -public class BabySteps2 { +public class HelloWorld2 { - final static Logger logger = LoggerFactory.getLogger(BabySteps1.class); + final static Logger logger = LoggerFactory.getLogger(HelloWorld1.class); public static void main(String[] args) { @@ -164,8 +165,8 @@ output to the console the next lines: </p> <div class="source"> -ERROR in Logger[ch.qos.logback.classic.examples.BabySteps2] - No appenders present \\ -in the hierarchy [default] for logger [ch.qos.logback.classic.examples.BabySteps2]. +ERROR in Logger[ch.qos.logback.classic.examples.HelloWorld2] - No appenders present \\ +in the hierarchy [default] for logger [ch.qos.logback.classic.examples.HelloWorld2]. </div> <p> We now know why nothing was logged: no Appenders are configured. @@ -188,9 +189,9 @@ import ch.qos.logback.BasicConfigurator; import ch.qos.logback.classic.util.LoggerStatusPrinter; -public class BabySteps3 { +public class HelloWorld3 { - final static Logger logger = LoggerFactory.getLogger(BabySteps1.class); + final static Logger logger = LoggerFactory.getLogger(HelloWorld1.class); public static void main(String[] args) { @@ -201,26 +202,32 @@ } } </div> + <p> - Let's run the BabySteps class again. Now, the BasicConfigurator will create - a simple console Appender. The logging request will then be propagated to - the Appender and the console will output the following: + Let's run the <code>HelloWorld3</code> application again. Now, + the <code>BasicConfigurator</code> will create a simple + <code>ConsoleAppender</code>. The logging request will then be + propagated to the Appender and the console will output the + following: </p> <div class="source"> -0 [main] DEBUG ch.qos.logback.classic.examples.BabySteps3 - Hello world. -This status manager contains no errors. +0 [main] DEBUG ch.qos.logback.classic.examples.HelloWorld3 - Hello world. </div> + <p> - This example is very simple. However, actual logging in a bigger - application is not much more complicated. The logging statement will barely - change. Only the configuration process will be different, since you don't - need (nor should) configure the logging context in each and every class that - will require logging. As well, the LoggerStatusPrinter will certainly not be + This example is very simple. However, actual logging in a larger + application is not much more complicated. The logging statement + will barely change. Only the configuration process will be + different, since you don't need (nor should) configure the + logging context in each and every class that will require + logging. As well, the LoggerStatusPrinter will certainly not be used after all the logging statements. </p> + <p> These are the three steps that are required to allow full logging in any application. </p> + <ol> <li>Configure the logback classic environment. You can do it using several sophisticated ways. The BasicConfigurator is the simplest but also least flexible.</li> @@ -551,22 +558,11 @@ </table> <p> - In example 4, the loggers - <code>root</code> - and - <code>X</code> - and are assigned the levels - <code>Proot</code> - and - <code>Px</code> - - respectively. The loggers - <code>X.Y</code> - and - <code>X.Y.Z</code> - inherits their level value from their nearest parent - <code>X</code> - having an assigned level. + In example 4, the loggers <code>root</code> and <code>X</code> + and are assigned the levels <code>Proot</code> and + <code>Px</code> respectively. The loggers <code>X.Y</code> and + <code>X.Y.Z</code> inherits their level value from their nearest + parent <code>X</code> having an assigned level. </p> <p> @@ -1045,25 +1041,6 @@ 0 [main] INFO ch.qos.logback.classic.examples.MyApp - Exiting application. </div> - - - - - - - - - - - - - - - - - - - </body> </document>