[logback-dev] svn commit: r1564 - in logback/trunk/logback-site/src/site/pages: . manual
noreply.ceki at qos.ch
noreply.ceki at qos.ch
Tue Aug 21 17:44:54 CEST 2007
Author: ceki
Date: Tue Aug 21 17:44:53 2007
New Revision: 1564
Modified:
logback/trunk/logback-site/src/site/pages/manual/architecture.html
logback/trunk/logback-site/src/site/pages/manual/index.html
logback/trunk/logback-site/src/site/pages/manual/joran.html
logback/trunk/logback-site/src/site/pages/manual/mdc.html
logback/trunk/logback-site/src/site/pages/news.html
Log:
- various documentation improvements
- fixed bug 90 by removing the outdated "configuration" section in chapter 2.
It was a duplicate of a homonym in chapter 3.
Modified: logback/trunk/logback-site/src/site/pages/manual/architecture.html
==============================================================================
--- logback/trunk/logback-site/src/site/pages/manual/architecture.html (original)
+++ logback/trunk/logback-site/src/site/pages/manual/architecture.html Tue Aug 21 17:44:53 2007
@@ -755,466 +755,190 @@
<div class="source"><pre>Object[] paramArray = {newVal, below, above};
logger.debug("Value {} was inserted between {} and {}.", paramArray);</pre></div>
- <a name="Configuration"></a>
- <h3>Configuration</h3>
+
+ <a name="UnderTheHood"></a>
+ <h3>A peak under the hood</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>
-
- <script src="../templates/setup.js"></script>
-
- <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 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;
-
-//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>
+ <p>After we have introduced the essential logback components, we are
+ now ready to describe the steps that the logback framework takes
+ when the user invokes a logger's printing method. Let us now analyze
+ the steps logback takes when the user invokes the
+ <code>info()</code> method of a logger named <em>com.wombat</em>.
+ </p>
- <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;
-import org.slf4j.LoggerFactory;
+ <h4>1. Get the filter chain decision</h4>
+
+ <p>If it exists, the <code>TurboFilter</code> chain is
+ invoked. Turbo filters can set a context-wide threshold, or to
+ filter out certain events based on information such as
+ <code>Marker</code>, <code>Level</code>, <code>Logger</code>,
+ message, or the <code>Throwable</code> that are associated with each
+ logging request. If the reply of the filter chain is
+ <code>FilterReply.DENY</code>, then the logging request is
+ dropped. If it is <code>FilterReply.NEUTRAL</code>, then we continue
+ with the next step, i.e. step 2. In case the reply is
+ <code>FilterReply.ACCEPT</code>, we skip the next and directly jump
+ to step 3.
+ </p>
+
+ <h4>2. Apply the Logger level filter</h4>
+
+ <p>At this step, logback compares the effective level of the logger
+ with the level of the request. If the logging request is disabled
+ according to this test, then logback will drop the request without
+ further processing. Otherwise, it proceeds to the next step.
+ </p>
+
+ <h4>3. Create a <code>LoggingEvent</code> object</h4>
+
+ <p>If the request passed the previous filters, logback will create a
+ <code>ch.qos.logback.classic.LoggingEvent</code> object containing
+ all the relevant parameters of the request, such as the logger of
+ the request, the request level, the message itself, the exception
+ that might have been passed along with the request, the current
+ time, the current thread, various data about the class that issued
+ the logging request and the <code>MDC</code>. Note that some of
+ these fields are initialized lazily, that is only when they are
+ actually needed. The <code>MDC</code> is used to decorate the
+ logging request with additional contextual information. MDC is
+ discussed in a <a href="mdc.html">separate chapter</a>.</p>
+
+ <h4>4. Invoking appenders</h4>
+
+ <p>After the creation of a <code>LoggingEvent</code> object, logback
+ invokes the <code>doAppend()</code> methods of all the applicable
+ appenders, that is, the appenders inherited from the logger context.
+ </p>
+
+
+ <p>All appenders shipped with the logback distribution extend the
+ <code>AppenderBase</code> abstract class that implements the
+ <code>doAppend</code> method in a synchronized block ensuring
+ thread-safety. The <code>doAppend()</code> method of
+ <code>AppenderBase</code> also invokes custom filters attached to
+ the appender, if any such filters exist. Custom filters, which can
+ be dynamically attached to any appender, are presented in a <a
+ href="filters.html">separate chapter</a>.
+ </p>
+
+ <h4>5. Formatting the output</h4>
+
+ <p>It is responsibility of the invoked appender to format the
+ logging event. However, some (but not all) appenders delegate the
+ task of formatting the logging event to a layout. A layout formats
+ the <code>LoggingEvent</code> instance and returns the result as a
+ String. Note that some appenders, such as the
+ <code>SocketAppender</code>, do not transform the logging event into
+ a string but serialize it instead. Consequently, they do not
+ require nor have a layout.
+ </p>
-class Bar {
+ <h4>6. Sending out the <code>LoggingEvent</code></h4>
- 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 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>
-
- <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 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>
-
- <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 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>
-
- <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
- the introduction. The output was generated due to this feature.
- </p>
+ <p>After the logging event is fully formatted it is sent to its
+ destination by each appender.
+ </p>
-<a name="UnderTheHood"></a>
-<h3>A peak under the hood</h3>
+ <p>
+ Here is a sequence UML diagram to show how everything works. You might
+ want to click on the image to display its bigger version.
+ </p>
-<p>
-After we have introduced the essential logback components, we are now
-ready to describe the steps that the logback framework takes when the user invokes
-a logger's printing method. Let us now analyze the steps logback takes when the
-user invokes the <code>info()</code> method of a
-logger named <em>com.wombat</em>.
-</p>
-
-<h4>1. Get the filter chain decision</h4>
-
-<p>
-Logback's <code>TurboFilter</code> chain is called. These filters may
-be used to prodvide a context-wide threshold, or to filter out certain
-events based on basic logging informations such as <code>Marker</code>,
-<code>Level</code>, <code>Logger</code>, message, or the <code>Throwable</code>
-that was provided in the logging request.
-If the reply of the filter chain is <code>FilterReply.DENY</code>, then the
-logging request is dropped. If it is <code>FilterReply.NEUTRAL</code>, then
-the next step is processed. In case the reply is <code>FilterReply.ACCEPT</code>,
-the next step is skipped and the logging request is directly processed to step 3.
-</p>
-
-<h4>2. Apply the Logger level filter</h4>
-
-<p>
-Logback compares the effective level of the <em>com.wombat</em> logger
-with the level of the request (in this example: <em>INFO</em>). If the logging
-request is disabled, then logback will drop the request without further processing.
-</p>
-
-<h4>3. Create a <code>LoggingEvent</code> object</h4>
-
-<p>
-If the request passed the previous filter, or if the <code>TurboFilter</code> chain
-gave a <code>FilterReply.ACCEPT</code> result, logback will create a
-<code>ch.qos.logback.classic.LoggingEvent</code> object containing all the
-relevant parameters of the request such as the logger of the request, the request
-level, the message, the exception that might have been passed along the request,
-the current time, the current thread, several information about the class that
-issued the logging request and the <code>MDC</code> map. Note that some of these fields
-are initialized lazily, that is only when they are actually needed. The <code>MDC</code> is used to stamp each requests with specific parameters. It is introduced in the <a href="mdc.html">corresponding chapter</a>.</p>
-
-<h4>4. Invoking appenders</h4>
-
-<p>
-After the creation of a <code>LoggingEvent</code> object, logback will proceed
-to invoke the <code>doAppend()</code> methods of all the applicable appenders,
-that is, the appenders inherited from the logger context.
-</p>
-<p>
-All appenders shipped with the logback distribution extend the
-<code>AppenderBase</code> abstract class that implements the
-<code>doAppend</code> method in a synchronized block ensuring thread-safety.
-The <code>doAppend()</code> method of <code>AppenderBase</code> also invokes
-custom filters attached to the appender, if any such filters exist.
-Custom filters, which can be dynamically attached to any appender,
-are presented Chapter 6.
-</p>
-
-<h4>5. Formatting the <code>LoggingEvent</code></h4>
-
-<p>
-It is responsibility of the invoked appender to format the
-logging event. However, most (but not all) appenders delegate
-the task of formatting the logging event to their layout. Their
-layout formats the <code>LoggingEvent</code> instance and returns the
-result as a String. Note that some appenders, such as the
-<code>SocketAppender</code>, do not transform the logging event
-into a string but serialize it instead.
-Consequently, they do not require nor have a layout.
-</p>
-
-<h4>6. Sending out the <code>LoggingEvent</code></h4>
-
-<p>
-After the logging event is fully formatted it is sent to
-its destination by each appender.
-</p>
+ <a href="underTheHood.html"><img src="images/chapter2/underTheHoodSequence2_small.gif" /></a>
+
+ <a name="Performance"></a>
+ <h3>Performance</h3>
+
+ <p>One of the often-cited arguments against logging is its
+ computational cost. This is a legitimate concern as even moderately
+ sized applications can generate thousands of log requests. Much
+ effort is spent measuring and tweaking logging performance.
+ Independently of these efforts, the user should still be aware of
+ the following performance issues.
+ </p>
+
+ <h4>1. Logging performance when logging is turned off entirely</h4>
+
+ <p>
+ You can turn off logging entirely by setting the level of the root logger
+ to <code>Level.OFF</code>, the highest possible level.
+ When logging is turned off entirely,
+ the cost of a log request consists of a method invocation plus an
+ integer comparison. On a 3.2Ghz Pentium D machine this cost is typically
+ around 20 nanoseconds.
+ </p>
+
+ <p>
+ However, any method invocation involves the "hidden" cost of parameter construction.
+ For example, for some logger <em>x</em> writing,
+ </p>
-<p>
-Here is a sequence UML diagram to show how everything works. You might
-want to click on the image to display its bigger version.
-</p>
-
-<a href="underTheHood.html"><img src="images/chapter2/underTheHoodSequence2_small.gif" /></a>
-
-<a name="Performance"></a>
-<h3>Performance</h3>
-
-<p>
-One of the often-cited arguments against logging is its computational cost.
-This is a legitimate concern as even moderately sized applications can generate
-thousands of log requests. Much effort is spent measuring and tweaking
-logging performance.
-Independently of these efforts, the user should still be aware of the following
-performance issues.
-</p>
-
-<h4>1. Logging performance when logging is turned off entirely</h4>
-
-<p>
-You can turn off logging entirely by setting the level of the root logger
-to <code>Level.OFF</code>, the highest possible level.
-When logging is turned off entirely,
-the cost of a log request consists of a method invocation plus an
-integer comparison. On a 3.2Ghz Pentium D machine this cost is typically
-around 20 nanoseconds.
-</p>
-
-<p>
-However, any method invocation involves the "hidden" cost of parameter construction.
-For example, for some logger <em>x</em> writing,
-</p>
-
-<div class="source"><pre>x.debug("Entry number: " + i + "is " + entry[i]);</pre></div>
-
-<p>
-incurs the cost of constructing the message parameter, i.e. converting both
-integer <code>i</code> and <code>entry[i]</code> to a string, and concatenating
-intermediate strings, regardless of whether the message will be logged or not.
-</p>
-
-<p>
-The cost of parameter construction can be quite high and depends on the size
-of the parameters involved. To avoid the cost of parameter construction
-you can use logback's parametrized logging:
-</p>
-
-<div class="source"><pre>x.debug("Entry number: {} is {}", i, entry[i]);</pre></div>
-
-<p>
-This will not incur the cost of parameter construction. Compared to the
-previous call to the <code>debug()</code> method, this call will be faster by
-a very wide margin.
-The message will be formatted only if the request is processed to the appenders.
-If it is processed, the component that formats the message offers high performance
-and does not impact negatively the overall process.
-It respectively takes 2 and 4 microseconds to format a message with 1 and 3 parameters.
-</p>
-
-<p>
-Please notice that, despite the performance points that we just discussed, inserting
-logging statements in tight-loops or very frequently invoked code is a lose-lose proposal
-and will not result in high performance. They will slow down your application even
-if logging is turned off or generate massive (and hence useless) output if enabled.
-</p>
-
-<h4>2. The performance of deciding whether to log or not to log when logging is turned on.</h4>
-
-<p>
-In logback, there is no need to walk the whole logger hierarchy. A logger knows
-its effective level (that is, its level, once level inheritance has been
-taken into consideration) when it is created. Should the level of a parent logger
-be changed, then all child loggers will be contacted and handle the change. Thus, before
-accepting or denying a request based on the effective level, the logger does not need
-to search its ancestors.
-</p>
-
-<p>
-Given this situation, it takes the same time to decide whether to log or not when logging
-is turned on as it takes when logging is turned off.
-</p>
-
-<h4>3. Actual logging (formatting and writing to the output device)</h4>
-
-<p>
-This is the cost of formatting the log output and sending it to its
-target destination. Here again, a serious effort was made to make
-layouts (formatters) perform as quickly as possible.
-The same is true for appenders. The typical cost of actually logging is
-about 9 to 12 microseconds when logging to a file on the local machine.
-It goes up to 1 millisecond when logging to a database on a remote server.
-</p>
-
-<p>
-Although feature-rich, one of the foremost design goals of logback was speed
-of execution, a requirement which is second only to reliability. Some logback
-components have been rewritten many times to improve performance.
-</p>
+ <div class="source"><pre>x.debug("Entry number: " + i + "is " + entry[i]);</pre></div>
+
+ <p>
+ incurs the cost of constructing the message parameter, i.e. converting both
+ integer <code>i</code> and <code>entry[i]</code> to a string, and concatenating
+ intermediate strings, regardless of whether the message will be logged or not.
+ </p>
+
+ <p>The cost of parameter construction can be quite high and depends
+ on the size of the parameters involved. To avoid the cost of
+ parameter construction you can take advantage of SLF4J's parametrized
+ logging:
+ </p>
+
+ <div class="source"><pre>x.debug("Entry number: {} is {}", i, entry[i]);</pre></div>
+
+ <p>
+ This variant will not incur the cost of parameter
+ construction. Compared to the previous call to the
+ <code>debug()</code> method, it will be faster by a very wide
+ margin. The message will be formatted only if the request is
+ processed to the appenders. If it is processed, the component
+ that formats the message offers high performance and does not
+ impact negatively the overall process. It respectively takes 2
+ and 4 microseconds to format a message with 1 and 3 parameters.
+ </p>
+
+ <p> Please notice that, despite the performance points that we just
+ discussed, inserting logging statements in tight-loops or very
+ frequently invoked code is a lose-lose proposal and is likely to
+ result in degraded performance. Logging in tight-loops slow down
+ your application even if logging is turned off, and if logging is
+ turned on, they will generate massive (and hence useless) output.
+ </p>
+
+ <h4>2. The performance of deciding whether to log or not to log when
+ logging is turned on.</h4>
+
+ <p>
+ In logback, there is no need to walk the logger hierarchy. A
+ logger knows its effective level (that is, its level, once level
+ inheritance has been taken into consideration) when it is
+ created. Should the level of a parent logger be changed, then all
+ child loggers are contacted to take notice of the change. Thus,
+ before accepting or denying a request based on the effective
+ level, the logger can make an quasi-instantaneous decision,
+ without needing to consult its ancestors.
+ </p>
+
+
+ <h4>3. Actual logging (formatting and writing to the output device)</h4>
+
+ <p>This is the cost of formatting the log output and sending it to
+ its target destination. Here again, a serious effort was made to
+ make layouts (formatters) perform as quickly as possible. The same
+ is true for appenders. The typical cost of actually logging is about
+ 9 to 12 microseconds when logging to a file on the local machine.
+ It goes up to several milliseconds when logging to a database on a
+ remote server.
+ </p>
+
+ <p>Although feature-rich, one of the foremost design goals of
+ logback was speed of execution, a requirement which is second only
+ to reliability. Some logback components have been rewritten several
+ times to improve performance.
+ </p>
<script src="../templates/footer.js"></script>
Modified: logback/trunk/logback-site/src/site/pages/manual/index.html
==============================================================================
--- logback/trunk/logback-site/src/site/pages/manual/index.html (original)
+++ logback/trunk/logback-site/src/site/pages/manual/index.html Tue Aug 21 17:44:53 2007
@@ -33,7 +33,7 @@
<li><p>appenders</p></li>
<li><p>layouts</p></li>
<li><p>filter chains</p></li>
- <li><p>logback diagnostic contexts</p></li>
+ <li><p>mapped diagnostic contexts</p></li>
<li><p>logback default initialization</p></li>
<li><p>logback in Servlet Containers</p></li>
</ul>
@@ -93,7 +93,7 @@
</p></li>
<li><p>
- <a href="mdc.html"><b>Chapter 7: Diagnostic Context</b></a>
+ <a href="mdc.html"><b>Chapter 7: Mapped Diagnostic Context</b></a>
</p></li>
<li><p>
Modified: logback/trunk/logback-site/src/site/pages/manual/joran.html
==============================================================================
--- logback/trunk/logback-site/src/site/pages/manual/joran.html (original)
+++ logback/trunk/logback-site/src/site/pages/manual/joran.html Tue Aug 21 17:44:53 2007
@@ -33,27 +33,41 @@
<script src="../templates/creative.js"></script>
- <script src="../templates/setup.js"></script>
<p>Joran stands for a cold north-west wind which, every now and
- then, blows forcefully on Lake Leman, a.k.a. lake Geneva. Located
- right in the middle of Europe, the Leman lake happens to be the
- continent's largest sweet water reserve.
+ then, blows forcefully on Lake Geneva. Located right in the middle
+ of Europe, the Geneva lake happens to be the continent's largest
+ sweet water reserve.
</p>
<p>In the first part, we start by presenting ways for configuring
logback, with many example configuration scripts. In the <a
href="#Joran">second part</a>, we present Joran, a generic
- configuration framework, that you can put to use in order to
+ configuration framework, that you can put into use in order to
configure your own applications.
</p>
<h2>Configuration in logback</h2>
+ <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, we need powerful tools to manage these
+ log statements.
+ </p>
+
<p>Logback can be configured either programmatically or with
- configuration a script (expressed in XML format). Here are the
- initialization steps that logback follows to try to configure
- itself:
+ configuration a script (expressed in XML format). By the way,
+ 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>Let us begin by discussing the initialization steps that
+ logback follows to try to configure itself:
</p>
<ol>
@@ -69,13 +83,16 @@
<li><p>In case neither file is found, logback configures itself
automatically using the <a
href="../xref/ch/qos/logback/classic/BasicConfigurator.html"><code>BasicConfigurator</code></a>
- which will cause output to be directed on the console. </a></p>
- </li>
+ which will cause logging output to be directed on the
+ console.
+ </p>
+ </li>
+
</ol>
<p>The third and last step is meant to provide a default (but very
- basic) logging functionnality in case no configuration file could
- be found.
+ basic) logging functionnality in the absence of a configuration
+ file.
</p>
@@ -84,7 +101,7 @@
won't be included in the artifact produced. Thus, you can use a
different configuration file, namely <em>logback-test.xml</em>
during testing, and another file, namely, <em>logback.xml</em>, in
- production. The same principle applies by analogy for Ant.
+ production. The same principle could apply by analogy for Ant.
</p>
@@ -115,61 +132,78 @@
}
}</pre></div>
- <p>Assuming the default configuration files
- <em>logback-test.xml</em> and <em>logback.xml</em> could not be
- found, logback will default to a minimal configuration hardwired
- to add a <code>ConsoleAppender</code> to the root logger. The
- output is formatted using a <code>PatternLayout</code> set to the
- pattern <em>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} -
+ <p>This class defines a static logger variable. It then
+ instantiates a Foo object. The Foo class is listed below:
+ </p>
+
+ <em>Example 3.2: Small class doing logging
+ <a href="../xref/chapter3/Foo.html">(logback-examples/src/main/java/chapter3/Foo.java)</a>
+ </em>
+
+<div class="source"><pre>package chapter3;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class Foo {
+ static final Logger logger = LoggerFactory.getLogger(Foo.class);
+
+ public void doIt() {
+ logger.debug("Did it again!");
+ }
+}</pre></div>
+
+
+
+ <p>In order to run the examples in this chapter, 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>
+
+
+ <p>Assuming the configuration files <em>logback-test.xml</em> or
+ <em>logback.xml</em> could not be found, logback will default to a
+ minimal configuration hardwired to attaching a
+ <code>ConsoleAppender</code> to the root logger. The output is
+ formatted using a <code>PatternLayout</code> set to the pattern
+ <em>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} -
%msg%n</em>. Moreover, by default the root logger is assigned to
the <code>DEBUG</code> level.
</p>
- <p>The output of the command <em>java chapter3.MyApp1</em> should
- be similar to:
+ <p>Thus, the output of the command <em>java chapter3.MyApp1</em>
+ should be similar to:
</p>
<div class="source"><pre>16:06:09.031 [main] INFO chapter3.MyApp1 - Entering application.
16:06:09.046 [main] DEBUG chapter3.Foo - Did it again!
16:06:09.046 [main] INFO chapter3.MyApp1 - Exiting application.</pre></div>
- <p>If you are unable to run this command, then make sure that you
- have set your classpath correctly. The scripts provided in the
- <em>logback-examples/</em> directory should help you get started.
- </p>
-
- <script src="../templates/setup.js"></script>
<p>The <code>MyApp1</code> application links to logback through
calls <code>org.slf4j.LoggerFactory</code> and
<code>org.slf4j.Logger</code> classes, retrieve the loggers it
- wishes to use, and chugs on. For example, the only dependence of
- the <code>Foo</code> class on logback are through
+ wishes to use, and chugs on. Note that the only dependence of the
+ <code>Foo</code> class on logback are through
<code>org.slf4j.LoggerFactory</code> and
<code>org.slf4j.Logger</code> imports. Except code that configures
- logback (if such code exists) user code does not need to depend on
- logback. Given that SLF4J permits the use of any implementation
+ logback (if such code exists) client code does not need to depend
+ on logback. Given that SLF4J permits the use of any implementation
under its abstraction layer, it is rather easy to migrate large
- bodies of code from an implementation to another. Logback also
- ships with a module called <em>log4j-bridge</em> which intercepts
- log4j calls and redirects them to the corresponding logback
- components. With the help of <em>log4j-bridge</em> , you can
- migrate an entire application using log4j to logback just by
- replacing jars. More information about the <em>log4j-bridge</em>
- module can be found on a <a href="../bridge.html">separate
- page</a>.
+ bodies of code from one logging system to another.
</p>
+
<h3>The same with <code>JoranConfigurator</code></h3>
<p>The previous example outputs logging information always in the
same fixed manner. How boring! It takes few easy steps to modify
<code>MyApp1</code> so that the log output can be controlled at
- runtime. Here is a slightly modified version called
+ runtime. Here is a slightly modified application called
<code>MyApp2</code>.
</p>
-<!-- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXxx -->
<p><em>Example 3.2: Simple example of
<code>BasicConfigurator</code> usage <a
@@ -235,6 +269,19 @@
</root>
</configuration></pre></div>
+
+ <p>The above configuration file directs logback to create an
+ <code>ConsoleAppender</code> named <em>STDOUT</em> whose output is
+ format is managed by a <code>PatternLayout</code>. The root logger
+ is configued by setting its level to DEBUG and attaching it the
+ previously created <code>ConsoleAppender</code>.
+ </p>
+
+ <p>Note we could have omitted setting the level of the root logger
+ to DEBUG because that is its default value.
+ </p>
+
+
<p>Assuming the current directory is <em>logback-examples</em>, try
running the <code>MyApp2</code> class by issuing the following
command:
@@ -279,11 +326,11 @@
</root>
</configuration></pre></div>
-<p>
-This should cause logback to print internal configuration messages in
-addition to the actual logs. Relaunching the <code>MyApp2</code> application with this
-new configuration file will ouput the following lines:
-</p>
+ <p>This should cause logback to print internal configuration
+ messages in addition to the actual logs. Relaunching the
+ <code>MyApp2</code> application with this new configuration file
+ will ouput the following lines:
+ </p>
<div class="source"><pre>|-INFO in ch.qos.logback.core.joran.action.AppenderAction - About to instantiate appender of type [ch. \
qos.logback.core.ConsoleAppender]
@@ -298,14 +345,26 @@
16:18:23.687 [main] DEBUG chapter3.Foo - Did it again!
16:18:23.687 [main] INFO chapter3.MyApp2 - Exiting application.</pre></div>
-<p>
-At the end of this output, one will immediately recognize the lines that were printed
-before. But right above stand the printing of logback's <code>Status</code> objects.
-<code>Status</code> objects are logback's powerful error reporting mechanism. They provide
-easy and precise access to logback's internal state.
-</p>
+ <p>At the end of this output, you can recognize the lines that were
+ printed in the previous example. You should also notive the
+ logback's internal messages based on <code>Status</code> objects,
+ logback internal reporting mechanism. <code>Status</code> objects
+ allow easy access to logback's internal state.
+ </p>
+
+ <h3>XML Syntax</h3>
+
+ <p>To obtain these different logging behaviors we do not need to
+ recompile code. You can easily configure logging so that output is
+ directed to a UNIX Syslog daemon, or to a log visualizer, or forward
+ 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>The remainder of this chapter presents the syntax of the
+ directives allowing all these variations.
+ </p>
-<h3>XML Syntax</h3>
<h4>Configuring Loggers</h4>
Modified: logback/trunk/logback-site/src/site/pages/manual/mdc.html
==============================================================================
--- logback/trunk/logback-site/src/site/pages/manual/mdc.html (original)
+++ logback/trunk/logback-site/src/site/pages/manual/mdc.html Tue Aug 21 17:44:53 2007
@@ -20,7 +20,7 @@
</div>
<div id="content">
- <h1>Chapter 7: Diagnostic Contexts</h1>
+ <h1>Chapter 7: Mapped Diagnostic Context</h1>
<div class="quote">
<p><em>Lock the doors.</em></p>
Modified: logback/trunk/logback-site/src/site/pages/news.html
==============================================================================
--- logback/trunk/logback-site/src/site/pages/news.html (original)
+++ logback/trunk/logback-site/src/site/pages/news.html Tue Aug 21 17:44:53 2007
@@ -28,6 +28,17 @@
<hr width="80%" align="center" />
+
+ <h3>20th of August 2007 - Release of version 0.9.8</h3>
+
+ <p>Fixed a number of documentation releated bugs, in particular <a
+ href="http://bugzilla.qos.ch/show_bug.cgi?id=90">bug 90</a> reported
+ by Luc Maisonobe.
+ </p>
+
+ <hr width="80%" align="center" />
+
+
<h3>29th of May 2007 - Release of version 0.9.7</h3>
More information about the logback-dev
mailing list