[logback-dev] svn commit: r1771 - logback/trunk/logback-site/src/site/pages/manual
noreply.ceki at qos.ch
noreply.ceki at qos.ch
Fri Aug 22 20:06:27 CEST 2008
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>
More information about the logback-dev
mailing list