Author: ceki
Date: Mon Nov 13 21:03:28 2006
New Revision: 908
Modified:
logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml
Log:
Ongoing work on the intro.
Modified: logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml
==============================================================================
--- logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml
(original)
+++ logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml Mon Nov
13 21:03:28 2006
@@ -406,20 +406,14 @@
<table>
<tr>
<th>
- Logger
- <br />
- name
+ Logger name
</th>
<th>
- Assigned
- <br />
- level
+ Assigned level
</th>
<th>
- Effective
- <br />
- level
+ Effective level
</th>
</tr>
<tr>
@@ -444,30 +438,24 @@
<td>DEBUG</td>
</tr>
</table>
- <p>
- In example 1 above, only the root logger is assigned a
- level.
- This level value, <code>DEBUG</code>, is inherited by the other
loggers
- <code>X</code>, <code>X.Y</code> and <code>X.Y.Z</code>
+
+ <p> In example 1 above, only the root logger is assigned a
level.
+ This level value, <code>DEBUG</code>, is inherited by the other
+ loggers <code>X</code>, <code>X.Y</code> and <code>X.Y.Z</code>
</p>
+
<em>Example 2</em>
<table>
<tr>
<th>
- Logger
- <br />
- name
+ Logger name
</th>
<th>
- Assigned
- <br />
- level
+ Assigned level
</th>
<th>
- Effective
- <br />
- level
+ Effective level
</th>
</tr>
<tr align="left">
@@ -493,28 +481,21 @@
</tr>
</table>
- <p>
- In example 2 above, all loggers have an assigned level
value.
- There is no need for level inheritence.
+ <p>In example 2 above, all loggers have an assigned level value.
+ There is no need for level inheritence.
</p>
<em>Example 3</em>
<table>
<tr>
<th>
- Logger
- <br />
- name
+ Logger name
</th>
<th>
- Assigned
- <br />
- level
+ Assigned level
</th>
<th>
- Effective
- <br />
- level
+ Effective level
</th>
</tr>
<tr align="left">
@@ -551,19 +532,13 @@
<tr>
<th>
- Logger
- <br />
- name
+ Logger name
</th>
<th>
- Assigned
- <br />
- level
+ Assigned level
</th>
<th>
- Effective
- <br />
- level
+ Effective level
</th>
</tr>
<tr align="left">
@@ -589,8 +564,7 @@
</tr>
</table>
- <!-- ========= CEKI: STOPPED HERE =================== -->
-
+
<p>In example 4 above, the loggers <code>root</code> and
<code>X</code> and are assigned the levels <code>DEBUG</code>
and
<code>INFO</code> respectively. The loggers <code>X.Y</code> and
@@ -627,7 +601,7 @@
<code>DEBUG < INFO < WARN < ERROR</code>.
</p>
- <p>In a more graphic way, here is how the selection rule works:
in
+ <p>In a more graphic way, here is how the selection rule works.
In
the following table, the vertical header shows the the level of
the logging request, designated by <em>p</em>, while the
horizontal header shows effective level of the logger,
designated
@@ -728,51 +702,52 @@
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. The developer is free to name
the
- loggers she desires.
+ 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
- located seems to be the best strategy known so far.
+
+ <p>Nevertheless, naming loggers after the class where they are
+ located seems to be the best strategy known so far.
</p>
<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, JMS, and remote
UNIX
- Syslog daemons. It is also possible to log
asynchronously.
+ 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, to 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>addAppender</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 context. In other words,
appenders
- are inherited additively from the logger context. 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 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 context. In other words, appenders
are
+ inherited additively from the logger context. 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
+ to false.
</p>
<p>
@@ -810,7 +785,7 @@
<table class="bodyTable">
<tr>
<th>Logger Name</th>
- <th>Added Appenders</th>
+ <th>Attached Appenders</th>
<th>Additivity Flag</th>
<th>Output Targets</th>
<th>Comment</th>
@@ -820,10 +795,9 @@
<td>A1</td>
<td>not applicable</td>
<td>A1</td>
- <td>
- The root logger can be accessed
- with the
LoggerFactory.getLogger("root") method. There is no
- default appender attached to root.
+
+ <td>Since the root logger stands at the top of
the logger
+ hiearchy, the additivity flag does not apply to
it.
</td>
</tr>
<tr>
@@ -850,18 +824,19 @@
<tr>
<td>security</td>
<td>A-sec</td>
- <td class="blue">false</td>
+ <td class="blue"><span
class="blue">false</span></td>
<td>A-sec</td>
+
<td>
- No appender accumulation since the
additivity flag
- is set to
+ No appender accumulation since the
additivity flag is set to
<code>false</code>. Only appender A-sec
will be used.
</td>
</tr>
<tr>
<td>security.access</td>
<td>none</td>
- <td>true</td>
<td>A-sec</td>
+ <td>true</td>
+ <td>A-sec</td>
<td>
Only appenders of "security" because
the additivity
flag in "security" is set to
@@ -887,7 +862,7 @@
<p>
For example, the PatternLayout with the conversion
pattern
- "%-4relative [%thread] %-5level %class - %msg%n" will
output something akin to:
+ "%-4relative [%thread] %-5level %logger{32} - %msg%n"
will output something akin to:
</p>
<div class="source"><pre>176 [main] DEBUG chapter1.HelloWorld3
- Hello world.</pre></div>
@@ -901,12 +876,15 @@
the message of the statement.
</p>
- <h4>Parametrized logging</h4>
+ <h3>Parameterized logging</h3>
<p>
- If you are a SLF4J user, you'll
- notice that the methods used to request logging do not
only
- take a String as a parameter. Some methods accept
further parameters.
+ 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>
@@ -945,6 +923,8 @@
log a statement.
</p>
+<!-- ========= CEKI: STOPPED HERE =================== -->
+
<h4>Better alternative</h4>
<p>
@@ -957,12 +937,11 @@
logger.debug("The entry is {}.", entry);</pre></div>
<p>
- After evaluting whether to log or not, and only if the
- decision is affirmative, 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
+ 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>
@@ -997,27 +976,29 @@
<h3>Configuration</h3>
<p>
- Inserting log requests into the application code
requires
- a fair amount of planning and effort. Observation shows
that
- approximately 4 percent of code is dedicated to
logging. Consequently,
- even moderately sized applications will have thousands
of logging
- statements embedded within their code. Given their
number, it becomes
- imperative to manage these log statements without the
need to
- modify them manually.
- </p>
- <p>
- The logback environment is fully configurable
programmatically.
- However, it is far more flexible to configure logback
using
- configuration files. In logback, configuration files
must be written in
- XML format.
- </p>
- <p>
- Log4j users can convert their
<code>log4j.properties</code> files to logback xml configration files using
- our <a
href="http://logback.qos.ch/translator/";>PropertiesTranslator</a> webapp.
+ 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>
+ <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
+ expressed in XML.
+ </p>
+ <p>
+ Existing log4j users can convert their
<em>log4j.properties</em>
+ files to <em>logback.xml</em> using <a
+
href="http://logback.qos.ch/translator/";>PropertiesTranslator</a>
+ web-application.
</p>
<p>
Let us give a taste of how logback configuration is
done with the help of an
- imaginary application MyApp that uses logback.
+ imaginary application <em>MyApp</em> that uses logback.
</p>
<em>Example 1.4: Basic configuration
(logback-examples/src/main/java/chapter1/MyApp.java)</em>
<div class="source"><pre>package chapter1;
_______________________________________________
logback-dev mailing list
[email protected]
http://qos.ch/mailman/listinfo/logback-dev
