Added: logging/log4net/site/release/manual/contexts.html
URL:
http://svn.apache.org/viewvc/logging/log4net/site/release/manual/contexts.html?rev=1244132&view=auto
==============================================================================
--- logging/log4net/site/release/manual/contexts.html (added)
+++ logging/log4net/site/release/manual/contexts.html Tue Feb 14 17:10:54 2012
@@ -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 Feb 14, 2012 -->
+<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="20120214" />
+ <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: 2012-02-14</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-2012
+ <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: logging/log4net/site/release/manual/contexts.html
------------------------------------------------------------------------------
svn:executable = *
Added: logging/log4net/site/release/manual/internals.html
URL:
http://svn.apache.org/viewvc/logging/log4net/site/release/manual/internals.html?rev=1244132&view=auto
==============================================================================
--- logging/log4net/site/release/manual/internals.html (added)
+++ logging/log4net/site/release/manual/internals.html Tue Feb 14 17:10:54 2012
@@ -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 Feb 14, 2012 -->
+<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="20120214" />
+ <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: 2012-02-14</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: 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™ 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
"hidden" 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("Entry number: " + i + " is " +
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("Entry number: " + i + " is " +
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
+ "sparse" 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("ConsoleApp.LoggingExample")</span>.
+ For example: <span
class="code">log4net.LogManager.GetLogger("ConsoleApp.LoggingExample").Info("Application
Start");</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 © 2004-2012
+ <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: logging/log4net/site/release/manual/internals.html
------------------------------------------------------------------------------
svn:executable = *
