[LOGBack-dev] svn commit: r365 - logback/classic/trunk/src/site/xdocTemplates
noreply.ceki at qos.ch
noreply.ceki at qos.ch
Thu Jul 27 22:47:18 CEST 2006
Author: ceki
Date: Thu Jul 27 22:47:17 2006
New Revision: 365
Modified:
logback/classic/trunk/src/site/xdocTemplates/shortIntro.xml
Log:
- The introduction section and the architecture repeat the same text. (I did not have time to perform the clean up.)
- Changed "source" style to use the 'white-space: pre;' style. It's much more convenient than
having to format source code manually.
- In the short manual, use the letter L instead of C in logger related rules.
- removed 3 paragraphs discussing object rendering as this concept is not implemented in LB.
- performed many indentation related changes.
Modified: logback/classic/trunk/src/site/xdocTemplates/shortIntro.xml
==============================================================================
--- logback/classic/trunk/src/site/xdocTemplates/shortIntro.xml (original)
+++ logback/classic/trunk/src/site/xdocTemplates/shortIntro.xml Thu Jul 27 22:47:17 2006
@@ -10,9 +10,9 @@
<table>
<tr>
- <td>
+ <td valign="top" align="top">
<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/2.5/">
- <img alt="Creative Commons License" border="0" valign="top"
+ <img alt="Creative Commons License" border="0" valign="top" align="top"
src="http://creativecommons.org/images/public/somerights20.png"/>
</a>
</td>
@@ -108,7 +108,7 @@
messages are formatted and where they are reported.
</p>
<p>
- The Loggers are defined in the classic module. On the other
+ Loggers are defined in the classic module. On the other
hand, Appenders and Layouts are defined in the core module
of logback.
</p>
@@ -141,17 +141,11 @@
</div>
<p>
- For example, the logger named
- <code>"com.foo"</code>
- is a parent of the logger named
- <code>"com.foo.Bar"</code>
- . Similarly,
- <code>"java"</code>
- is a parent of
- <code>"java.util"</code>
- and an ancestor of
- <code>"java.util.Vector"</code>
- . This naming scheme should be familiar to most developers.
+ For example, the logger named <code>"com.foo"</code> is a parent
+ of the logger named <code>"com.foo.Bar"</code> . Similarly,
+ <code>"java"</code> is a parent of <code>"java.util"</code> and
+ an ancestor of <code>"java.util.Vector"</code> . This naming
+ scheme should be familiar to most developers.
</p>
<p>
The root logger resides at the top of the logger hierarchy.
@@ -161,44 +155,36 @@
<li>it always exists,</li>
<li>it cannot be retrieved by name.</li>
</ol>
- All other loggers are retrieved with the class static
+
+ <p>All other loggers are retrieved with the class static
LoggerFactory.getLogger method. This method takes the name of
the desired logger as a parameter. Some of the basic methods in
the Logger interface are listed below.
- <div class="source">
- <p>package org.slf4j;</p>
+ </p>
- <p>public interface Logger {</p>
- <p>
- // Creation and retrieval method:
- <br />
- public static Logger getLogger(String name);
- <br />
- </p>
- <p>
- // printing methods:
- <br />
- public void debug(Object message);
- <br />
- public void info(Object message);
- <br />
- public void warn(Object message);
- <br />
- public void error(Object message);
- <br />
- public void fatal(Object message);
- <br />
- </p>
- <p>}</p>
- </div>
- <p>
- Loggers may be assigned levels. The set of possible levels,
- that is DEBUG, INFO, WARN, ERROR and FATAL are defined in
- the org.apache.log4j.Level class. Although we do not
- encourage you to do so, you may define your own levels by
- sub-classing the Level class. A perhaps better approach will
- be explained later on.
+ <div class="source">package org.slf4j;
+
+public interface Logger {
+
+ // Creation and retrieval method:
+ public static Logger getLogger(String name);
+
+ // printing methods:
+ public void debug(Object message);
+ public void info(Object message);
+ public void warn(Object message);
+ public void error(Object message);
+ public void fatal(Object message);
+}</div>
+
+ <p>
+ Loggers may be assigned levels. The set of possible levels, that
+ is DEBUG, INFO, WARN and ERROR are defined in the
+ org.apache.log4j.Level class. The level class cannot be
+ sub-classed as a much better approach exist in the form of
+ Marker 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
@@ -208,10 +194,10 @@
<div class="definition">
<div class="deftitle">Level Inheritance</div>
<p>
- The inherited level for a given logger C, is equal to
- the first non-null level in the logger hierarchy,
- starting at C and proceeding upwards in the hierarchy
- towards the root logger.
+ The inherited level for a given logger <em>L</em>, is equal to
+ the first non-null level in the logger hierarchy, starting at
+ <em>L</em> and proceeding upwards in the hierarchy towards the
+ root logger.
</p>
</div>
<p>
@@ -426,22 +412,13 @@
</table>
<p>
- In example 4, the loggers
- <code>root</code>
- and
- <code>X</code>
- and are assigned the levels
- <code>Proot</code>
- and
+ In example 4, the loggers <code>root</code> and <code>X</code>
+ and are assigned the levels <code>Proot</code> and
<code>Px</code>
- respectively. The loggers
- <code>X.Y</code>
- and
- <code>X.Y.Z</code>
- inherits their level value from their nearest parent
- <code>X</code>
- having an assigned level.
+ respectively. The loggers <code>X.Y</code> and
+ <code>X.Y.Z</code> inherits their level value from their nearest
+ parent <code>X</code> having an assigned level.
</p>
<p>
@@ -452,20 +429,16 @@
<p>
By definition, the printing method determines the level of a
- logging request. For example, if
- <code>c</code>
- is a logger instance, then the statement
- <code>c.info("..")</code>
- is a logging request of level INFO.
+ logging request. For example, if <code>c</code> is a logger
+ instance, then the statement <code>c.info("..")</code> is a
+ logging request 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 hierarchy. This rule is summarized below.
+ 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 hierarchy. This rule is
+ summarized below.
</p>
<div class="definition">
<div class="deftitle">Basic Selection Rule</div>
@@ -491,74 +464,25 @@
</p>
<p>Here is an example of this rule.</p>
- <div class="source">
- <p>
- // get a logger instance named "com.foo", with an
- <span class="blue">INFO</span>
- level.
- <br />
- Logger logger = LoggerFactory.getLogger("com.foo");
- <br />
- </p>
- <p>
- Logger barlogger =
- LoggerFactory.getLogger("com.foo.Bar");
- <br />
- </p>
- <p>
- // This request is enabled, because
- <span class="green">WARN</span>
- >=
- <span class="blue">INFO</span>
- .
- <br />
- logger.
- <span class="green">warn</span>
- ("Low fuel level.");
- <br />
- </p>
- <p>
- // This request is disabled, because
- <span class="green">DEBUG</span>
- <
- <span class="blue">INFO</span>
- .
- <br />
- logger.
- <span class="green">debug</span>
- ("Starting search for nearest gas station.");
- <br />
- </p>
- <p>
- // The logger instance barlogger, named "com.foo.Bar",
- <br />
- // will inherit its level from the logger named
- <br />
- // "com.foo" Thus, the following request is enabled
- <br />
- // because
- <span class="green">INFO</span>
- >=
- <span class="blue">INFO</span>
- .
- <br />
- barlogger.
- <span class="green">info</span>
- ("Located nearest gas station.");
- <br />
- </p>
- <p>
- // This request is disabled, because
- <span class="green">DEBUG</span>
- <
- <span class="blue">INFO</span>
- .
- <br />
- barlogger.
- <span class="green">debug</span>
- ("Exiting gas station search");
- <br />
- </p>
+ <div class="source">// get a logger instance named "com.foo", with an <span class="blue">INFO</span> level.
+ Logger logger = LoggerFactory.getLogger("com.foo");
+
+ Logger barlogger = LoggerFactory.getLogger("com.foo.Bar");
+
+ // This request is enabled, because <span class="green">WARN</span> >= <span class="blue">INFO</span>
+ logger.<span class="green">warn</span>("Low fuel level.");
+
+
+ // This request is disabled, because <span class="green">DEBUG</span> < <span class="blue">INFO</span>.
+ logger.<span class="green">debug</span>("Starting search for nearest gas station.");
+ // The logger instance barlogger, named "com.foo.Bar",
+ // will inherit its level from the logger named
+ // "com.foo" Thus, the following request is enabled
+ // because <span class="green">INFO</span> >= <span class="blue">INFO</span>.
+ barlogger.<span class="green">info</span>("Located nearest gas station.");
+
+ // This request is disabled, because <span class="green">DEBUG</span> < <span class="blue">INFO</span>.
+ barlogger.<span class="green">debug</span>("Exiting gas station search");
</div>
<p>
@@ -567,29 +491,23 @@
method with the same name will always return a reference to
the exact same logger object.
</p>
+
<p>For example, in</p>
- <div class="source">
- Logger x = LoggerFactory.getLogger("wombat");
- <br />
- Logger y = LoggerFactory.getLogger("wombat");
- </div>
- <code>x</code>
- and
- <code>y</code>
- refer to
- <em>exactly</em>
- the same logger object.
+ <div class="source">Logger x = LoggerFactory.getLogger("wombat");
+Logger y = LoggerFactory.getLogger("wombat");</div>
+ <p><code>x</code> and <code>y</code> refer to <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 classic 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.
+ 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
+ classic 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
@@ -598,18 +516,16 @@
discussed shortly.
</p>
<p>
- Logback makes it easy to name loggers by
- <em>software component</em>
- . This can be accomplished by statically 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 as desired.
+ Logback makes it easy to name loggers by <em>software
+ component</em>. This can be accomplished by statically
+ 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 as desired.
</p>
<p>
Nevertheless, naming loggers after the class where they are
@@ -619,65 +535,57 @@
<div class="section">
<h3>Appenders and Layouts</h3>
</div>
- <p>
- The ability to selectively enable or disable logging
- requests based on their logger is only part of the picture.
- Log4j allows logging requests to print to multiple
- destinations. In log4j speak, an output destination is
- called an appender. Currently, appenders exist for the
- console, files, GUI components, remote socket servers, JMS,
- NT Event Loggers, and remote UNIX Syslog daemons. It is also
- possible to log asynchronously.
+
+ <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.
</p>
+
<p>More than one appender can be attached to a logger.</p>
<p>
- The addAppender 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 C, then enabled logging requests for C and C's
- children will print on a file and 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.
+ The addAppender 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 and 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>
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>C</em>
- will go to all the appenders in
- <em>C</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>C</em>
- , say
- <em>P</em>
- , has the additivity flag set to false, then
- <em>C</em>
- 's output will be directed to all the appenders in
- <em>C</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.
+ Loggers have their additivity flag set to true by default.
</p>
+
</div>
The table below shows an example:
@@ -749,19 +657,17 @@
<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 PatternLayout, part of the standard
- log4j distribution, lets the user specify the output format
- according to conversion patterns similar to the C language
- <code>printf</code>
- function.
+ 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 PatternLayout, 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
"%r [%t] %-5p %c - %m%n" will output something akin to:
@@ -779,89 +685,50 @@
associated with the log request. The text after the '-' is
the message of the statement.
</p>
- <p>
- Just as importantly, log4j will render the content of the
- log message according to user specified criteria. For
- example, if you frequently need to log
- <code>Oranges</code>
- , an object type used in your current project, then you can
- register an
- <code>OrangeRenderer</code>
- that will be invoked whenever an orange needs to be logged.
- </p>
- <p>
- Object rendering follows the class hierarchy. For example,
- assuming oranges are fruits, if you register an
- <code>FruitRenderer</code>
- , all fruits including oranges will be rendered by the
- <code>FruitRenderer</code>
- , unless of course you registered an orange specific
- <code>OrangeRenderer</code>
- .
- </p>
- <p>
- Object renderers have to implement the ObjectRenderer
- interface.
- </p>
<h4>More sophitsicated ways of logging</h4>
<p>
If you are a SLF4J user (if not, you should be...), you'll
- notice that the methods used to request logging do not only
- take a String as a parameter. Some methods allow more
- sophisticated parameter configurations.
+ notice that the methods used to request logging do not only take
+ a String as a parameter. Some methods allow more sophisticated
+ parameter configurations.
</p>
- <p>
- For some Logger
- <code>logger</code>
- , writing,
- </p>
+ <p> For some Logger <code>logger</code>, writing, </p>
+
<div class="source">
- logger.debug("Entry number: " + i + " is " +
- String.valueOf(entry[i]));
+ logger.debug("Entry number: " + i + " is " +
+ String.valueOf(entry[i]));
</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
+ 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">
- if(logger.isDebugEnabled()) {
- <br />
- logger.debug("Entry number: " + i + " is " +
- String.valueOf(entry[i]));
- <br />
- }
- </div>
+if(logger.isDebugEnabled()) {
+ logger.debug("Entry number: " + i + " is " +
+ String.valueOf(entry[i]));
+} </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 statement.
+ <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 statement.
</p>
<h4>Better alternative based on format messages</h4>
More information about the logback-dev
mailing list