logging-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bode...@apache.org
Subject svn commit: r886052 [11/28] - in /websites/production/logging/content/log4net/log4net-1.2.13: ./ css/ images/ images/logos/ release/ release/howto/ release/manual/ release/sdk/ release/sdk/ndoc_msdn_temp/ release/sdk/ndoc_resources/
Date Sun, 10 Nov 2013 08:25:14 GMT
Added: websites/production/logging/content/log4net/log4net-1.2.13/release/manual/contexts.html
==============================================================================
--- websites/production/logging/content/log4net/log4net-1.2.13/release/manual/contexts.html (added)
+++ websites/production/logging/content/log4net/log4net-1.2.13/release/manual/contexts.html Sun Nov 10 08:24:41 2013
@@ -0,0 +1,425 @@
+<!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 Nov 10, 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="20131110" />
+    <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-11-10</span>
+                  &nbsp;| <span id="projectVersion">Version: 1.2.13</span>
+                          |                           <a href="http://www.apache.org/" class="externalLink" title="Apache">Apache</a>
+        &gt;
+                          <a href="../../../" title="Logging Services">Logging Services</a>
+        &gt;
+                          <a href="../.././" title="log4net">log4net</a>
+        &gt;
+    
+        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&#x2122; 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[&quot;name&quot;] = 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[&quot;GCAllocatedBytes&quot;] = 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[&quot;NDC&quot;].Push(&quot;context&quot;))
+{
+    log.Info(&quot;Message&quot;);
+}
+</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 &#169;                    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>

Propchange: websites/production/logging/content/log4net/log4net-1.2.13/release/manual/contexts.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: websites/production/logging/content/log4net/log4net-1.2.13/release/manual/internals.html
==============================================================================
--- websites/production/logging/content/log4net/log4net-1.2.13/release/manual/internals.html (added)
+++ websites/production/logging/content/log4net/log4net-1.2.13/release/manual/internals.html Sun Nov 10 08:24:41 2013
@@ -0,0 +1,439 @@
+<!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 Nov 10, 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: Internals</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="20131110" />
+    <meta http-equiv="Content-Language" content="en" />
+        <meta name="keywords" content="log4net internals, 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-11-10</span>
+                  &nbsp;| <span id="projectVersion">Version: 1.2.13</span>
+                          |                           <a href="http://www.apache.org/" class="externalLink" title="Apache">Apache</a>
+        &gt;
+                          <a href="../../../" title="Logging Services">Logging Services</a>
+        &gt;
+                          <a href="../.././" title="log4net">log4net</a>
+        &gt;
+    
+        Apache log4net Manual: Internals
+              </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">
+                          <a href="../../release/manual/contexts.html" title="Contexts">Contexts</a>
+            </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">
+            <strong>Internals</strong>
+          </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&#x2122; Manual - Internals</h2>
+            <a name="perf"></a><div class="section"><h2 id="perf">Performance</h2>
+                <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 was spent measuring and tweaking logging 
+                    performance. Log4net claims to be fast and flexible: speed first, flexibility 
+                    second.
+                </p>
+                <p>
+                    The user should be aware of the following performance issues.
+                </p>
+                <ol style="list-style-type: decimal">
+                    <li>
+                        <b>Logging performance when logging is turned off.</b>
+                        <p>
+                            When logging is turned off entirely or just for a set of levels, the cost of a 
+                            log request consists of a method invocation plus an integer comparison.
+                        </p>
+                        <p>
+                            However, The method invocation involves the &quot;hidden&quot; cost of parameter 
+                            construction.
+                        </p>
+                        <p>
+                            For example, for some logger
+                            <span class="code">log</span>, writing,
+                        </p>
+                        <div class="syntax"><div class="code"><pre>
+log.Debug(&quot;Entry number: &quot; + i + &quot; is &quot; + entry[i].ToString());</pre></div></div>
+                        <p>
+                            incurs the cost of constructing the message parameter, i.e. converting both 
+                            integer
+                            <span class="code">i</span>
+                            and
+                            <span class="code">entry[i]</span>
+                            to strings, and concatenating intermediate strings, regardless of whether the 
+                            message will be logged or not. This cost of parameter construction can be quite 
+                            high and it depends on the number and type of the parameters involved.
+                        </p>
+                        <p>
+                            To avoid the parameter construction cost write:
+                        </p>
+                        <div class="syntax"><div class="code"><pre>
+if(log.IsDebugEnabled)
+{
+    log.Debug(&quot;Entry number: &quot; + i + &quot; is &quot; + entry[i].ToString());
+}</pre></div></div>
+                        <p>
+                            This will not incur the cost of parameter construction if debugging is 
+                            disabled. On the other hand, if the logger is debug-enabled, it will incur 
+                            twice the cost of evaluating whether the logger is enabled or not: once in
+                            <span class="code">IsDebugEnabled</span>
+                            and once in
+                            <span class="code">Debug</span>. This is an insignificant overhead because 
+                            evaluating a logger takes about 1% of the time it takes to actually log.
+                        </p>
+                        <p>
+                            Certain users resort to pre-processing or compile-time techniques to compile 
+                            out all log statements. This leads to perfect performance efficiency with 
+                            respect to logging. However, since the resulting application binary does not 
+                            contain any log statements, logging cannot be turned on for that binary. In 
+                            many people's opinion this is a disproportionate price to pay in exchange for a 
+                            small performance gain.
+                        </p>
+                    </li>
+                    <li>
+                        <b>The performance of deciding whether to log or not to log when logging is 
+                            turned on.</b>
+                        <p>
+                            This is essentially the performance of walking the logger hierarchy. When 
+                            logging is turned on, log4net still needs to compare the level of the log 
+                            request with the level of the request logger. However, loggers may not have an 
+                            assigned level; they can inherit them from the logger hierarchy. Thus, before 
+                            inheriting a level, the logger may need to search its ancestors.
+                        </p>
+                        <p>
+                            There has been a serious effort to make this hierarchy walk to be as fast as 
+                            possible. For example, child loggers link only to their existing ancestors. In 
+                            the
+                            <span class="code">BasicConfigurator</span>
+                            example shown earlier, the logger named
+                            <span class="code">Com.Foo.Bar</span>
+                            is linked directly to the <i>root</i> logger, thereby circumventing the nonexistent
+                            <span class="code">Com</span>
+                            or
+                            <span class="code">Com.Foo</span>
+                            loggers. This significantly improves the speed of the walk, especially in 
+                            &quot;sparse&quot; hierarchies.
+                        </p>
+                        <p>
+                            The typical cost of walking the hierarchy is typically 3 times slower than when 
+                            logging is turned off entirely.
+                        </p>
+                    </li>
+                    <li>
+                        <b>Actually outputting log messages</b>
+                        <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.
+                        </p>
+                    </li>
+                </ol>
+                <p>
+                    Although log4net has many features, its first design goal was speed. Some 
+                    log4net components have been rewritten many times to improve performance. 
+                    Nevertheless, contributors frequently come up with new optimizations. You 
+                    should be pleased to know that when configured with the
+                    <span class="code">SimpleLayout</span>
+                    performance tests have shown log4net to log within an order of magnitude of
+                    <span class="code">System.Console.WriteLine</span>.
+                </p>
+            </div>
+
+            <a name="flow"></a><div class="section"><h2 id="flow">Logging Event Flow</h2>
+                <p>
+                    The following is the series of steps and checks that a messages goes through while being logged.
+                    For the purposes of this example we will document an <span class="code">INFO</span> level
+                    message being logged on logger <i>ConsoleApp.LoggingExample</i>. This logger is configured
+                    to use the <span class="code">log4net.Appender.ConsoleAppender</span>. The repository used
+                    in this example is a <span class="code">log4net.Repository.Hierarchy</span> object.
+                </p>
+                <ol style="list-style-type: decimal">
+                    <li>
+                        <p>
+                            The user logs a message using the <span class="code">ILog.Info</span> method on the logger
+                            obtained using a call to <span class="code">log4net.LogManager.GetLogger(&quot;ConsoleApp.LoggingExample&quot;)</span>.
+                            For example: <span class="code">log4net.LogManager.GetLogger(&quot;ConsoleApp.LoggingExample&quot;).Info(&quot;Application Start&quot;);</span>
+                            The <span class="code">ILog</span> interface is actually an extension to log4net that provides level 
+                            specific logging methods (i.e. Debug, Info, Warn, Error, and Fatal).
+                        </p>
+                    </li>
+                    <li>
+                        <p>
+                            The message is then logged through to the <span class="code">ILogger.Log</span> method on the 
+                            appropriate <span class="code">log4net.Repository.Hierarchy.Logger</span> object. The 
+                            <span class="code">ILogger.Log</span> method takes the <span class="code">Level</span> to
+                            log at as a parameter and therefore works for all levels.
+                        </p>
+                    </li>
+                    <li>
+                        <p>
+                            The repository threshold level is compared to the message level to determine if the message 
+                            can be logged. If the message level is below the threshold level the message is not logged.
+                            In this case the repository is a <span class="code">log4net.Repository.Hierarchy</span> object.
+                        </p>
+                    </li>
+                    <li>
+                        <p>
+                            The <span class="code">Logger</span> level is compared to the message level to determine if the 
+                            message can be logged. Note that the <span class="code">Logger</span> level is inherited from a 
+                            parent <span class="code">Logger</span> if not specified explicitly for this <span class="code">Logger</span>.
+                            If the message level is below the <span class="code">Logger</span> level the message is not logged.
+                        </p>
+                    </li>
+                    <li>
+                        <p>
+                            A <span class="code">LoggingEvent</span> instance is created to encapsulate the message being logged.
+                        </p>
+                    </li>
+                    <li>
+                        <p>
+                            The list of appenders for the <span class="code">Logger</span> is built. This includes appenders 
+                            attached to parent <span class="code">Logger</span>s except where excluded by the 
+                            <span class="code">Logger.Additivity</span> property.
+                        </p>
+                    </li>
+                    <li>
+                        <p>
+                            The <span class="code">LoggingEvent</span> object is passed to the 
+                            <span class="code">IAppender.DoAppend</span> method for each appender.
+                        </p>
+                    </li>
+                </ol>
+                <p>
+                    For Each Appender that the <span class="code">LoggingEvent</span> is delivered to the following
+                    actions take place:
+                </p>
+                <ol style="list-style-type: decimal">
+                    <li>
+                        <p>
+                            The appender threshold level is compared to the message level to determine if the message 
+                            can be logged. If the message level is below the threshold level the message is not logged.
+                        </p>
+                    </li>
+                    <li>
+                        <p>
+                            If the appender has a filter chain the <span class="code">LoggingEvent</span> is passed down the 
+                            filter chain which can decide if the message can be logged or not.
+                        </p>
+                    </li>
+                    <li>
+                        <p>
+                            Next an appender specific check is performed. Usually this check will verify that all the 
+                            required properties are set for the appender (e.g. a <span class="code">Layout</span> is set if required).
+                        </p>
+                    </li>
+                    <li>
+                        <p>
+                            The <span class="code">LoggingEvent</span> is passed to the appender specific 
+                            <span class="code">Append</span> method. What happens now is specific to the appender.
+                        </p>
+                    </li>
+                </ol>
+                <p>
+                    The following actions take place in the <span class="code">ConsoleAppender.Append</span> method:
+                </p>
+                <ol style="list-style-type: decimal">
+                    <li>
+                        <p>
+                            The <span class="code">ConsoleAppender</span> uses a <span class="code">Layout</span> to 
+                            format the message as a string for display.
+                        </p>
+                    </li>
+                    <li>
+                        <p>
+                            The <span class="code">Layout</span> uses the <span class="code">LoggingEvent.RenderedMessage</span>
+                            property to get the string for the message object. This uses the registered 
+                            <span class="code">IObjectRenderer</span> for the type of the message object.
+                        </p>
+                    </li>
+                    <li>
+                        <p>
+                            The message text is displayed on the console using the <span class="code">Console.WriteLine</span> method.
+                        </p>
+                    </li>
+                </ol>
+            </div>
+
+        </div>
+    
+
+      </div>
+    </div>
+    <div class="clear">
+      <hr/>
+    </div>
+    <div id="footer">
+      <div class="xright">
+        <div class="xright">Copyright &#169;                    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>

Propchange: websites/production/logging/content/log4net/log4net-1.2.13/release/manual/internals.html
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message