Google Git
Sign in
apache / logging-log4j-site / d0d0de55986756593c08e5d2b8059541eacaf428 / . / log4j-2.4 / manual / thread-context.html
blob: 49c16a402dde3c2fe376f8cbf7542573de44d137 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- Generated by Apache Maven Doxia at 2015-09-20 -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Log4j &#x2013; Log4j 2 Thread Context - Apache Log4j 2</title>
<link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css" />
<link rel="stylesheet" href="../css/site.css" type="text/css" />
<script type="text/javascript" src="../js/jquery.min.js"></script>
<script type="text/javascript" src="../js/bootstrap.min.js"></script>
<script type="text/javascript" src="../js/prettify.min.js"></script>
<script type="text/javascript" src="../js/site.js"></script>
<meta name="author" content="Ralph Goers" />
<meta name="author" content="Gary Gregory" />
<meta name="Date-Revision-yyyymmdd" content="20150920" />
<meta http-equiv="Content-Language" content="en" />
</head>
<body class="composite">
<a href="https://logging.apache.org/">
<img class="logo-left" src="../images/ls-logo.jpg" alt="Apache logging services logo" />
</a>
<img class="logo-right" src="../images/logo.jpg" alt="Apache log4j logo" />
<div class="clear"></div>
<div class="navbar">
<div class="navbar-inner">
<div class="container-fluid">
<a class="brand" href="http://logging.apache.org/log4j/2.x/">Apache Log4j 2 &trade;</a>
<ul class="nav">
<li>
<a href="http://wiki.apache.org/logging" class="external" target="_blank" title="Logging Wiki">Logging Wiki</a>
</li>
<li>
<a href="http://www.apache.org/" class="external" target="_blank" title="Apache">Apache</a>
</li>
<li>
<a href="../../../" title="Logging Services">Logging Services</a>
</li>
<li>
<a href="https://analysis.apache.org/dashboard/index/org.apache.logging.log4j:log4j" class="external" target="_blank" title="Sonar">Sonar</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container-fluid">
<table class="layout-table">
<tr>
<td class="sidebar">
<div class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-home"></i>Apache Log4j™ 2</li>
<li class="none">
<a href="../index.html" title="About">About</a>
</li>
<li class="none">
<a href="../download.html" title="Download">Download</a>
</li>
<li class="none">
<a href="../maven-artifacts.html" title="Maven and Ivy">Maven and Ivy</a>
</li>
<li class="none">
<a href="../build.html" title="Build">Build</a>
</li>
<li class="none">
<a href="../guidelines.html" title="Guidelines">Guidelines</a>
</li>
<li class="none">
<a href="../javastyle.html" title="Style Guide">Style Guide</a>
</li>
<li class="none">
<a href="../changelog.html" title="Changelog">Changelog</a>
</li>
<li class="collapsed">
<a href="../javadoc.html" title="Javadoc">Javadoc</a>
</li>
<li class="none">
<a href="../runtime-dependencies.html" title="Runtime Dependencies">Runtime Dependencies</a>
</li>
<li class="none">
<a href="../faq.html" title="FAQ">FAQ</a>
</li>
<li class="none">
<a href="../articles.html" title="Articles">Articles</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-book"></i>Manual</li>
<li class="none">
<a href="../manual/index.html" title="Introduction">Introduction</a>
</li>
<li class="none">
<a href="../manual/architecture.html" title="Architecture">Architecture</a>
</li>
<li class="none">
<a href="../manual/migration.html" title="Log4j 1.x Migration">Log4j 1.x Migration</a>
</li>
<li class="expanded">
<a href="../manual/api.html" title="API">API</a>
<ul>
<li class="none">
<a href="../manual/flowtracing.html" title="Flow Tracing">Flow Tracing</a>
</li>
<li class="none">
<a href="../manual/markers.html" title="Markers">Markers</a>
</li>
<li class="none">
<a href="../manual/eventlogging.html" title="Event Logging">Event Logging</a>
</li>
<li class="none">
<a href="../manual/messages.html" title="Messages">Messages</a>
</li>
<li class="none active">
<a href="../manual/thread-context.html" title="ThreadContext">ThreadContext</a>
</li>
</ul>
</li>
<li class="collapsed">
<a href="../manual/configuration.html" title="Configuration">Configuration</a>
</li>
<li class="collapsed">
<a href="../manual/webapp.html" title="Web Applications and JSPs">Web Applications and JSPs</a>
</li>
<li class="collapsed">
<a href="../manual/plugins.html" title="Plugins">Plugins</a>
</li>
<li class="collapsed">
<a href="../manual/lookups.html" title="Lookups">Lookups</a>
</li>
<li class="collapsed">
<a href="../manual/appenders.html" title="Appenders">Appenders</a>
</li>
<li class="collapsed">
<a href="../manual/layouts.html" title="Layouts">Layouts</a>
</li>
<li class="collapsed">
<a href="../manual/filters.html" title="Filters">Filters</a>
</li>
<li class="collapsed">
<a href="../manual/async.html" title="Async Loggers">Async Loggers</a>
</li>
<li class="none">
<a href="../manual/jmx.html" title="JMX">JMX</a>
</li>
<li class="none">
<a href="../manual/logsep.html" title="Logging Separation">Logging Separation</a>
</li>
<li class="collapsed">
<a href="../manual/extending.html" title="Extending Log4j">Extending Log4j</a>
</li>
<li class="collapsed">
<a href="../manual/customconfig.html" title="Extending Log4j Configuration">Extending Log4j Configuration</a>
</li>
<li class="collapsed">
<a href="../manual/customloglevels.html" title="Custom Log Levels">Custom Log Levels</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-cog"></i>Components</li>
<li class="none">
<a href="../log4j-api/index.html" title="API">API</a>
</li>
<li class="none">
<a href="../log4j-core/index.html" title="Implementation">Implementation</a>
</li>
<li class="none">
<a href="../log4j-jcl/index.html" title="Commons Logging Bridge">Commons Logging Bridge</a>
</li>
<li class="none">
<a href="../log4j-1.2-api/index.html" title="Log4j 1.2 API">Log4j 1.2 API</a>
</li>
<li class="none">
<a href="../log4j-slf4j-impl/index.html" title="SLF4J Binding">SLF4J Binding</a>
</li>
<li class="none">
<a href="../log4j-jul/index.html" title="JUL Adapter">JUL Adapter</a>
</li>
<li class="none">
<a href="../log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter">Log4j 2 to SLF4J Adapter</a>
</li>
<li class="none">
<a href="../log4j-flume-ng/index.html" title="Apache Flume Appender">Apache Flume Appender</a>
</li>
<li class="none">
<a href="../log4j-taglib/index.html" title="Log4j Tag Library">Log4j Tag Library</a>
</li>
<li class="none">
<a href="../log4j-jmx-gui/index.html" title="Log4j JMX GUI">Log4j JMX GUI</a>
</li>
<li class="none">
<a href="../log4j-web/index.html" title="Log4j Web Application Support">Log4j Web Application Support</a>
</li>
<li class="none">
<a href="../log4j-nosql/index.html" title="Log4j NoSQL support">Log4j NoSQL support</a>
</li>
<li class="none">
<a href="../log4j-iostreams/index.html" title="Log4j IO Streams">Log4j IO Streams</a>
</li>
<li class="none">
<a href="../log4j-liquibase/index.html" title="Log4j Liquibase Binding">Log4j Liquibase Binding</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-info-sign"></i>Project Information</li>
<li class="none">
<a href="../dependencies.html" title="Dependencies">Dependencies</a>
</li>
<li class="none">
<a href="../dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a>
</li>
<li class="none">
<a href="../dependency-management.html" title="Dependency Management">Dependency Management</a>
</li>
<li class="none">
<a href="../team-list.html" title="Project Team">Project Team</a>
</li>
<li class="none">
<a href="../mail-lists.html" title="Mailing Lists">Mailing Lists</a>
</li>
<li class="none">
<a href="../issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
</li>
<li class="none">
<a href="../license.html" title="Project License">Project License</a>
</li>
<li class="none">
<a href="../source-repository.html" title="Source Repository">Source Repository</a>
</li>
<li class="none">
<a href="../project-summary.html" title="Project Summary">Project Summary</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-cog"></i>Project Reports</li>
<li class="none">
<a href="../changes-report.html" title="Changes Report">Changes Report</a>
</li>
<li class="none">
<a href="../jira-report.html" title="JIRA Report">JIRA Report</a>
</li>
<li class="none">
<a href="../surefire-report.html" title="Surefire Report">Surefire Report</a>
</li>
<li class="none">
<a href="../rat-report.html" title="RAT Report">RAT Report</a>
</li>
</ul>
</div>
<div id="poweredBy">
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
<img class="poweredBy" alt="Built by Maven" src="../images/maven-feather.png" />
</a>
</div>
</td>
<td class="content">
<!-- Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License. -->
<div class="section">
<h2><a name="Log4j_2_API"></a>Log4j 2 API</h2>
<div class="section">
<h3><a name="Thread_Context"></a>Thread Context</h3>
<div class="section">
<h4><a name="Introduction"></a>Introduction</h4>
<p>Log4j introduced the concept of the Mapped Diagnostic Context or MDC. It has been documented and
discussed in numerous places including
<a class="externalLink" href="http://veerasundar.com/blog/2009/10/log4j-mdc-mapped-diagnostic-context-what-and-why/">Log4j MDC: What and Why</a> and
<a class="externalLink" href="http://blog.f12.no/wp/2004/12/09/log4j-and-the-mapped-diagnostic-context/">Log4j and the Mapped Diagnostic Context</a>.
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
<a class="externalLink" href="http://lstierneyltd.com/blog/development/log4j-nested-diagnostic-contexts-ndc/">Log4j NDC</a>.
SLF4J/Logback followed with its own implementation of the MDC, which is documented very well at
<a class="externalLink" href="http://logback.qos.ch/manual/mdc.html">Mapped Diagnostic Context</a>.
</p>
<p>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.
</p>
</div>
<div class="section">
<h4><a name="Fish_Tagging"></a>Fish Tagging</h4>
<p>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.
</p>
<p>A lighter technique is to uniquely stamp each log request initiated from the same client interaction.
Neil Harrison described this method in the book &quot;Patterns for Logging Diagnostic Messages,&quot; in <i>Pattern
Languages of Program Design 3</i>, 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 <i>Fish Tagging</i>.
</p>
<p>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.
</p>
<p>To uniquely stamp each request using the Thread Context Stack, the user pushes contextual information
on to the Stack.
</p>
<div>
<pre class="prettyprint linenums">
ThreadContext.push(UUID.randomUUID().toString()); // Add the fishtag;
logger.debug(&quot;Message 1&quot;);
.
.
.
logger.debug(&quot;Message 2&quot;);
.
.
ThreadContext.pop();</pre></div>
<p>
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:
</p>
<div>
<pre class="prettyprint linenums">
ThreadContext.put(&quot;id&quot;, UUID.randomUUID().toString(); // Add the fishtag;
ThreadContext.put(&quot;ipAddress&quot;, request.getRemoteAddr());
ThreadContext.put(&quot;loginId&quot;, session.getAttribute(&quot;loginId&quot;));
ThreadContext.put(&quot;hostName&quot;, request.getServerName());
.
logger.debug(&quot;Message 1&quot;);
.
.
logger.debug(&quot;Message 2&quot;);
.
.
ThreadContext.clear();</pre></div>
<p>The Stack and the Map are managed per thread and are based on
<a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/lang/ThreadLocal.html">ThreadLocal</a>
by default. The Map can be configured to use an
<a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/lang/InheritableThreadLocal.html">InheritableThreadLocal</a>
by setting system property <tt>isThreadContextMapInheritable</tt> to <tt>&quot;true&quot;</tt>.
When configured this way, the contents of the Map will be passed to child threads. However, as
discussed in the
<a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/util/concurrent/Executors.html#privilegedThreadFactory()">Executors</a>
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.
</p>
<p>
Note that all methods of the
<a href="../log4j-api/apidocs/org/apache/logging/log4j/ThreadContext.html">ThreadContext</a>
class are static.
</p>
</div>
<div class="section">
<h4><a name="Including_the_ThreadContext_when_writing_logs"></a>Including the ThreadContext when writing logs</h4>
<p>
The <a href="../log4j-api/apidocs/org/apache/logging/log4j/core/PatternLayout.html">PatternLayout</a>
provides mechanisms to print the contents of the
<a href="../log4j-api/apidocs/org/apache/logging/log4j/ThreadContext.html">ThreadContext</a>
Map and Stack.
</p>
<ul>
<li>
Use <tt>%X</tt> by itself to include the full contents of the Map.
</li>
<li>
Use <tt>%X{key}</tt> to include the specified key.
</li>
<li>
Use <tt>%x</tt> to include the full contents of the <a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/util/Stack.html">Stack</a>.
</li>
</ul>
</div></div>
</div>
</td>
</tr>
</table>
</div>
<div class="footer">
<p>Copyright &copy; 1999-2015 <a class="external" href="http://www.apache.org">Apache Software Foundation</a>. All Rights Reserved.</p>
<p>Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p>
<p>Site powered by <a class="external" href="http://getbootstrap.com/">Twitter Bootstrap</a>. Icons from <a class="external" href="http://glyphicons.com/">Glyphicons Free</a>.</p>
</div>
</div>
</body>
</html>