<document>
	<!-- 
	
		Warning: do not use any auto-format function on this file.
		Since "source" divs use pre as white-space, it affects the
		look of the code parts in this document.
	
	 -->


	<body>
    <h2>Chapter 2: Architecture</h2>
    <div class="author">
    	Authors: Ceki G&#252;lc&#252;, S&#233;bastien Pennec
    </div>


		<table>
			<tr>
				<td valign="top" align="top">
						<a rel="license"
							href="http://creativecommons.org/licenses/by-nc-sa/2.5/">
							<img alt="Creative Commons License"
								style="border-width: 0"
								src="http://creativecommons.org/images/public/somerights20.png" />
						</a>
				</td>
				<td>
					<p>Copyright &#169; 2000-2006, QOS.ch</p>

					<p>
						<!--Creative Commons License-->
						This work is licensed under a
						<a rel="license"
							href="http://creativecommons.org/licenses/by-nc-sa/2.5/">
							Creative Commons
							Attribution-NonCommercial-ShareAlike 2.5
							License
						</a>
						.
						<!--/Creative Commons License-->
					</p>
				</td>
			</tr>
		</table>


    <h2>Logback architecture</h2>

    <p>
    	Logback's basic architecture is sufficiently generic so as to
    	apply under different circumstances. At present time, logback is
    	divided into three modules, Core, Classic and Access.
    </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>.
    </p>
    <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>
		<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>
    
    <a name="LoggerContext" />
    <h3>Logger context</h3>

		<p>The first and foremost advantage of any logging API over plain
		<code>System.out.println</code> resides in its ability to disable
		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.
		</p>
			
		<p>
			Loggers are named entities. Their names are case-sensitive and
			they follow the hierarchical naming rule:
		</p>
		<div class="definition">
			<div class="deftitle">Named Hierarchy</div>
			<p>
				A logger is said to be an ancestor of another logger if
				its name followed by a dot is a prefix of the descendant
				logger name. A logger is said to be a parent of a child
				logger if there are no ancestors between itself and the
				descendant logger.
			</p>
		</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.
		</p>
		<p>
			The root logger resides at the top of the logger hierarchy.  It
			is exceptional in that it is part of every hierarchy at its
			inception. Like every logger, it can be retrieved by its name,
			as follows:
		</p>
		<div class="source"><pre>Logger rootLogger = LoggerFactory.getLogger(<a href="../apidocs/constant-values.html#ch.qos.logback.classic.LoggerContext.ROOT_NAME">LoggerContext.<em>ROOT_NAME</em></a>);</pre></div>

		<p>
			All other loggers are also retrieved with the class static
			<code>getLogger</code> method found in the <a
			href="http://www.slf4j.org/api/org/slf4j/Logger.html">org.slf4j.LoggerFactory</a>
			class. This method takes the name of the desired logger as a
			parameter. Some of the basic methods in the <code>Logger</code>
			interface are listed below.
		</p>

		<div class="source"><pre>package org.slf4j; 
public interface Logger {

  // Printing methods: 
  public void debug(String message);
  public void info(String message); 
  public void warn(String message); 
  public void error(String message); 
  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>

		<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>
		</div>
	
		<p>
			To ensure that all loggers can eventually inherit a level, the
			root logger always has an assigned level. By default, this level
			is DEBUG.
		</p>
		<p>
			Below are four examples with various assigned level values and
			the resulting effective (inherited) levels according to the
			level inheritance rule.
		</p>

		<em>Example 1</em>
		<table>
			<tr>
				<th>
					Logger name
				</th>
				<th>
					Assigned level
				</th>

				<th>
					Effective level
				</th>
			</tr>
			<tr>
				<td>root</td>
				<td>DEBUG</td>
				<td>DEBUG</td>
			</tr>
			<tr>
				<td>X</td>
				<td>none</td>
				<td>DEBUG</td>
			</tr>

			<tr>
				<td>X.Y</td>
				<td>none</td>
				<td>DEBUG</td>
			</tr>
			<tr>
				<td>X.Y.Z</td>
				<td>none</td>
				<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>

		<em>Example 2</em>
		<table>
			<tr>
				<th>
					Logger name
				</th>
				<th>
					Assigned level
				</th>

				<th>
					Effective level
				</th>
			</tr>
			<tr align="left">
				<td>root</td>
				<td>ERROR</td>
				<td>ERROR</td>
			</tr>
			<tr align="left">
				<td>X</td>
				<td>INFO</td>
				<td>INFO</td>
			</tr>

			<tr align="left">
				<td>X.Y</td>
				<td>DEBUG</td>
				<td>DEBUG</td>
			</tr>
			<tr align="left">
				<td>X.Y.Z</td>
				<td>WARN</td>
				<td>WARN</td>
			</tr>
		</table>

		<p>In example 2 above, all loggers have an assigned level value.
		Level inheritence does not come into play.
		</p>

		<em>Example 3</em>
		<table>
			<tr>
				<th>
					Logger name
				</th>
				<th>
					Assigned level
				</th>
				<th>
					Effective level
				</th>
			</tr>
			<tr align="left">
				<td>root</td>
				<td>DEBUG</td>
				<td>DEBUG</td>
			</tr>

			<tr align="left">
				<td>X</td>
				<td>INFO</td>
				<td>INFO</td>
			</tr>
			<tr align="left">
				<td>X.Y</td>
				<td>none</td>
				<td>INFO</td>
			</tr>
			<tr align="left">
				<td>X.Y.Z</td>
				<td>ERROR</td>
				<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>
		<em>Example 4</em>
		<table>

			<tr>
				<th>
					Logger name
				</th>
				<th>
					Assigned level
				</th>
				<th>
					Effective level
				</th>
			</tr>
			<tr align="left">
				<td>root</td>
				<td>DEBUG</td>
				<td>DEBUG</td>
			</tr>

			<tr align="left">
				<td>X</td>
				<td>INFO</td>
				<td>INFO</td>
			</tr>
			<tr align="left">
				<td>X.Y</td>
				<td>none</td>
				<td>INFO</td>
			</tr>
			<tr align="left">
				<td>X.Y.Z</td>
				<td>none</td>
				<td>INFO</td>
			</tr>
		</table>

   
		<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
		<code>X.Y.Z</code> inherit their level value from their nearest
		parent <code>X</code>, which has an assigned level.
		</p>

    <a name="PrintintMethods" />
    <h3>Printing methods</h3>

		<p>By definition, the printing method determines the level of a
		logging request. For example, if <code>L</code> is a logger
		instance, then the statement <code>L.info("..")</code> is a
		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.
		</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 &gt;= q</em>.
			</p>
		</div>

		<p>
			This rule is at the heart of logback. It assumes
			that levels are ordered as follows: 
			<code>DEBUG &lt; INFO &lt; WARN &lt; ERROR&lt; OFF</code>.
		</p>
				
		<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
		by <em>q</em>.
		</p>
		
		<table>
			<tr>
				<th><span style="align:center"><em>p</em>/<em>q</em></span></th>
				<th>DEBUG</th>
				<th>INFO</th>
				<th>WARN</th>
				<th>ERROR</th>	
        <th>OFF</th>    			
			</tr>
			<tr>
				<th>DEBUG</th>
				<td><span class="greenBold">YES</span></td>
				<td><span class="redBold">NO</span></td>
				<td><span class="redBold">NO</span></td>
				<td><span class="redBold">NO</span></td>
        <td><span class="redBold">NO</span></td>
			</tr>
			<tr>
				<th>INFO</th>
				<td><span class="greenBold">YES</span></td>
				<td><span class="greenBold">YES</span></td>
				<td><span class="redBold">NO</span></td>
				<td><span class="redBold">NO</span></td>
        <td><span class="redBold">NO</span></td>
			</tr>
			<tr>
				<th>WARN</th>
				<td><span class="greenBold">YES</span></td>
				<td><span class="greenBold">YES</span></td>
				<td><span class="greenBold">YES</span></td>
				<td><span class="redBold">NO</span></td>
        <td><span class="redBold">NO</span></td>
			</tr>
			<tr>
				<th>ERROR</th>
				<td><span class="greenBold">YES</span></td>
				<td><span class="greenBold">YES</span></td>
				<td><span class="greenBold">YES</span></td>
				<td><span class="greenBold">YES</span></td>
        <td><span class="redBold">NO</span></td>
			</tr>		
		</table>
		
		<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. 
Logger logger = LoggerFactory.getLogger("com.foo");
//set its Level to <span class="blue">INFO</span>
logger.setLevel(Level. <span class="blue">INFO</span>);
Logger barlogger = LoggerFactory.getLogger("com.foo.Bar");

// This request is enabled, because <span class="green bold">WARN</span> &gt;= <span class="blue">INFO</span>
logger.<span class="green bold">warn</span>("Low fuel level.");

// This request is disabled, because <span class="green bold">DEBUG</span> &lt; <span class="blue">INFO</span>. 
logger.<span class="green bold">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 bold">INFO</span> &gt;= <span class="blue">INFO</span>. 
barlogger.<span class="green bold">info</span>("Located nearest gas station.");

// This request is disabled, because <span class="green bold">DEBUG</span> &lt; <span class="blue">INFO</span>. 
barlogger.<span class="green bold">debug</span>("Exiting gas station search");</pre></div>

    <a name="RetrievingLoggers" />
		<h3>Retrieving Loggers</h3>
		<p>
			Calling the <code><a href="../apidocs/org/slf4j/LoggerFactory.html#getLogger(java.lang.String)">LoggerFactory.getLogger</a></code>
			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"><pre>Logger x = LoggerFactory.getLogger("wombat"); 
Logger y = LoggerFactory.getLogger("wombat");</pre></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 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
		located seems to be the best general strategy known so far.
		</p>

    <a name="AppendersAndLayouts" />
    <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. 

      <!--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>

		<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>

			<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>

		</div>
		The table below shows an example:

		<table class="bodyTable">
			<tr>
				<th>Logger Name</th>
				<th>Attached Appenders</th>
				<th>Additivity Flag</th>
				<th>Output Targets</th>
				<th>Comment</th>
			</tr>
			<tr>
				<td>root</td>
				<td>A1</td>
				<td>not applicable</td>
				<td>A1</td>

				<td>Since the root logger stands at the top of the logger
				hiearchy, the additivity flag does not apply to it.
				</td>
			</tr>
			<tr>
				<td>x</td>
				<td>A-x1, A-x2</td>
				<td>true</td>
				<td>A1, A-x1, A-x2</td>
				<td>Appenders of "x" and of root.</td>
			</tr>
			<tr>
				<td>x.y</td>
				<td>none</td>
				<td>true</td>
				<td>A1, A-x1, A-x2</td>
				<td>Appenders of "x" and of root.</td>
			</tr>
			<tr>
				<td>x.y.z</td>
				<td>A-xyz1</td>
				<td>true</td>
				<td>A1, A-x1, A-x2, A-xyz1</td>
				<td>Appenders of "x.y.z", "x" and of root.</td>
			</tr>
			<tr>
				<td>security</td>
				<td>A-sec</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
					<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>
					Only appenders of "security" because the additivity
					flag in "security" is set to
					<code>false</code>.
				</td>
			</tr>
		</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>

		<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>

    <a name="ParametrizedLogging" />
		<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>

		<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>

		<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()) { 
  logger.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));
}</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>



		<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>


		<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>


		<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>

		<div class="source"><pre>logger.debug("The new entry is {}. It replaces {}.", entry, oldEntry);</pre></div>

		<p>If three or more arguments need to be passed, an
		<code>Object[]</code> variant is also availalble. For example, you
		can write:
		</p>


		<div class="source"><pre>Object[] paramArray = {newVal, below, above};
logger.debug("Value {} was inserted between {} and {}.", paramArray);</pre></div>

    <a name="Configuration" />
    <h3>Configuration</h3>

		<p>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>
    
    <div class="highlight">
    <p>
      In order to run the examples in this introduction, you need
      to make sure that certain jar files are present on the
      classpath.
      Please refer to the <a href="../setup.html">setup page</a>
      for further details.
    </p>
    </div>
    
    <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 written
		in XML format.
		</p>

		<p>Existing log4j users can convert their
		<em>log4j.properties</em> files to <em>logback.xml</em> using our <a
		href="http://logback.qos.ch/translator/">PropertiesTranslator</a>
		web-application.
		</p>
		
		<p>
			Configuring logback from a XML file is an easy task. One just needs to
			instanciate a <code>JoranConfigurator</code> and pass the configuration
			file, as the following example demonstrate.
		</p>

     <em>Example 2.1: Logback configuration from file (<a
  href="../xref/chapter2/MyAppWithConfigFile.html">logback-examples/src/main/java/chapter2/MyAppWithConfigFile.java</a>)</em>

<div class="source"><pre>package chapter2;

//Import SLF4J classes.
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import ch.qos.logback.classic.LoggerContext;
import ch.qos.logback.classic.joran.JoranConfigurator;
import ch.qos.logback.core.util.StatusPrinter;

public class MyAppWithConfigFile {
	
  public static void main(String[] args) {
    Logger logger = LoggerFactory.getLogger(MyAppWithConfigFile.class);
    LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();
		
    JoranConfigurator configurator = new JoranConfigurator();
    configurator.setContext(lc);
    configurator.doConfigure(args[0]);

    logger.info("Entering application.");
    Bar bar = new Bar();
    bar.doIt();
    logger.info("Exiting application.");
	
    StatusPrinter.print(lc.getStatusManager());
  }
}</pre></div>	


		<p>This class defines a logger instance variable. 
		It then instantiates a <code>Bar</code>
		object. The <code>Bar</code> class is listed below:
		</p>

		<em>Example 2.2: Sample logging class (<a href="../xref/chapter2/Bar.html">logback-examples/src/main/java/chapter2/Bar.java</a>)</em>
<div class="source"><pre>package chapter2;
  
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

class Bar {

  Logger logger = LoggerFactory.getLogger(Bar.class);	
	
  public void doIt() {
    logger.debug("doing my job");
  }
}</pre></div>

		<p><em>MyAppWithConfigFile</em> configures logback by using the
	   <code>JoranConfigurator</code>.  Joran is a XML interpreter, similar to the
		commons-digester API, but offering several advantages over
		commons-digester. Here, it parses the xml file and runs actions
		depending on the tags it finds.  To setup the <code>JoranConfigurator</code>
		properly, we passed the <code>LoggerContext</code>. A
		<code>LoggerContext</code> is the class that creates and manages
		Loggers in logback.  It is also the class that implements the
		<code>org.slf4j.ILoggerFactory</code> interface.
		</p>
	<p>
		All
    other classes only need to retrieve an instance of
    <code>org.slf4j.Logger</code> by calling
    <code>LoggerFactory.getLogger()</code>, and then log away. For
    example, the only dependence of the <code>Bar</code> class is on
    <code>org.slf4j.Logger</code> and
    <code>org.slf4j.LoggerFactory</code>. Except code that configures
    logback (if such code exists) user code does not need to depend on
    logback, but on SLF4J instead.
    </p>

    <p>Let us configure logback with the
    next XML configuration file:</p>

	<em>Example 2.3: Basic configuration with a xml file (logback-examples/src/main/java/chapter2/sample-config-1.xml)</em>	
<div class="source"><pre>&lt;?xml version="1.0" encoding="UTF-8" ?&gt;

&lt;configuration&gt;

  &lt;appender name="STDOUT"
    class="ch.qos.logback.core.ConsoleAppender"&gt;
    &lt;layout class="ch.qos.logback.classic.PatternLayout"&gt;
      &lt;pattern&gt;%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n&lt;/pattern&gt;
    &lt;/layout&gt;
  &lt;/appender&gt;

  &lt;root&gt;
    &lt;level value="debug" /&gt;
    &lt;appender-ref ref="STDOUT" /&gt;
  &lt;/root&gt;
&lt;/configuration&gt;</pre></div>
	
	<p>We first created an <code>Appender</code>, named <em>STDOUT</em>
	that is of <code>ConsoleAppender</code> type. Its layout is managed
	by a <code>PatternLayout</code>, that uses the value of the <em>pattern</em> parameter
	to generate the logging statement. We then configured the root
	logger, set its level to DEBUG, and linked the newly configured
	<code>ConsoleAppender</code> to the root logger.</p>

	<p>Note that we've set the root logger level explicitly. Since root
	logger have a DEBUG level by default we could have omitted this.</p>
	
	<p>To run this example, use this command:</p>
	
<div class="source"><pre>java chapter2.MyAppWithConfigFile src/main/java/chapter2/sample-config-1.xml</pre></div>

	<p>
		Here is what you should see in the console:
	</p>
	
<div class="source"><pre>18:15:26.718 [main] INFO  chapter2.MyAppWithConfigFile - Entering application.
18:15:26.718 [main] DEBUG chapter2.Bar - doing my job
18:15:26.718 [main] INFO  chapter2.MyAppWithConfigFile - Exiting application.</pre></div>

	
	<p>Logging to the console is a rather simple example. Let's now
	configure logback so that it logs on the console, but also to a
	custom file.</p>

<em>Example 2.4: Configuring logback with multiple appenders (logback-examples/src/main/java/chapter2/sample-config-2.xml)</em>
<div class="source"><pre>&lt;?xml version="1.0" encoding="UTF-8" ?&gt;

&lt;configuration>

  &lt;appender name="STDOUT"
    class="ch.qos.logback.core.ConsoleAppender">
    &lt;layout class="ch.qos.logback.classic.PatternLayout">
      &lt;pattern>%-4relative [%thread] %-5level %class - %msg%n&lt;/pattern>
    &lt;/layout>
  &lt;/appender>

  &lt;appender name="FILE"
    class="ch.qos.logback.core.FileAppender">
    &lt;layout class="ch.qos.logback.classic.PatternLayout">
      &lt;pattern>%-4relative [%thread] %-5level %class - %msg%n&lt;/pattern>
    &lt;/layout>
    &lt;File>sample-log.txt&lt;/File>
  &lt;/appender>

  &lt;root>
    &lt;level value="debug" />
    &lt;appender-ref ref="STDOUT" />
    &lt;appender-ref ref="FILE" />
  &lt;/root>
&lt;/configuration></pre></div>
	
	<p>Now, all the logging statements are directed to the console and
	to a file named <em>sample-log.txt</em>.  As you can see, the
	configuration needed to add an Appender is rather small. The options
	are declared as xml element, in either Appender configuration. They are
	read and their value are assigned to the corresponding attribute in
	the specified java class.
	</p>
	
	<p>Suppose that we do not want to see the DEBUG level statements in
	the chapter2 package anymore.  This is done by adding the following
	bold xml snippet to the configuration file, right before the
	<code>&lt;root&gt;</code> element.</p>

<em>Example 2.5: Configuring a specific logger (logback-examples/src/main/java/chapter2/sample-config-3.xml)</em>	
<div class="source"><pre>&lt;?xml version="1.0" encoding="UTF-8" ?&gt;

&lt;configuration&gt;

  &lt;appender name="STDOUT"
    class="ch.qos.logback.core.ConsoleAppender">
    &lt;layout class="ch.qos.logback.classic.PatternLayout">
      &lt;pattern>%-4relative [%thread] %-5level %class - %msg%n&lt;/pattern>
    &lt;/layout>
  &lt;/appender>

  &lt;appender name="FILE"
    class="ch.qos.logback.core.FileAppender">
    &lt;layout class="ch.qos.logback.classic.PatternLayout">
      &lt;pattern>%-4relative [%thread] %-5level %class - %msg%n&lt;/pattern>
    &lt;/layout>
    &lt;File>sample-log.txt&lt;/File>
  &lt;/appender>
<b>
  &lt;logger name="chapter2"&gt;
    &lt;level value="info" /&gt;
  &lt;/logger&gt;
</b>
  &lt;root&gt;
    &lt;level value="debug" /&gt;
    &lt;appender-ref ref="STDOUT" /&gt;
    &lt;appender-ref ref="FILE" /&gt;
  &lt;/root&gt;
&lt;/configuration&gt;
</pre></div>	
	
	<p>Once done, the output is modified to show only statements of level INFO and higher:</p>
	
<div class="source"><pre>0    [main] INFO  chapter2.MyAppWithConfigFile - Entering application.
0    [main] INFO  chapter2.MyAppWithConfigFile - Exiting application.</pre></div>

	<p>Note that to obtain these different logging behaviors we did not need to recompile code. 
	We could just as easily have logged to a UNIX Syslog daemon, redirected all chapter2 output 
	to a log visualizer, or forwarded logging events to a remote logback server, 
	which would log according to local server policy, for example by forwarding the log event 
	to a second logback server.</p>
	
	
	<p>
		Until now, we always had to specifically load the configuration file and pass it
		to a logback component. However, this step is not necessary in most cases. When logback
		is not configured by instanciating <code>JoranConfigurator</code> objects, it follows 
		a simple policy to configure itself.
	</p>
	
	<ul>
		<p>Logback first tries to find a file called <em>logback.xml</em> within the classpath.</p>
		<p>If no such file is found, it checks for another file called <em>logback-test.xml</em>.</p>
		<p>In case none of these files are found, logback configures itself automatically using the 
		<a href="../xref/ch/qos/logback/classic/BasicConfigurator.html"><code>BasicConfigurator</code>
		</a> class.</p>
	</ul>
	
	<p>
		The first two checks allow for two environments to cooperate nicely. When the application
		using logback is in development and test process, a special file can be used to setup
		a logging environment that is developer-friendly. Once in production environment, the 
		presence of a <em>logback.xml</em> file overrides any <em>logback-test.xml</em> 
		configuration.
	</p>
		
	<p>
		The last step is meant to provide very basic logging functionnality in case no configuration
		file is provided. In that case, the logging requests are output to the console.
	</p>
	
	<p>
		Letting logback load its configuration file is the most often used way of 
		configuring. It allows the user to only import SLF4J classes in her code.
	</p>
	
	<p>
		The last step of logback's configuration policy permits the use of a minimal
		logging configuration right out of the box. Remember the very first example of 
		the introduction. The output was generated due to this feature.
	</p>
  
<a name="UnderTheHood" />
<h3>A peak under the hood</h3>

<p>
After we have introduced the essential logback components, we are now 
ready to describe the steps that the logback framework takes when the user invokes 
a logger's printing method. Let us now analyze the steps logback takes when the 
user invokes the <code>info()</code> method of a 
logger named <em>com.wombat</em>.
</p>

<h4>1. Get the filter chain decision</h4>

<p>
Logback's <code>TurboFilter</code> chain is called. These filters may
be used to prodvide a context-wide threshold, or to filter out certain
events based on basic logging informations such as <code>Marker</code>, 
<code>Level</code>, <code>Logger</code>, message, or the <code>Throwable</code>
that was provided in the logging request.
If the reply of the filter chain is <code>FilterReply.DENY</code>, then the
logging request is dropped. If it is <code>FilterReply.NEUTRAL</code>, then
the next step is processed. In case the reply is <code>FilterReply.ACCEPT</code>,
the next step is skipped and the logging request is directly processed to step 3.
</p>

<h4>2. Apply the Logger level filter</h4>

<p>
Logback compares the effective level of the <em>com.wombat</em> logger
with the level of the request (in this example: <em>INFO</em>). If the logging
request is disabled, then logback will drop the request without further processing.
</p>

<h4>3. Create a <code>LoggingEvent</code> object</h4>

<p>
If the request passed the previous filter, or if the <code>TurboFilter</code> chain
gave a <code>FilterReply.ACCEPT</code> result, logback will create a
<code>ch.qos.logback.classic.LoggingEvent</code> object containing all the 
relevant parameters of the request such as the logger of the request, the request
level, the message, the exception that might have been passed along the request,
the current time, the current thread, several information about the class that 
issued the logging request and the <code>MDC</code> map. Note that some of these fields
are initialized lazily, that is only when they are actually needed.
</p>

<h4>4. Invoking appenders</h4>

<p>
After the creation of a <code>LoggingEvent</code> object, logback will proceed 
to invoke the <code>doAppend()</code> methods of all the applicable appenders, 
that is, the appenders inherited from the logger context.
</p>
<p>
All appenders shipped with the logback distribution extend the 
<code>AppenderBase</code> abstract class that implements the 
<code>doAppend</code> method in a synchronized block ensuring thread-safety. 
The <code>doAppend()</code> method of <code>AppenderBase</code> also invokes 
custom filters attached to the appender, if any such filters exist. 
Custom filters, which can be dynamically attached to any appender, 
are presented Chapter 6.
</p>

<h4>5. Formatting the <code>LoggingEvent</code></h4>

<p>
It is responsibility of the invoked appender to format the 
logging event. However, most (but not all) appenders delegate 
the task of formatting the logging event to their layout. Their 
layout formats the <code>LoggingEvent</code> instance and returns the 
result as a String. Note that some appenders, such as the 
<code>SocketAppender</code>, do not transform the logging event 
into a string but serialize it instead. 
Consequently, they do not require nor have a layout. 
</p>

<h4>6. Sending out the <code>LoggingEvent</code></h4>

<p>
After the logging event is fully formatted it is sent to 
its destination by each appender.
</p>
  
<p>
Here is a sequence UML diagram to show how everything works. You might
want to click on the image to display its bigger version.
</p>

<a href="underTheHood.html"><img src="images/chapter2/underTheHoodSequence2_small.gif" /></a>

<a name="Performance" />
<h3>Performance</h3>

<p>
One of the often-cited arguments against logging is its computational cost. 
This is a legitimate concern as even moderately sized applications can generate 
thousands of log requests. Much effort is spent measuring and tweaking 
logging performance.
Independently of these efforts, the user should still be aware of the following 
performance issues.
</p>

<h4>1. Logging performance when logging is turned off entirely</h4>

<p>
You can turn off logging entirely by setting the level of the root logger
to <code>Level.OFF</code>, the highest possible level. 
When logging is turned off entirely, 
the cost of a log request consists of a method invocation plus an 
integer comparison. On a 3.2Ghz Pentium D machine this cost is typically 
around 20 nanoseconds. 
</p>

<p>
However, any method invocation involves the "hidden" cost of parameter construction. 
For example, for some logger <em>x</em> writing, 
</p>

<div class="source"><pre>x.debug("Entry number: " + i + "is " + entry[i]);</pre></div>

<p>
incurs the cost of constructing the message parameter, i.e. converting both 
integer <code>i</code> and <code>entry[i]</code> to a string, and concatenating 
intermediate strings, regardless of whether the message will be logged or not. 
</p>

<p>
The cost of parameter construction can be quite high and depends on the size 
of the parameters involved. To avoid the cost of parameter construction 
you can use logback's parametrized logging: 
</p>

<div class="source"><pre>x.debug("Entry number: {} is {}", i, entry[i]);</pre></div>

<p>
This will not incur the cost of parameter construction. Compared to the
previous call to the <code>debug()</code> method, this call will be faster by 
a very wide margin. 
The message will be formatted only if the request is processed to the appenders. 
If it is processed, the component that formats the message offers high performance 
and does not impact negatively the overall process. 
It respectively takes 2 and 4 microseconds to format a message with 1 and 3 parameters.
</p>

<p>
Please notice that, despite the performance points that we just discussed, inserting 
logging statements in tight-loops or very frequently invoked code is a lose-lose proposal
and will not result in high performance. They will slow down your application even 
if logging is turned off or generate massive (and hence useless) output if enabled. 
</p>

<h4>2. The performance of deciding whether to log or not to log when logging is turned on.</h4>

<p>
In logback, there is no need to walk the whole logger hierarchy. A logger knows
its effective level (that is, its level, once level inheritance has been
taken into consideration) when it is created. Should the level of a parent logger
be changed, then all child loggers will be contacted and handle the change. Thus, before
accepting or denying a request based on the effective level, the logger does not need
to search its ancestors.
</p>

<p>
Given this situation, it takes the same time to decide whether to log or not when logging
is turned on as it takes when logging is turned off.
</p>

<h4>3. Actual logging (formatting and writing to the output device)</h4>

<p>
This is the cost of formatting the log output and sending it to its 
target destination. Here again, a serious effort was made to make 
layouts (formatters) perform as quickly as possible. 
The same is true for appenders. The typical cost of actually logging is 
about 9 to 12 microseconds when logging to a file on the local machine.
It goes up to 1 millisecond when logging to a database on a remote server.
</p>

<p>
Although feature-rich, one of the foremost design goals of logback was speed 
of execution, a requirement which is second only to reliability. Some logback 
components have been rewritten many times to improve performance. 
</p>

</body>
</document>
