Author: ceki Date: Fri Aug 22 20:06:27 2008 New Revision: 1771 Modified: logback/trunk/logback-site/src/site/pages/manual/architecture.html logback/trunk/logback-site/src/site/pages/manual/joran.html Log: - ongoing work on documentation 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 Fri Aug 22 20:06:27 2008 @@ -317,9 +317,8 @@ parent <code>X</code>, which has an assigned level. </p> - <a name="PrintintMethods"></a> - <a name="basic_selection"></a> - <h3>Printing methods</h3> + <h3><a name="basic_selection" href="#basic_selection">Printing + methods and the basic selection rule</a></h3> <p>By definition, the printing method determines the level of a logging request. For example, if <code>L</code> is a logger 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 Fri Aug 22 20:06:27 2008 @@ -487,8 +487,8 @@ <p>Setting the level of a logger or root logger is as simple as declaring it and setting its level, as the next example illustrates. Suppose we are no longer interested in seeing any DEBUG - level logs from any component belonging to the chapter3 package. The - following configuration file shows how to achieve that. + messages from any component belonging to the "chapter3" package. The + following configuration file shows how. </p> <em>Example 3.<span class="autoEx"/>: Setting the level of a logger (logback-examples/src/main/java/chapter3/sample2.xml)</em> @@ -500,13 +500,11 @@ </layout> </appender> - <b class="red"><logger name="chapter3" level="INFO"/></b> + <b><logger name="chapter3" level="INFO"/></b> - - <root> - <!-- The following level element is not necessary since the --> - <!-- level of the root level is set to DEBUG by default. --> - <level value="DEBUG" /> + <!-- Strictly speaking, the level attribute is not necessary since --> + <!-- the level of the root level is set to DEBUG by default. --> + <root level="DEBUG"> <appender-ref ref="STDOUT" /> </root> @@ -537,48 +535,40 @@ </layout> </appender> - <b><logger name="chapter3"> - <level value="INFO" /> - </logger> + <b><logger name="chapter3" level="INFO" /> + <logger name="chapter3.Foo" level="DEBUG" /></b> - <logger name="chapter3.Foo"> - <level value="DEBUG" /> - </logger></b> - - <root> - <!-- The following level element is not necessary since the --> - <!-- level of the root level is set to DEBUG by default. --> - <level value="DEBUG" /> + <root level="DEBUG"> <appender-ref ref="STDOUT" /> </root> </configuration></pre></div> -<p>Running <code>MyApp2</code> with this configuration file will -result in the following output on the console: -</p> + <p>Running <code>MyApp2</code> with this configuration file will + result in the following output on the console: + </p> <div class="source"><pre>17:39:27.593 [main] INFO chapter3.MyApp2 - Entering application. 17:39:27.593 [main] DEBUG chapter3.Foo - Did it again! 17:39:27.593 [main] INFO chapter3.MyApp2 - Exiting application.</pre></div> -<p> -After <code>JoranConfigurator</code> configures logback using the <em>sample3.xml</em> -file, the logger settings, more specifically their levels, are summarized in the following table. -</p> + <p>After <code>JoranConfigurator</code> configures logback using + the <em>sample3.xml</em> file, the logger settings, more + specifically their levels, are summarized in the following table. + </p> -<table> +<table class="bodyTable"> <tr> <th>Logger name</th> <th>Assigned Level</th> <th>Effective Level</th> </tr> - <tr> - <td>root</td> - <td><code>DEBUG</code></td> - <td><code>DEBUG</code></td> - </tr> - <tr> + <tr> + <td>root</td> + <td><code>DEBUG</code></td> + <td><code>DEBUG</code></td> + </tr> + <tr class="alt"> <td>chapter3</td> <td><code>INFO</code></td> <td><code>INFO</code></td> @@ -588,25 +578,27 @@ <td><code>null</code></td> <td><code>INFO</code></td> </tr> - <tr> + <tr class="alt"> <td>chapter3.Foo</td> <td><code>DEBUG</code></td> <td><code>DEBUG</code></td> </tr> </table> -<p>It follows that the two logging statements of level -<code>INFO</code> in the <code>MyApp2</code> class are enabled while -the <code>debug</code> statement in <code>Foo.doIt()</code> method -will also print without hindrance. Note that the level of the root -logger is always set to a non-null value, which is <code>DEBUG</code> -by default. One rather important point to remember is that the -logger-level filter depends on the effective level of the logger being -invoked, not the level of the logger where the appenders are -attached. The configuration file <em>sample4.xml</em> is a case in -point: -</p> -<em>Example 3.<span class="autoEx"/>: Logger level sample (logback-examples/src/main/java/chapter3/sample4.xml)</em> + <p>It follows that the two logging statements of level + <code>INFO</code> in the <code>MyApp2</code> class as well as the + DEBUG messages in <code>Foo.doIt()</code> are all enabled. Note that + the level of the root logger is always set to a non-null value, + which is DEBUG by default. One rather important point to remember + is that the <a + href="architecture.html#basic_selection">basic-selection rule</a> + depends on the effective level of the logger being invoked, not the + level of the logger where appenders are attached. The configuration + file <em>sample4.xml</em> is a case in point: + </p> + + <em>Example 3.<span class="autoEx"/>: Logger level sample + (logback-examples/src/main/java/chapter3/sample4.xml)</em> <div class="source"><pre><configuration> <appender name="STDOUT" @@ -618,81 +610,78 @@ </layout> </appender> - <b><logger name="chapter3"> - <level value="INFO" /> - </logger></b> + <b><logger name="chapter3" level="INFO" /></b> - <root> - <b><level value="OFF" /></b> + <root <b>level="OFF"</b>> <appender-ref ref="STDOUT" /> </root> </configuration></pre></div> -<p> -The following table lists the loggers and their level setting after applying the -<em>sample4.xml</em> configuration file. -</p> - -<table> - <tr> - <th>Logger name</th> - <th>Assigned Level</th> - <th>Effective Level</th> - </tr> - <tr> - <td>root</td> - <td><code>OFF</code></td> - <td><code>OFF</code></td> - </tr> - <tr> - <td>chapter3</td> - <td><code>INFO</code></td> - <td><code>INFO</code></td> - </tr> - <tr> - <td>chapter3.MyApp2</td> - <td><code>null</code></td> - <td><code>INFO</code></td> - </tr> - <tr> - <td>chapter3.Foo</td> - <td><code>null</code></td> - <td><code>INFO</code></td> - </tr> -</table> - -<p>The ConsoleAppender named <em>STDOUT</em>, the only configured -appender in <em>sample4.xml</em>, is attached to the root logger whose -level is set to <code>OFF</code>. However, running MyApp2 with -configuration script <em>sample4.xml</em> will output: -</p> - -<div class="source"><pre>17:52:23.609 [main] INFO chapter3.MyApp2 - Entering application. -17:52:23.609 [main] INFO chapter3.MyApp2 - Exiting application.</pre></div> - -<p>Thus, the level of the root logger has no apparent effect because -the loggers in <code>chapter3.MyApp2</code> and -<code>chapter3.Foo</code> classes, namely <em>chapter3.MyApp2</em> and -<em>chapter3.Foo</em>, inherit their level from the <em>chapter3</em> -logger which has its level set to <code>INFO</code>. As noted -previously, the <em>chapter3</em> logger exists by virtue of its -declaration in the configuration file - even if the Java source code -does not directly refer to it. -</p> - -<h4>Configuring Appenders</h4> + <p>The following table lists the loggers and their level setting + after applying the <em>sample4.xml</em> configuration file. + </p> -<p> -Appenders are configured using <em>appender</em> elements. These elements admit -two attributes <em>name</em> and <em>class</em> both of which are mandatory. -The <em>name</em> attribute specifies the name of the appender whereas -the <em>class</em> attribute specifies the fully qualified name of the class -of which the named appender will be an instance. -The <em>appender</em> may contain zero or one <em>layout</em> elements and -zero or more <em>filter</em> elements. Appart from these two basic elements, -<em>appender</em> elements may contain any element that corresponds to a setter -method of the appender class, to configure the appender's options. + <table class="bodyTable"> + <tr> + <th>Logger name</th> + <th>Assigned Level</th> + <th>Effective Level</th> + </tr> + <tr> + <td>root</td> + <td><code>OFF</code></td> + <td><code>OFF</code></td> + </tr> + <tr class="alt"> + <td>chapter3</td> + <td><code>INFO</code></td> + <td><code>INFO</code></td> + </tr> + <tr> + <td>chapter3.MyApp2</td> + <td><code>null</code></td> + <td><code>INFO</code></td> + </tr> + <tr class="alt"> + <td>chapter3.Foo</td> + <td><code>null</code></td> + <td><code>INFO</code></td> + </tr> + </table> + + <p>The ConsoleAppender named <em>STDOUT</em>, the only configured + appender in <em>sample4.xml</em>, is attached to the root logger + whose level is set to <code>OFF</code>. However, running MyApp2 with + configuration script <em>sample4.xml</em> will output: + </p> + + <div class="source"><pre>17:52:23.609 [main] INFO chapter3.MyApp2 - +Entering application. 17:52:23.609 [main] INFO chapter3.MyApp2 - +Exiting application.</pre></div> + + <p>Thus, the level of the root logger has no apparent effect because + the loggers in <code>chapter3.MyApp2</code> and + <code>chapter3.Foo</code> classes, namely <em>chapter3.MyApp2</em> + and <em>chapter3.Foo</em>, inherit their level from the + <em>chapter3</em> logger which has its level set to + <code>INFO</code>. As noted previously, the <em>chapter3</em> + logger exists by virtue of its declaration in the configuration file + - even if the Java source code does not directly refer to it. + </p> + + <h4>Configuring Appenders</h4> + + <p>Appenders are configured using <em>appender</em> elements. These + elements admit two attributes <em>name</em> and <em>class</em> both + of which are mandatory. The <em>name</em> attribute specifies the + name of the appender whereas the <em>class</em> attribute specifies + the fully qualified name of the class of which the named appender + will be an instance. The <em>appender</em> may contain zero or one + <em>layout</em> elements and zero or more <em>filter</em> + elements. Appart from these two basic elements, <em>appender</em> + elements may contain any element that corresponds to a setter method + of the appender class, to configure the appender's options. </p> <p>