Introduction

Log4j introduced the concept of the Mapped Diagnostic Context or MDC. It has been documented and discussed in numerous places including Log4j MDC: What and Why and Log4j and the Mapped Diagnostic Context. In addition, Log4j 1.x provides support for a Nested Diagnostic Context or NDC. It too has been documented and discussed in various places such as Log4j NDC. SLF4J/Logback followed with its own implementation of the MDC, which is documented very well at Mapped Diagnostic Context.

Log4j 2 continues with the idea of the MDC and the NDC but merges them into a single Thread Context. The Thread Context Map is the equivalent of the MDC and the Thread Context Stack is the equivalent of the NDC. Although these are frequently used for purposes other than diagnosing problems, they are still frequently referred to as the MDC and NDC in Log4j 2 since they are already well known by those acronyms.

Fish Tagging

Most real-world systems have to deal with multiple clients simultaneously. In a typical multithreaded implementation of such a system, different threads will handle different clients. Logging is especially well suited to trace and debug complex distributed applications. A common approach to differentiate the logging output of one client from another is to instantiate a new separate logger for each client. This promotes the proliferation of loggers and increases the management overhead of logging.

A lighter technique is to uniquely stamp each log request initiated from the same client interaction. Neil Harrison described this method in the book "Patterns for Logging Diagnostic Messages," in Pattern Languages of Program Design 3, edited by R. Martin, D. Riehle, and F. Buschmann (Addison-Wesley, 1997). Just as a fish can be tagged and have its movement tracked, stamping log events with a common tag or set of data elements allows the complete flow of a transaction or a request to be tracked. We call this Fish Tagging.

Log4j provides two mechanisms for performing Fish Tagging; the Thread Context Map and the Thread Context Stack. The Thread Context Map allows any number of items to be added and be identified using key/value pairs. The Thread Context Stack allows one or more items to be pushed on the Stack and then be identified by their order in the Stack or by the data itself. Since key/value pairs are more flexible, the Thread Context Map is recommended when data items may be added during the processing of the request or when there are more than one or two items.

To uniquely stamp each request using the Thread Context Stack, the user pushes contextual information on to the Stack.

ThreadContext.push(UUID.randomUUID().toString()); // Add the fishtag;

logger.debug("Message 1");
.
.
.
logger.debug("Message 2");
.
.
ThreadContext.pop();

The alternative to the Thread Context Stack is the Thread Context Map. In this case, attributes associated with the request being processed are adding at the beginning and removed at the end as follows:

ThreadContext.put("id", UUID.randomUUID().toString(); // Add the fishtag;
ThreadContext.put("ipAddress", request.getRemoteAddr());
ThreadContext.put("loginId", session.getAttribute("loginId"));
ThreadContext.put("hostName", request.getServerName());
.
logger.debug("Message 1");
.
.
logger.debug("Message 2");
.
.
ThreadContext.clear();

The Stack and the Map are managed per thread and are based on ThreadLocal by default. The Map can be configured to use an InheritableThreadLocal by setting system property isThreadContextMapInheritable to "true". When configured this way, the contents of the Map will be passed to child threads. However, as discussed in the Executors class and in other cases where thread pooling is utilized, the ThreadContext may not always be automatically passed to worker threads. In those cases the pooling mechanism should provide a means for doing so. The getContext() and cloneStack() methods can be used to obtain copies of the Map and Stack respectively.

Note that all methods of the ThreadContext class are static.

Including the ThreadContext when writing logs

The PatternLayout provides mechanisms to print the contents of the ThreadContext Map and Stack.

• Use %X by itself to include the full contents of the Map.
• Use %X{key} to include the specified key.
• Use %x to include the full contents of the Stack.