Author: ceki Date: Sat Aug 9 23:42:09 2008 New Revision: 1752 Modified: logback/trunk/logback-site/src/site/pages/css/site.css logback/trunk/logback-site/src/site/pages/documentation.html logback/trunk/logback-site/src/site/pages/download.html logback/trunk/logback-site/src/site/pages/manual/architecture.html logback/trunk/logback-site/src/site/pages/templates/right.js Log: - improving the docs Modified: logback/trunk/logback-site/src/site/pages/css/site.css ============================================================================== --- logback/trunk/logback-site/src/site/pages/css/site.css (original) +++ logback/trunk/logback-site/src/site/pages/css/site.css Sat Aug 9 23:42:09 2008 @@ -226,6 +226,10 @@ background-color: #eee; } +table.bodyTable tr.alt { + background-color: #eee; +} + .author { text-align: left; font-weight: bold; Modified: logback/trunk/logback-site/src/site/pages/documentation.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/documentation.html (original) +++ logback/trunk/logback-site/src/site/pages/documentation.html Sat Aug 9 23:42:09 2008 @@ -38,11 +38,7 @@ <li> <a href="dependencies.html">Dependencies per module</a> </li> - - - <li> - <a href="bridge.html">How to use the log4j bridge</a> - </li> + <li> <a href="jmxConfig.html">How to use the logback JMX Configurator</a> </li> Modified: logback/trunk/logback-site/src/site/pages/download.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/download.html (original) +++ logback/trunk/logback-site/src/site/pages/download.html Sat Aug 9 23:42:09 2008 @@ -84,7 +84,7 @@ </dt> <dd> - <p>Lilith is a Logging- and AccessEvent viewer for LOGBack. + <p>Lilith is a Logging- and AccessEvent viewer for logback. </p> </dd> 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 Sat Aug 9 23:42:09 2008 @@ -46,35 +46,35 @@ </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>. + 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 java.util.logging (JUL) introduced in JDK + 1.4. 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>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>Logback is built upon three main classes: <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>The <code>Logger</code> class is part of the logback-classic + module. On the other hand, the <code>Appender</code> and + <code>Layout</code> interfaces are part of logback-core. As a + general-purpose module, logback-core has no notion of loggers. </p> <a name="LoggerContext"></a> @@ -85,8 +85,8 @@ 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. + according to some developer-chosen criteria. In logback-classic, + this categorization is an inherent part of loggers. </p> <p> @@ -140,27 +140,24 @@ 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>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 <code>Marker</code> + 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>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>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> @@ -178,34 +175,27 @@ <em>Example 1</em> <table class="bodyTable"> <tr> - <th> - Logger name - </th> - <th> - Assigned level - </th> - - <th> - Effective level - </th> + <th>Logger name</th> + <th>Assigned level</th> + <th>Effective level</th> </tr> - <tr class="a"> + <tr class="alt"> <td>root</td> <td>DEBUG</td> <td>DEBUG</td> </tr> - <tr class="b"> + <tr> <td>X</td> <td>none</td> <td>DEBUG</td> </tr> - <tr class="a"> + <tr class="alt"> <td>X.Y</td> <td>none</td> <td>DEBUG</td> </tr> - <tr class="b"> + <tr> <td>X.Y.Z</td> <td>none</td> <td>DEBUG</td> @@ -218,20 +208,13 @@ </p> <em>Example 2</em> - <table> + <table class="bodyTable"> <tr> - <th> - Logger name - </th> - <th> - Assigned level - </th> - - <th> - Effective level - </th> + <th>Logger name</th> + <th>Assigned level</th> + <th>Effective level</th> </tr> - <tr align="left"> + <tr class="alt" align="left"> <td>root</td> <td>ERROR</td> <td>ERROR</td> @@ -242,7 +225,7 @@ <td>INFO</td> </tr> - <tr align="left"> + <tr class="alt" align="left"> <td>X.Y</td> <td>DEBUG</td> <td>DEBUG</td> @@ -259,19 +242,13 @@ </p> <em>Example 3</em> - <table> + <table class="bodyTable"> <tr> - <th> - Logger name - </th> - <th> - Assigned level - </th> - <th> - Effective level - </th> + <th>Logger name</th> + <th>Assigned level</th> + <th>Effective level</th> </tr> - <tr align="left"> + <tr class="alt" align="left"> <td>root</td> <td>DEBUG</td> <td>DEBUG</td> @@ -282,7 +259,7 @@ <td>INFO</td> <td>INFO</td> </tr> - <tr align="left"> + <tr class="alt" align="left"> <td>X.Y</td> <td>none</td> <td>INFO</td> @@ -293,28 +270,23 @@ <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>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> + <table class="bodyTable"> <tr> - <th> - Logger name - </th> - <th> - Assigned level - </th> - <th> - Effective level - </th> + <th>Logger name</th> + <th>Assigned level</th> + <th>Effective level</th> </tr> - <tr align="left"> + <tr class="alt" align="left"> <td>root</td> <td>DEBUG</td> <td>DEBUG</td> @@ -325,7 +297,7 @@ <td>INFO</td> <td>INFO</td> </tr> - <tr align="left"> + <tr class="alt" align="left"> <td>X.Y</td> <td>none</td> <td>INFO</td> @@ -346,6 +318,7 @@ </p> <a name="PrintintMethods"></a> + <a name="basic_selection"></a> <h3>Printing methods</h3> <p>By definition, the printing method determines the level of a @@ -354,25 +327,27 @@ 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. + is higher than or equal to the effective level of its + logger. Otherwise, the request is said to be <em>disabled</em>. As + described previously, a logger without an assigned level will + inherit one from its nearest ancestor. 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>A log request of level <em>p</em> issued with a logger having + 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>This rule is at the heart of logback. It assumes that levels + are ordered as follows: <code>DEBUG < INFO < WARN < + ERROR</code>. </p> <p>In a more graphic way, here is how the selection rule works. In @@ -427,7 +402,7 @@ <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. + <div class="source"><pre>// get a logger instance named "com.foo" Logger logger = LoggerFactory.getLogger("com.foo"); //set its Level to <span class="blue">INFO</span> logger.setLevel(Level. <span class="blue">INFO</span>); @@ -465,34 +440,28 @@ <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>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 @@ -502,62 +471,54 @@ <a name="AppendersAndLayouts"></a> <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>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. <!--It is also possible to log asynchronously. --> </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>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>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>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>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>Loggers have their additivity flag set to true by default. </p> </div> @@ -581,7 +542,7 @@ hiearchy, the additivity flag does not apply to it. </td> </tr> - <tr> + <tr class="alt"> <td>x</td> <td>A-x1, A-x2</td> <td>true</td> @@ -595,7 +556,7 @@ <td>A1, A-x1, A-x2</td> <td>Appenders of "x" and of root.</td> </tr> - <tr> + <tr class="alt"> <td>x.y.z</td> <td>A-xyz1</td> <td>true</td> @@ -613,7 +574,7 @@ <code>false</code>. Only appender A-sec will be used. </td> </tr> - <tr> + <tr class="alt"> <td>security.access</td> <td>none</td> <td>true</td> @@ -627,65 +588,55 @@ </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>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>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>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> <a name="ParametrizedLogging"></a> <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>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> + <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>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>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()) { @@ -693,55 +644,46 @@ }</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>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>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>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>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>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> @@ -781,7 +723,8 @@ to step 3. </p> - <h4>2. Apply the Logger level filter</h4> + <h4>2. Apply the <a href="#basic_selection">basic selection + rule</a></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 Modified: logback/trunk/logback-site/src/site/pages/templates/right.js ============================================================================== --- logback/trunk/logback-site/src/site/pages/templates/right.js (original) +++ logback/trunk/logback-site/src/site/pages/templates/right.js Sat Aug 9 23:42:09 2008 @@ -1,13 +1,10 @@ - //document.write('<p class="menu"><a href="'+prefix+'10reasons.ppt">10 reasons for migrating</a>') document.write('<p class="menu_header">New and noteworthy</p>') -document.write('<p class="menu"><a href="http://wizardforge.org/pc?action=showVersion&id=72">Configuration Wizard</a>') - -http://wizardforge.org/pc?action=showVersion&id=72 +document.write('<p class="menu"><a href="http://stubbisms.wordpress.com/2008/07/15/some-serious-logging-niceness-logback-with-eclipse-plugin/">Logging niceness</a>') -document.write('<p class="menu"><a href="http://www.javadonkey.com/blog/log4j-isdebugenabled-logback/">isDebugEnabled()</a>') +document.write('<p class="menu"><a href="http://wizardforge.org/pc?action=showVersion&id=72">Configuration Wizard</a>') document.write('<p class="menu"><a href="http://xhab.blogspot.com/2007/03/new-logging-experience.html">A new logging experience!</a>')