<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 7: Diagnostic Context</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>
		
		<p>
				One of the design goals of logback is to audit and debug complex distributed applications. 
				Most real-world distributed systems need to deal with multiple clients simultaneously. 
				In a typical multithreaded implementation of such a system, different threads will handle 
				different clients. A possible but discouraged approach to differentiate the logging output of 
				one client from another consists of instantiating a new and separate logger for each client. 
				This technique promotes the proliferation of loggers and considerably increases 
				their management overhead.
		</p>
		<div class="highlight">
    <p>
      In order to run the examples in this chapter, 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> 
				A lighter technique consists of uniquely stamping each 
				log request servicing a given client. Neil Harrison described this method in the book 
				<em>Patterns for Logging Diagnostic Messages</em> in 
				Pattern Languages of Program Design 3, edited by R. Martin, D. Riehle, 
				and F. Buschmann (Addison-Wesley, 1997). Logback offers a variant of this technique: 
				Mapped Diagnostic Contexts (MDC).
		</p>
		
		<p>
			To uniquely stamp each request, the user puts contextual information into the 
			<code><a href="../xref/ch/qos/logback/classic/MDC.html">MDC</a></code>, 
			the abbreviation of Mapped Diagnostic Context. 
			The public interface of the MDC class is shown below. 
		</p>

<div class="source"><pre>package ch.qos.logback.classic;

public class MDC {
  //Put a context value as identified by <em>key</em>
  //into the current thread's context map.
  <b>public static void put(String key, String val);</b>

  //Get the context identified by the <code>key</code> parameter.
  <b>public static String get(String key);</b>

  //Remove the the context identified by the <code>key</code> parameter.
  <b>public static void remove(String key);</b>

  //Clear all entries in the MDC.
  <b>public static void clear();</b>

  //Returns the keys in the MDC as a Set. The returned value can be null.
  <b>public static Set&lt;String> getKeys();</b>
}</pre></div>

		<p>
			The <code>MDC</code> class contains only static methods. 
			It lets the developer place information in a <em>diagnostic context</em> that can be 
			subsequently retrieved by certain logback components. The 
			<code>MDC</code> manages contextual information on a <em>per thread basis</em>.  
			Typically, while starting to service a new client request, the developer will 
			insert pertinent contextual information, such as the client id, client's IP 
			address, request parameters etc. into the <code>MDC</code>. Logback components, 
			if appropriately configured, will automatically include this information 
			in each log entry.
		</p>

		<p>
			The next application named 
			<code><a href="../xref/chapter7/SimpleMDC.html">SimpleMDC</a></code> 
			demonstrates this basic principle.
		</p>
<em>Example 7.1: Basic MDC usage (<a href="../xref/chapter7/SimpleMDC.html">
logback-examples/src/main/java/chapter7/SimpleMDC.java)</a></em>
<div class="source"><pre>package chapter7;

import org.slf4j.LoggerFactory;

import ch.qos.logback.classic.Logger;
import ch.qos.logback.classic.MDC;
import ch.qos.logback.classic.PatternLayout;
import ch.qos.logback.core.ConsoleAppender;

public class SimpleMDC {
  static public void main(String[] args) throws Exception {
    // You can put values in the MDC at any time. We first put the
    // first name
    <b>MDC.put("first", "Dorothy");</b>

    // Configure logback
    PatternLayout layout = new PatternLayout();
    layout.setPattern("%X{first} %X{last} - %m%n");
    layout.start();
    ConsoleAppender&lt;LoggingEvent> appender = new ConsoleAppender&lt;LoggingEvent>();
    appender.setLayout(layout);
    appender.start();
    Logger root = (Logger)LoggerFactory.getLogger("root");
    root.addAppender(appender);
    
    // get a logger
    Logger logger = (Logger)LoggerFactory.getLogger(SimpleMDC.class);

    // We now put the last name
    <b>MDC.put("last", "Parker");</b>

    // The most beautiful two words in the English language according
    // to Dorothy Parker:
    logger.info("Check enclosed.");
    logger.debug("The most beautiful two words in English.");

    MDC.put("first", "Richard");
    MDC.put("last", "Nixon");
    logger.info("I am not a crook.");
    logger.info("Attributed to the former US president. 17 Nov 1973.");
  }
}</pre></div>

		<p>
			The main method starts by associating the value <em>Dorothy</em> with 
			the key <em>first</em> in the <code>MDC</code>. You can place as many 
			value/key associations in the <code>MDC</code> as you wish. 
			Multiple insertions with the same key will overwrite older values. 
			The code then proceeds to configure logback. 
			Note the usage of the <em>%X</em> specifier within the 
			<code>PatternLayout</code> conversion pattern. The <em>%X</em> 
			conversion specifier is employed twice, once for the key <em>first</em> 
			and once for the key <em>last</em>. After configuring the root logger, 
			the code associates the value <em>Parker</em> with the key <em>last</em>. 
			It then invokes the logger twice with different messages. 
			The code finishes by setting the <code>MDC</code> to different values 
			and issuing several logging requests. Running SimpleMDC yields:
		</p>

<div class="source"><pre>Dorothy Parker - Check enclosed.
Dorothy Parker - The most beautiful two words in English.
Richard Nixon - I am not a crook.
Richard Nixon - Attributed to the former US president. 17 Nov 1973.</pre></div>


		<p>
			The <code>SimpleMDC</code> application illustrates how logback layouts, 
			if configured appropriately, automatically output <code>MDC</code> information. 
			Moreover, the information placed into the <code>MDC</code> can be used by 
			multiple logger invocations.
		</p>
		
		<h3>Advanced Use</h3>
		
		<p>
			Mapped Diagnostic Contexts shine brightest within client server architectures. 
			Typically, multiple clients will be served by multiple threads on the server. 
			Although the methods in the <code>MDC</code> class are static, 
			the diagnostic context is managed on a per thread basis, allowing each server 
			thread to bear a distinct <code>MDC</code> stamp. <code>MDC</code> operations 
			such as <code>put()</code> and <code>get()</code> affect the <code>MDC</code> 
			of the <em>current</em> thread only. The <code>MDC</code> in other threads remain 
			unaffected. Given that <code>MDC</code> information is managed on a 
			per thread basis, each thread will have its own copy of the <code>MDC</code>. 
			Thus, there is no need for the developer to worry about thread-safety or 
			synchronization when programming with the <code>MDC</code> because 
			it safely and transparently handles these issues.
		</p>

		<p>
			The next example is somewhat more advanced. 
			It shows how the 	<code>MDC</code> can be used in a client-server setting. 
			The server-side implements the <code>NumberCruncher</code> interface shown in 
			Example 7.2 below. <code>The NumberCruncher</code> interface contains a single 
			method named <code>factor()</code>. Using RMI technology, client invokes the 
			<code>factor()</code> method of the server application to retrieve the distinct 
			factors of an integer.
		</p>

<em>Example 7.2: The service interface (<a href="../xref/chapter7/NumberCruncher.html">
logback-examples/src/main/java/chapter7/NumberCruncher.java)</a></em>
<div class="source"><pre>package chapter7;

import java.rmi.Remote;
import java.rmi.RemoteException;

/**
 * NumberCruncher factors positive integers.
 */
public interface NumberCruncher extends Remote {
  /**
   * Factor a positive integer <code>number</code> and return its
   * <em>distinct</em> factor's as an integer array.
   * */
  int[] factor(int number) throws RemoteException;
}</pre></div>

		<p>
			The <code>NumberCruncherServer</code> application, listed in Example 7.3 below, 
			implements the <code>NumberCruncher</code> interface. Its main method exports 
			an RMI Registry on the local host that accepts requests on a well-known port.  
		</p>

<em>Example 7.3: The server side (<a href="../xref/chapter7/NumberCruncherServer.html">
logback-examples/src/main/java/chapter7/NumberCruncherServer.java)</a></em>
<div class="source"><pre>package chapter7;

import java.rmi.RemoteException;
import java.rmi.registry.LocateRegistry;
import java.rmi.registry.Registry;
import java.rmi.server.UnicastRemoteObject;
import java.util.Vector;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import ch.qos.logback.classic.LoggerContext;
import ch.qos.logback.classic.MDC;
import ch.qos.logback.classic.joran.JoranConfigurator;
import ch.qos.logback.core.joran.spi.JoranException;


/**
 * A simple NumberCruncher implementation that logs its progress when
 * factoring numbers. The purpose of the whole exercise is to show the
 * use of mapped diagnostic contexts in order to distinguish the log
 * output from different client requests.
 * */
public class NumberCruncherServer extends UnicastRemoteObject
  implements NumberCruncher {

  private static final long serialVersionUID = 1L;

  static Logger logger = LoggerFactory.getLogger(NumberCruncherServer.class);

  public NumberCruncherServer() throws RemoteException {
  }

  public int[] factor(int number) throws RemoteException {
    // The client's host is an important source of information.
    try {
      <b>MDC.put("client", NumberCruncherServer.getClientHost());</b>
    } catch (java.rmi.server.ServerNotActiveException e) {
      logger.warn("Caught unexpected ServerNotActiveException.", e);
    }

    // The information contained within the request is another source
    // of distinctive information. It might reveal the users name,
    // date of request, request ID etc. In servlet type environments,
    // useful information is contained in the HttpRequest or in the  
    // HttpSession.
    <b>MDC.put("number", String.valueOf(number));</b>

    logger.info("Beginning to factor.");

    if (number &lt;= 0) {
      throw new IllegalArgumentException(number +
        " is not a positive integer.");
    } else if (number == 1) {
      return new int[] { 1 };
    }

    Vector&lt;Integer> factors = new Vector&lt;Integer>();
    int n = number;

    for (int i = 2; (i &lt;= n) &amp;&amp; ((i * i) &lt;= number); i++) {
      // It is bad practice to place log requests within tight loops.
      // It is done here to show interleaved log output from
      // different requests. 
      logger.debug("Trying " + i + " as a factor.");

      if ((n % i) == 0) {
        logger.info("Found factor " + i);
        factors.addElement(new Integer(i));

        do {
          n /= i;
        } while ((n % i) == 0);
      }

      // Placing artificial delays in tight-loops will also lead to
      // sub-optimal resuts. :-)
      delay(100);
    }

    if (n != 1) {
      logger.info("Found factor " + n);
      factors.addElement(new Integer(n));
    }

    int len = factors.size();

    int[] result = new int[len];

    for (int i = 0; i &lt; len; i++) {
      result[i] = ((Integer) factors.elementAt(i)).intValue();
    }

    <b>// clean up
    MDC.remove("client");
    MDC.remove("number");</b>

    return result;
  }

  static void usage(String msg) {
    System.err.println(msg);
    System.err.println("Usage: java chapter7.NumberCruncherServer configFile\n" +
      "   where configFile is a logback configuration file.");
    System.exit(1);
  }

  public static void delay(int millis) {
    try {
      Thread.sleep(millis);
    } catch (InterruptedException e) {
    }
  }

  public static void main(String[] args) {
    if (args.length != 1) {
      usage("Wrong number of arguments.");
    }

    String configFile = args[0];

    if (configFile.endsWith(".xml")) {
      try {
        LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();
        JoranConfigurator configurator = new JoranConfigurator();
        configurator.setContext(lc);
        lc.shutdownAndReset();
        configurator.doConfigure(args[0]);
      } catch (JoranException je) {
        je.printStackTrace();
      }
    }

    NumberCruncherServer ncs;

    try {
      ncs = new NumberCruncherServer();
      logger.info("Creating registry.");

      Registry registry = LocateRegistry.createRegistry(Registry.REGISTRY_PORT);
      registry.rebind("Factor", ncs);
      logger.info("NumberCruncherServer bound and ready.");
    } catch (Exception e) {
      logger.error("Could not bind NumberCruncherServer.", e);

      return;
    }
  }
}</pre></div>

		<p>
				The implementation of the <code>factor(int number)</code> method is 
				of particular relevance. It starts by putting the client's hostname into the 
				<code>MDC</code> under the key <em>client</em>. The number to factor, 
				as requested by the client, is put into the <code>MDC</code> under the key 
				<em>number</em>. After computing the distinct factors of the integer 
				parameter, the result is returned to the client. Before returning the 
				result however, the values for the <em>client</em> and <em>number</em> are 
				cleared by calling the <code>MDC.remove()</code> method. Normally, 
				a <code>put()</code> operation should be balanced by the corresponding 
				<code>remove()</code> operation. Otherwise, the <code>MDC</code> will 
				contain stale values for certain keys. We would recommend that whenever 
				possible <code>remove()</code> operations be performed within finally blocks, 
				ensuring their invocation regardless of the execution path of the code.
		</p>	
		
		<p>
			After these theoretical explanations, we are ready to run the number 
			cruncher example. Start the server with the following command:
		</p>
		
<div class="source"><pre>java chapter7.NumberCruncherServer src/main/java/chapter7/mdc1.xml</pre></div>
		
		<p>
			The <em>mdc1.xml</em> configuration file is listed below:
		</p>
<em>Example 7.4: Configuration file (logback-examples/src/main/java/chapter7/mdc1.xml)</em>
<div class="source"><pre>&lt;configuration>

  &lt;appender name="CONSOLE"
    class="ch.qos.logback.core.ConsoleAppender">
    &lt;layout class="ch.qos.logback.classic.PatternLayout">
      &lt;Pattern>%-4r [%thread] %-5level <b>C:%X{client} N:%X{number}</b> - %msg%n&lt;/Pattern>
    &lt;/layout>	    
  &lt;/appender>
  
  &lt;root>
    &lt;level value ="debug"/>
    &lt;appender-ref ref="CONSOLE"/>
  &lt;/root>  
&lt;/configuration></pre></div>

		<p>
			Note the use of the <em>%X</em> conversion specifier within the 
			<span class="option">Pattern</span> option.
		</p>
	
		<p>
			The following command starts an instance of <code>NumberCruncherClient</code> 
			application:  	
		</p>
		
<div class="source"><pre>java chapter7.NumberCruncherClient <em>hostname</em></pre></div>

		<p>
			where <em>hostname</em> is the host where the 
			<code>NumberCruncherServer</code> is running
		</p>
		
		<p>
			Executing multiple instances of the client and requesting the server to factor 
			the numbers 129 from the first client and shortly thereafter 
			the number 71 from the second client, the server outputs the following:
		</p>
		
<div class="source"><pre>
<b>70984 [RMI TCP Connection(4)-192.168.1.6] INFO  C:orion N:129 - Beginning to factor.</b>
70984 [RMI TCP Connection(4)-192.168.1.6] DEBUG C:orion N:129 - Trying 2 as a factor.
71093 [RMI TCP Connection(4)-192.168.1.6] DEBUG C:orion N:129 - Trying 3 as a factor.
71093 [RMI TCP Connection(4)-192.168.1.6] INFO  C:orion N:129 - Found factor 3
71187 [RMI TCP Connection(4)-192.168.1.6] DEBUG C:orion N:129 - Trying 4 as a factor.
71297 [RMI TCP Connection(4)-192.168.1.6] DEBUG C:orion N:129 - Trying 5 as a factor.
71390 [RMI TCP Connection(4)-192.168.1.6] DEBUG C:orion N:129 - Trying 6 as a factor.
<b>71453 [RMI TCP Connection(5)-192.168.1.6] INFO  C:orion N:71 - Beginning to factor.</b>
71453 [RMI TCP Connection(5)-192.168.1.6] DEBUG C:orion N:71 - Trying 2 as a factor.
71484 [RMI TCP Connection(4)-192.168.1.6] DEBUG C:orion N:129 - Trying 7 as a factor.
71547 [RMI TCP Connection(5)-192.168.1.6] DEBUG C:orion N:71 - Trying 3 as a factor.
71593 [RMI TCP Connection(4)-192.168.1.6] DEBUG C:orion N:129 - Trying 8 as a factor.
71656 [RMI TCP Connection(5)-192.168.1.6] DEBUG C:orion N:71 - Trying 4 as a factor.
71687 [RMI TCP Connection(4)-192.168.1.6] DEBUG C:orion N:129 - Trying 9 as a factor.
71750 [RMI TCP Connection(5)-192.168.1.6] DEBUG C:orion N:71 - Trying 5 as a factor.
71797 [RMI TCP Connection(4)-192.168.1.6] DEBUG C:orion N:129 - Trying 10 as a factor.
71859 [RMI TCP Connection(5)-192.168.1.6] DEBUG C:orion N:71 - Trying 6 as a factor.
71890 [RMI TCP Connection(4)-192.168.1.6] DEBUG C:orion N:129 - Trying 11 as a factor.
71953 [RMI TCP Connection(5)-192.168.1.6] DEBUG C:orion N:71 - Trying 7 as a factor.
72000 [RMI TCP Connection(4)-192.168.1.6] INFO  C:orion N:129 - Found factor 43
72062 [RMI TCP Connection(5)-192.168.1.6] DEBUG C:orion N:71 - Trying 8 as a factor.
72156 [RMI TCP Connection(5)-192.168.1.6] INFO  C:orion N:71 - Found factor 71</pre></div>

		<p>
			The clients were run from a machine called <em>orion</em> as can be seen in 
			the above output. Even if the server processes the requests of clients 
			near-simultaneously in separate threads, the logging output pertaining 
			to each client request can be distinguished by studying the output of the 
			<code>MDC</code>. Note for example the stamp associated with <em>number</em>, 
			i.e. the number to factor. 
		</p>
		
		<p>
			The attentive reader might have observed that the thread name could 
			also have been used to distinguish each request. The thread name can cause 
			confusion if the server side technology recycles threads. In that case, 
			it may be hard to determine the boundaries of each request, that is, 
			when a given thread finishes servicing a request and when it begins servicing the next.
			Because the <code>MDC</code> is under the control of the application developer, 
			<code>MDC</code> stamps do not suffer from this problem. 
		</p>
		
		
		
		<h3>Automating access to the <code>MDC</code></h3>
		
		<p>
			As we've seen, the <code>MDC</code> is very useful when dealing with multiple
			clients. In the case of a web application that manages user authentication, one
			simple solution could be to set the user's name in the <code>MDC</code> and remove
			it once the user logs out. Unfortunately, it is not always possible to achieve
			reliable results using this technique. Since <code>MDC</code> is managing
			information on a <em>per thread</em> basis, a server that recycles
			threads might lead to false information contained in the <code>MDC</code>.
		</p>
		
		<p>
			To allow the information contained in the <code>MDC</code> to be correct
			at all times when a request is processed, a solution might be to store the
			username at the beginning of the process, and remove it at the end of
			said process. A servlet 
			<a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/Filter.html">
			<code>Filter</code></a> is a good tool to have at
			hand in such case.
		</p>
		
		<p>
			By using a servlet filter, one can access the request, try to access
			to relevant user information and store it in the <code>MDC</code>. 
			Then, after the process of creating the response, one just needs 
			to remove the user information from the <code>MDC</code>.
		</p>
		
		<p>
		Here is an implementation of such a filter:
		</p>

<em>Example 7.5: User servlet filter (<a href="../xref/chapter7/UserServletFilter.html">
logback-examples/src/main/java/chapter7/UserServletFilter.java)</a></em>
<div class="source"><pre>package chapter7;

import java.io.IOException;
import java.security.Principal;

import javax.servlet.Filter;
import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpSession;

import ch.qos.logback.classic.MDC;

public class UserServletFilter implements Filter {

  boolean userRegistered = false;
  
  private final String userKey = "username";
  
  public void destroy() {
  }

  public void doFilter(ServletRequest request, ServletResponse response,
    FilterChain chain) throws IOException, ServletException {

    HttpServletRequest req = (HttpServletRequest) request;
    Principal principal = req.getUserPrincipal();

    if (principal != null) {
      String username = principal.getName();
      registerUsername(username);
    } else {
      HttpSession session = req.getSession();
      String username = (String)session.getAttribute(userKey);
      registerUsername(username);
    }
    
    try {
      chain.doFilter(request, response);
    } finally {
      if (userRegistered) {
        MDC.remove(userKey);
      }
    }
  }

  public void init(FilterConfig arg0) throws ServletException {
  }
  
  private void registerUsername(String username) {
    if (username != null &amp;&amp; username.trim().length() > 0) {
      MDC.put(userKey, username);
      userRegistered = true;
    }
  }
}</pre></div>


	<p>
		When the filter's <code>doFilter()</code> method is called, is first looks for a
		<code>java.security.Principal</code> object in the request. This object contains 
		the name of the currently authenticated user. In case the user principal is not set, 
		the filter looks for a session attribute matching a given key (here <em>username</em>).
		If a user information is found, it is registered in the <code>MDC</code>.
	</p>
		
	<p>
		Once the filter chain has completed, the filter removes the user information
		from the <code>MDC</code>.
	</p>
	
	<p>
		With this filter, the user information is present in the <code>MDC</code> only 
		the time it takes to process the request. The thread may be reused to process a
		request for another user without risking to display false information in the
		logs.
	</p>
		
  </body>
</document>