[LOGBack-dev] svn commit: r391 - logback/classic/trunk/src/site/xdocTemplates
noreply.ceki at qos.ch
noreply.ceki at qos.ch
Sun Aug 6 13:18:06 CEST 2006
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>
More information about the logback-dev
mailing list