| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <!-- Generated by Apache Maven Doxia at Apr 12, 2013 --> |
| <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> |
| Apache log4net Manual: Contexts</title> |
| <style type="text/css" media="all"> |
| @import url("../../css/maven-base.css"); |
| @import url("../../css/maven-theme.css"); |
| @import url("../../css/site.css"); |
| </style> |
| <link rel="stylesheet" href="../../css/print.css" type="text/css" media="print" /> |
| <meta name="author" content="Nicko Cadell" /> |
| <meta name="Date-Revision-yyyymmdd" content="20130412" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| <meta name="keywords" content="building log4net, log4net" /> |
| </head> |
| <body class="composite"> |
| <div id="banner"> |
| <a href="../../../" id="bannerLeft"> |
| <img src="../../images/ls-logo.jpg" alt="Apache Logging Services Project" /> |
| </a> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="breadcrumbs"> |
| |
| |
| <div class="xleft"> |
| <span id="publishDate">Last Published: 2013-04-12</span> |
| | <span id="projectVersion">Version: 1.2.12-SNAPSHOT</span> |
| | <a href="http://www.apache.org/" class="externalLink" title="Apache">Apache</a> |
| > |
| <a href="../../../" title="Logging Services">Logging Services</a> |
| > |
| <a href="../.././" title="log4net">log4net</a> |
| > |
| |
| Apache log4net Manual: Contexts |
| </div> |
| <div class="xright"> |
| |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="leftColumn"> |
| <div id="navcolumn"> |
| |
| |
| <h5>Apache log4net</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../index.html" title="About">About</a> |
| </li> |
| <li class="none"> |
| <a href="../../download_log4net.cgi" title="Download">Download</a> |
| </li> |
| <li class="none"> |
| <a href="../../release/release-notes.html" title="Release Notes">Release Notes</a> |
| </li> |
| <li class="none"> |
| <a href="../../license.html" title="License">License</a> |
| </li> |
| </ul> |
| <h5>Documentation</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../release/features.html" title="Features">Features</a> |
| </li> |
| <li class="none"> |
| <a href="../../release/framework-support.html" title="Supported Frameworks">Supported Frameworks</a> |
| </li> |
| <li class="none"> |
| <a href="../../release/example-apps.html" title="Example Apps">Example Apps</a> |
| </li> |
| <li class="none"> |
| <a href="../../release/config-examples.html" title="Config Examples">Config Examples</a> |
| </li> |
| <li class="none"> |
| <a href="../../release/building.html" title="Building">Building</a> |
| </li> |
| <li class="none"> |
| <a href="../../release/faq.html" title="FAQ">FAQ</a> |
| </li> |
| <li class="none"> |
| <a href="../../release/howto/index.html" title="How Tos">How Tos</a> |
| </li> |
| <li class="none"> |
| <a href="../../release/sdk/index.html" title="SDK Reference">SDK Reference</a> |
| </li> |
| </ul> |
| <h5>Manual</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../release/manual/introduction.html" title="Introduction">Introduction</a> |
| </li> |
| <li class="none"> |
| <a href="../../release/manual/configuration.html" title="Configuration">Configuration</a> |
| </li> |
| <li class="none"> |
| <strong>Contexts</strong> |
| </li> |
| <li class="none"> |
| <a href="../../release/manual/plugins.html" title="Plugins">Plugins</a> |
| </li> |
| <li class="none"> |
| <a href="../../release/manual/repositories.html" title="Repositories">Repositories</a> |
| </li> |
| <li class="none"> |
| <a href="../../release/manual/internals.html" title="Internals">Internals</a> |
| </li> |
| </ul> |
| <h5>Community</h5> |
| <ul> |
| <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> |
| </ul> |
| <h5>Development</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../source-repository.html" title="Repository">Repository</a> |
| </li> |
| <li class="none"> |
| <a href="../../integration.html" title="Continuous Integration">Continuous Integration</a> |
| </li> |
| </ul> |
| <h5>Project Documentation</h5> |
| <ul> |
| <li class="collapsed"> |
| <a href="../../project-info.html" title="Project Information">Project Information</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../../project-reports.html" title="Project Reports">Project Reports</a> |
| </li> |
| </ul> |
| <h5>Apache</h5> |
| <ul> |
| <li class="none"> |
| <a href="http://www.apache.org/" class="externalLink" title="Home">Home</a> |
| </li> |
| <li class="none"> |
| <a href="http://www.apache.org/licenses/" class="externalLink" title="License">License</a> |
| </li> |
| <li class="none"> |
| <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship">Sponsorship</a> |
| </li> |
| <li class="none"> |
| <a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks">Thanks</a> |
| </li> |
| <li class="none"> |
| <a href="http://www.apache.org/security/" class="externalLink" title="Security">Security</a> |
| </li> |
| <li class="none"> |
| <a href="http://www.apachecon.com" class="externalLink" title="Conferences">Conferences</a> |
| </li> |
| </ul> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> |
| <img class="poweredBy" alt="Built by Maven" src="../../images/logos/maven-feather.png" /> |
| </a> |
| |
| |
| </div> |
| </div> |
| <div id="bodyColumn"> |
| <div id="contentBox"> |
| <!-- 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. --> |
| |
| |
| <a name="main"></a><div class="section"><h2 id="main">Apache log4net™ Manual - Contexts</h2> |
| <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. An approach to differentiate the |
| logging output of one client from another is to instantiate a new separate |
| logger for each client. However 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. |
| </p> |
| <p> |
| Log4net supports different types of contextual logging and contexts with different scopes. |
| </p> |
| |
| <a name="scopes"></a><div class="section"><h2 id="scopes">Scopes</h2> |
| <p> |
| Contextual data can be set in different scopes. These contexts have progressively narrower visibility. |
| In the logging event itself the values from all of the contexts are combined together such that |
| values specified in a lower scoped context hide values from a higher context. |
| </p> |
| |
| <div class="table"> |
| <table border="0" class="bodyTable"> |
| <tr class="a"> |
| <th>Scope</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr class="b" align="left"> |
| <td>Global</td> |
| <td><span class="code">log4net.GlobalContext</span></td> |
| <td> |
| The global context is shared by all threads in the current AppDomain. |
| This context is thread safe for use by multiple threads concurrently. |
| </td> |
| </tr> |
| <tr class="a" align="left"> |
| <td>Thread</td> |
| <td><span class="code">log4net.ThreadContext</span></td> |
| <td> |
| The thread context is visible only to the current managed thread. |
| </td> |
| </tr> |
| <tr class="b" align="left"> |
| <td>Logical Thread</td> |
| <td><span class="code">log4net.ThreadLogicalContext</span></td> |
| <td> |
| The logical thread context is visible to a logical thread. Logical |
| threads can jump from one managed thread to another. For more details |
| see the .NET API <span class="code">System.Runtime.Remoting.Messaging.CallContext</span>. |
| </td> |
| </tr> |
| <tr class="a" align="left"> |
| <td>Event</td> |
| <td><span class="code">log4net.Core.LoggingEvent</span></td> |
| <td> |
| Each event captures the current contextual state at the time the event |
| is generated. Contextual data can be set on the event itself. This context |
| is only visible to the code generating the event itself. |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| |
| <a name="properties"></a><div class="section"><h2 id="properties">Context Properties</h2> |
| <p> |
| The log4net contexts store properties, i.e. name value pairs. The name is a string |
| the value is any object. A property can be set as follows: |
| </p> |
| <div class="source"><pre> |
| log4net.GlobalContext.Properties["name"] = value; |
| </pre></div> |
| <p> |
| If properties with the same name are set in more than one context scope then |
| the value in the narrowest scope (lower down in the list above) will hide the |
| other values. |
| </p> |
| <p> |
| The property values are stored as objects within the <span class="code">LoggingEvent</span>. |
| The <span class="code">PatternLayout</span> supports rendering the value of a named |
| property using the <span class="code">%property{name}</span> syntax. The value is |
| converted to a string by passing it to the <span class="code">log4net.ObjectRenderer.RendererMap</span> |
| which will locate any custom renderer for the value type. The default behavior for |
| custom types is to call the object's <span class="code">ToString()</span> method. |
| </p> |
| |
| <a name="active"></a><div class="section"><h2 id="active">Active Property Values</h2> |
| <p> |
| An active property value is one who's value changes over time. |
| </p> |
| <p> |
| For example, imagine a custom type that implemented the |
| <span class="code">ToString()</span> method to return the |
| number of bytes allocated by the runtime garbage collector. |
| </p> |
| <div class="source"><pre> |
| public class GCAllocatedBytesHelper |
| { |
| public override string ToString() |
| { |
| return GC.GetTotalMemory(true).ToString(); |
| } |
| }</pre></div> |
| <p> |
| An instance of this type can be added to the <span class="code">log4net.GlobalContext</span> |
| during application startup: |
| </p> |
| <div class="source"><pre> |
| log4net.GlobalContext.Properties["GCAllocatedBytes"] = new GCAllocatedBytesHelper(); |
| </pre></div> |
| <p> |
| Once this property is set in the context all subsequent logging events will have a property |
| called <i>GCAllocatedBytes</i>. The value of the property will be an instance of the |
| <span class="code">GCAllocatedBytesHelper</span> type. When this value is rendered to a |
| string by calling the <span class="code">ToString</span> method the current number of bytes |
| allocated by the garbage collector will be returned and included in the output. |
| </p> |
| |
| </div> |
| |
| </div> |
| |
| <a name="stacks"></a><div class="section"><h2 id="stacks">Context Stacks</h2> |
| <p> |
| Sometimes simple key value pairs are not the most convenient way of capturing contextual |
| information. A stack of information is a very convenient way of storing data especially |
| as our applications tend to be stack based. |
| </p> |
| <p> |
| The <span class="code">ThreadContext</span> and <span class="code">LogicalThreadContext</span> |
| also support storing contextual data in a stack. The stack is stored in context property, |
| therefore stacks have names and more than one stack can exist in the same context. A property |
| value set in a narrower context would override a stack with the same property name set in a |
| wider scoped context. |
| </p> |
| <p> |
| The stack supports <span class="code">Push</span> and <span class="code">Pop</span> methods. |
| As more contextual data is pushed onto the stack the stack grows. When the stack is rendered |
| all the data pushed onto the stack is output with the most recent data to the right hand |
| end of the string. |
| </p> |
| <p> |
| As the stack is just an object stored in the context properties it is also rendered |
| using the same <span class="code">PatternLayout</span> syntax: <span class="code">%property{name}</span>. |
| Where <i>name</i> is the name of the stack. |
| </p> |
| <p> |
| Calls the the stack's <span class="code">Push</span> and <span class="code">Pop</span> |
| methods must be matched up so that each push has a corresponding pop. The |
| <span class="code">Push</span> method also returns an <span class="code">IDisposable</span> |
| object that will perform the required pop operation when it is disposed. This allows |
| the C# <i>using</i> syntax to be used to automate the stack management. |
| </p> |
| <div class="source"><pre> |
| using(log4net.ThreadContext.Stacks["NDC"].Push("context")) |
| { |
| log.Info("Message"); |
| } |
| </pre></div> |
| <p> |
| The INFO level log has a stack stored in its <i>NDC</i> property. The top item in the |
| stack is the string <i>context</i>. |
| The <i>using</i> syntax ensures that the value <i>context</i> is popped off the stack |
| at the end of the block. |
| </p> |
| <p> |
| The <span class="code">using</span> |
| syntax is recommended because it removes some work load from the developer and |
| reduces errors in matching up the Push and Pop calls, especially when exceptions |
| can occur. |
| </p> |
| </div> |
| |
| <a name="ndc"></a><div class="section"><h2 id="ndc">Nested Diagnostic Contexts</h2> |
| <p> |
| The <span class="code">NDC</span> (Nested Diagnostic Context) exists for compatibility |
| with older versions of log4net. This helper class implements a stack which is stored |
| in the thread context property named <i>NDC</i>. |
| </p> |
| </div> |
| |
| <a name="mdc"></a><div class="section"><h2 id="mdc">Mapped Diagnostic Contexts</h2> |
| <p> |
| The <span class="code">MDC</span> (MappedDiagnostic Context) exists for compatibility |
| with older versions of log4net. This helper class implements a properties map which is |
| mapped directly through to the thread context properties. |
| </p> |
| </div> |
| |
| <p> |
| To illustrate this point, let us take the example of a web service delivering |
| content to numerous clients. The web service can build the <span class="code">NDC</span> at the very |
| beginning of the request before executing other code. The contextual |
| information can be the client's host name and other information inherent to the |
| request, typically information contained in cookies. Hence, even if the web |
| service is serving multiple clients simultaneously, the logs initiated by the |
| same code, i.e. belonging to the same logger, can still be distinguished |
| because each client request will have a different <span class="code">NDC</span> stack. Contrast this with |
| the complexity of passing a freshly instantiated logger to all code exercised |
| during the client's request. |
| </p> |
| <p> |
| Nevertheless, some sophisticated applications, such as virtual hosting web |
| servers, must log differently depending on the virtual host context and also |
| depending on the software component issuing the request. Log4net supports |
| multiple logger repositories. This would allow each virtual host to possess its own copy |
| of the logger hierarchy. Configuring multiple logger hierarchies is beyond the |
| scope of this document. |
| </p> |
| |
| </div> |
| |
| |
| </div> |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| <div id="footer"> |
| <div class="xright"> |
| <div class="xright">Copyright © 2004-2013 |
| <a href="http://www.apache.org">Apache Software Foundation</a>. |
| |
| |
| Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache Software License, Version 2.0</a>.</div><br /> |
| <div class="xright">Apache log4net, Apache, log4net, the Apache feather logo, the Apache Logging Services project logo and the Built by Maven logo are trademarks of The Apache Software Foundation.</div> |
| <div class="clear"> |
| </div> |
| </div> |
| </body> |
| </html> |