You are viewing a plain text version of this content. The canonical link for it is here.
Posted to log4net-dev@logging.apache.org by ni...@apache.org on 2005/01/17 20:16:08 UTC
cvs commit: logging-log4net/xdocs/src/release/manual configuration.xml contexts.xml faq.xml introduction.xml plugins.xml repositories.xml
nicko 2005/01/17 11:16:08
Modified: xdocs/src/release building.xml config-examples.xml
features.xml framework-support.xml
xdocs/src/release/manual configuration.xml contexts.xml
faq.xml introduction.xml plugins.xml
repositories.xml
Log:
Updated docs to be in sync with code
Revision Changes Path
1.2 +90 -4 logging-log4net/xdocs/src/release/building.xml
Index: building.xml
===================================================================
RCS file: /home/cvs/logging-log4net/xdocs/src/release/building.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- building.xml 13 Feb 2004 19:04:19 -0000 1.1
+++ building.xml 17 Jan 2005 19:16:07 -0000 1.2
@@ -26,28 +26,114 @@
<body>
<section name="Building log4net">
<sectionMenu name="Contents" />
+
+ <p>
+ The log4net release builds are built using NAnt. Log4net can also be built
+ using Visual Studio .NET 2002 or 2003.
+ </p>
+ <p>
+ To build a release build of log4net you will need to create a strong
+ name key file. See the Strong Name section below.
+ </p>
<section name="Visual Studio .NET" id="id_1">
<p>
- TODO
+ Visual Studio .NET 2002 and 2003 are supported build platforms for log4net.
</p>
<section name="Visual Studio .NET 2002" id="id_2">
<p>
- TODO
+ The log4net distribution includes a solution and project file
+ for Visual Studio .NET 2002. Open the <span class="code">log4net.sln</span>
+ from the src directory in the distribution.
+ </p>
+ <p>
+ The log4net project requires only the following references:
</p>
+ <ul>
+ <li>System</li>
+ <li>System.Data</li>
+ <li>System.Web</li>
+ <li>System.XML</li>
+ </ul>
</section>
<section name="Visual Studio .NET 2003" id="id_3">
<p>
- TODO
+ Open the Visual Studio .NET 2002 solution file as above.
+ Visual Studio will convert the solution and project files
+ to Visual Studio .NET 2003 format.
+ </p>
+ <p>
+ The log4net project file is not suitable for building log4net
+ for the .NET Compact Framework. To build for the Compact Framework
+ you must create a new C# project for Smart Devices. Configure the
+ project as a library project. Add all the C# files from the
+ src directory in the distribution.
</p>
</section>
</section>
<section name="NAnt">
<p>
- TODO
+ The log4net distribution is built using the NAnt tool.
+ NAnt version 0.85 is required to build log4net, it is
+ available from <a href="http://nat.sourceforge.net">nant.sourceforge.net</a>.
+ </p>
+ <p>
+ To support building log4net for the SSCLI framework the NAnt configuration
+ files need to be updated to specify the SSCLI framework directory.
+ </p>
+ <p>
+ To build log4net from the command line, change directory to the root of the
+ log4net distribution, ensure that the nant executable is in the
+ PATH, and then run the following command:
+ </p>
+ <pre class="code">
+nant -buildfile:log4net.build compile-all
+ </pre>
+ <p>
+ This command will build log4net for all the supported frameworks
+ that are available on the current machine. To list all the build
+ targets that are available run the following command:
+ </p>
+ <pre class="code">
+nant -buildfile:log4net.build -projecthelp
+ </pre>
+ <p>
+ Under windows the <span class="code">build.cmd</span> can be used
+ to script the nant build. This can be called from a different
+ directory and will locate the correct log4net.build file to use.
+ For example:
+ </p>
+ <pre class="code">
+build.cmd compile-all
+ </pre>
+ </section>
+
+ <section name="Strong Name">
+ <p>
+ In order to build the Release builds of log4net a Strong
+ Name key is required.
+ </p>
+ <p>
+ Use the <span class="code">sn.exe</span> tool in the
+ .NET Framework SDK to generate a strong name key pair.
+ </p>
+ <pre class="code">
+sn -k log4net.snk
+ </pre>
+ <p>
+ The log4net.snk file should be placed in the root of the
+ log4net distribution, in the same folder as the log4net.build
+ file.
+ </p>
+ </section>
+
+ <section name="NDoc">
+ <p>
+ NDoc is used to build the log4net SDK documentation.
+ NDoc is available from <a href="http://ndoc.sourceforge.net">ndoc.sourceforge.net</a>.
</p>
</section>
1.4 +7 -7 logging-log4net/xdocs/src/release/config-examples.xml
Index: config-examples.xml
===================================================================
RCS file: /home/cvs/logging-log4net/xdocs/src/release/config-examples.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- config-examples.xml 15 Dec 2004 22:17:12 -0000 1.3
+++ config-examples.xml 17 Jan 2005 19:16:07 -0000 1.4
@@ -276,20 +276,20 @@
<parameter>
<parameterName value=":log_level" />
<layout type="log4net.Layout.PatternLayout">
- <conversionPattern value="%p" />
+ <conversionPattern value="%level" />
</layout>
</parameter>
<parameter>
<parameterName value=":logger" />
<layout type="log4net.Layout.PatternLayout">
- <conversionPattern value="%c" />
+ <conversionPattern value="%logger" />
</layout>
</parameter>
<parameter>
<parameterName value=":message" />
<dbType value="String" />
<layout type="log4net.Layout.PatternLayout">
- <conversionPattern value="%m" />
+ <conversionPattern value="%message" />
</layout>
</parameter>
</appender>
@@ -735,7 +735,7 @@
<threshold value="WARN"/>
</evaluator>
<layout type="log4net.Layout.PatternLayout">
- <conversionPattern value="%n%d [%t] %-5p %c [%x] - %m%n%n%n" />
+ <conversionPattern value="%newline%date [%thread] %-5level %logger [%ndc] - %message%newline%newline%newline" />
</layout>
</appender>
]]></source>
@@ -753,7 +753,7 @@
<bufferSize value="512" />
<lossy value="false" />
<layout type="log4net.Layout.PatternLayout">
- <conversionPattern value="%n%d [%t] %-5p %c [%x] - %m%n%n%n" />
+ <conversionPattern value="%newline%date [%thread] %-5level %logger [%ndc] - %message%newline%newline%newline" />
</layout>
</appender>
]]></source>
@@ -772,7 +772,7 @@
<threshold value="WARN" />
</evaluator>
<layout type="log4net.Layout.PatternLayout,log4net">
- <conversionPattern value="%P{log4net:HostName} :: %p :: %m %nLogger: %c%nThread: %t%nDate: %d%nNDC: %x%n%n" />
+ <conversionPattern value="%property{log4net:HostName} :: %level :: %message %newlineLogger: %logger%newlineThread: %thread%newlineDate: %date%newlineNDC: %ndc%newline%newline" />
</layout>
</appender>
]]></source>
@@ -845,7 +845,7 @@
<remoteAddress value="224.0.0.1" />
<remotePort value="8080" />
<layout type="log4net.Layout.PatternLayout, log4net">
- <conversionPattern value="%-5p %c [%x] - %m%n" />
+ <conversionPattern value="%-5level %logger [%ndc] - %message%newline" />
</layout>
</appender>
]]></source>
1.2 +44 -11 logging-log4net/xdocs/src/release/features.xml
Index: features.xml
===================================================================
RCS file: /home/cvs/logging-log4net/xdocs/src/release/features.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- features.xml 13 Feb 2004 19:04:19 -0000 1.1
+++ features.xml 17 Jan 2005 19:16:08 -0000 1.2
@@ -72,7 +72,7 @@
<li>Microsoft .Net Framework 1.0 (1.0.3705)</li>
<li>Microsoft .Net Framework 1.1 (1.1.4322)</li>
<li>Microsoft .Net Compact Framework 1.0 (1.0.5000)</li>
- <li>Mono 0.25 or higher</li>
+ <li>Mono 1.0</li>
<li>Microsoft Shared Source CLI 1.0</li>
</ul>
</section>
@@ -90,20 +90,32 @@
Description</th>
</tr>
<tr>
- <td>log4net.Appender.ADONetAppender</td>
+ <td>log4net.Appender.AdoNetAppender</td>
<td>
Writes logging events to a database using either prepared statements or stored
procedures.
</td>
</tr>
<tr>
- <td>log4net.Appender.ASPNetTraceAppender</td>
+ <td>log4net.Appender.AnsiColorTerminalAppender</td>
+ <td>
+ Writes color highlighted logging events to a an ANSI terminal window.
+ </td>
+ </tr>
+ <tr>
+ <td>log4net.Appender.AspNetTraceAppender</td>
<td>
Writes logging events to the ASP trace context. These can then be rendered at
the end of the ASP page or on the ASP trace page.
</td>
</tr>
<tr>
+ <td>log4net.Appender.ColoredConsoleAppender</td>
+ <td>
+ Writes color highlighted logging events to the application's Windows Console.
+ </td>
+ </tr>
+ <tr>
<td>log4net.Appender.ConsoleAppender</td>
<td>
Writes logging events to the application's Console. The events may go to either
@@ -123,6 +135,12 @@
</td>
</tr>
<tr>
+ <td>log4net.LocalSyslogAppender</td>
+ <td>
+ Writes logging events to the local syslog service (UNIX only).
+ </td>
+ </tr>
+ <tr>
<td>log4net.Appender.MemoryAppender</td>
<td>
Stores logging events in an in memory buffer.
@@ -144,6 +162,12 @@
</td>
</tr>
<tr>
+ <td>log4net.Appender.RemoteSyslogAppender</td>
+ <td>
+ Writes logging events to a remote syslog service using UDP networking.
+ </td>
+ </tr>
+ <tr>
<td>log4net.Appender.RemotingAppender</td>
<td>
Writes logging events to a remoting sink using .NET remoting.
@@ -158,12 +182,18 @@
</td>
</tr>
<tr>
- <td>log4net.Appender.SMTPAppender</td>
+ <td>log4net.Appender.SmtpAppender</td>
<td>
Sends logging events to an email address.
</td>
</tr>
<tr>
+ <td>log4net.Appender.TelnetAppender</td>
+ <td>
+ Clients connect via Telnet to receive logging events.
+ </td>
+ </tr>
+ <tr>
<td>log4net.Appender.TraceAppender</td>
<td>
Writes logging events to the .NET trace system.
@@ -185,7 +215,7 @@
<p>
Hierarchical logging is an ideal fit with component based development.
Each component has its own of logger. When individually tested, the
- properties of these categories may be set however the developer wishes.
+ properties of these loggers may be set as the developer requires.
When combined with other components, the loggers inherit the properties
determined by the integrator of the components. One can selectively elevate
logging priorities on one component without affecting the other components.
@@ -203,6 +233,9 @@
configuration is easily readable and updateable while retaining the
flexibility to express all configurations.
</p>
+ <p>
+ Alternatively log4net can be configured programmatically.
+ </p>
</section>
<section name="Dynamic Configuration">
@@ -219,12 +252,12 @@
<section name="Logging Context">
<p>
log4net can collect logging context data in a way that is transparent
- to the developer at the point of logging. The NDC (Nested Diagnostic Context)
- and the MDC (Mapped Diagnostic Context) capture contextual data and attach
- it to logging messages. For instance, in a web service, the
- authentication ID of the caller is stored in the MDC once the caller is
- authenticated. This ID is then logged as part of each logging message
- automatically.
+ to the developer at the point of logging. The GlobalContext and the
+ ThreadContext allow the application to capture contextual data and for it
+ to be attached to logging messages. For instance, in a web service,
+ once the caller is authenticated the username of the caller is can be
+ stored in a ThreadContext property. This property is then automatically
+ logged as part of each logging message.
</p>
</section>
1.2 +37 -5 logging-log4net/xdocs/src/release/framework-support.xml
Index: framework-support.xml
===================================================================
RCS file: /home/cvs/logging-log4net/xdocs/src/release/framework-support.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- framework-support.xml 13 Feb 2004 19:04:19 -0000 1.1
+++ framework-support.xml 17 Jan 2005 19:16:08 -0000 1.2
@@ -56,7 +56,7 @@
<td><a href="http://msdn.microsoft.com/vstudio/device/compactfx.asp">http://msdn.microsoft.com/vstudio/device/compactfx.asp</a></td>
</tr>
<tr style="vertical-align: top;">
- <td>Mono 0.25 or higher</td>
+ <td>Mono 1.0</td>
<td><a href="http://www.go-mono.org">http://www.go-mono.org</a></td>
</tr>
<tr style="vertical-align: top;">
@@ -94,7 +94,7 @@
<th>.NET Framework 1.0</th>
<th>.NET Framework 1.1</th>
<th>.NET Compact Framework 1.0</th>
- <th>Mono 0.25 or higher</th>
+ <th>Mono 1.0</th>
<th>Shared Source CLI 1.0</th>
</tr>
<tr>
@@ -106,6 +106,14 @@
<td></td>
</tr>
<tr>
+ <td>AnsiColorTerminalAppender</td>
+ <td>x</td>
+ <td>x</td>
+ <td>x</td>
+ <td>x</td>
+ <td>x</td>
+ </tr>
+ <tr>
<td>AspNetTraceAppender</td>
<td>x</td>
<td>x</td>
@@ -138,7 +146,7 @@
<td>x</td>
</tr>
<tr>
- <td>CountingAppender</td>
+ <td>DebugAppender</td>
<td>x</td>
<td>x</td>
<td>x</td>
@@ -170,6 +178,14 @@
<td>x</td>
</tr>
<tr>
+ <td>LocalSyslogAppender</td>
+ <td>x</td>
+ <td>x</td>
+ <td></td>
+ <td>x</td>
+ <td></td>
+ </tr>
+ <tr>
<td>MemoryAppender</td>
<td>x</td>
<td>x</td>
@@ -194,6 +210,14 @@
<td></td>
</tr>
<tr>
+ <td>RemoteSyslogAppender</td>
+ <td>x</td>
+ <td>x</td>
+ <td>x</td>
+ <td>x</td>
+ <td>x</td>
+ </tr>
+ <tr>
<td>RemotingAppender</td>
<td>x</td>
<td>x</td>
@@ -226,6 +250,14 @@
<td>x</td>
</tr>
<tr>
+ <td>TelnetAppender</td>
+ <td>x</td>
+ <td>x</td>
+ <td>x</td>
+ <td>x</td>
+ <td>x</td>
+ </tr>
+ <tr>
<td>TraceAppender</td>
<td>x</td>
<td>x</td>
@@ -263,7 +295,7 @@
<li>
<h4>Assembly attributes</h4>
<p>
- The .NET Compact Framework 1.0 does not support retrieving assembly-level
+ The .NET Compact Framework 1.0 does not support retrieving assembly level
attributes, therefore all log4net configuration attributes were removed from
the .NET Compact Framework 1.0 version of log4net.
</p>
@@ -379,7 +411,7 @@
</ul>
</section>
- <section name="Mono 0.25 or higher">
+ <section name="Mono 1.0">
<p>
none
</p>
1.3 +15 -2 logging-log4net/xdocs/src/release/manual/configuration.xml
Index: configuration.xml
===================================================================
RCS file: /home/cvs/logging-log4net/xdocs/src/release/manual/configuration.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- configuration.xml 12 Nov 2004 22:36:35 -0000 1.2
+++ configuration.xml 17 Jan 2005 19:16:08 -0000 1.3
@@ -1162,10 +1162,23 @@
<param name="evaluator" type="log4net.spi.LevelEvaluator">
<param name="Threshold" value="WARN"/>
<param>]]></source>
-
+
+ <section name="Extension Parameters">
+ <p>
+ Configuration parameters map directly to writable properties on an object.
+ The properties available depend on the actual type of the object being
+ configured. The log4net SDK documentation contains the API reference for
+ all the components included in the log4net assembly.
+ </p>
+ <p>
+ For 3rd party components please see their relevant API reference for
+ details of the properties available.
+ </p>
+ </section>
+
<section name="Compact Parameter Syntax">
<p>
- Parameters may also be specified using the parameter name as the element name
+ All parameters may alternately be specified using the parameter name as the element name
rather than using the <i>param</i> element and <i>name</i> attribute.
</p>
<p>
1.2 +188 -107 logging-log4net/xdocs/src/release/manual/contexts.xml
Index: contexts.xml
===================================================================
RCS file: /home/cvs/logging-log4net/xdocs/src/release/manual/contexts.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- contexts.xml 13 Feb 2004 19:04:19 -0000 1.1
+++ contexts.xml 17 Jan 2005 19:16:08 -0000 1.2
@@ -27,139 +27,220 @@
<section name="log4net Manual - Contexts">
<sectionMenu name="Contents" />
- <section name="Nested Diagnostic Contexts">
+ <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>
+
+ <section name="Scopes">
+ <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 cellspacing="0">
+ <tr>
+ <th>Scope</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr 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 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 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 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>
+ </section>
+
+ <section name="Context Properties">
<p>
- Most real-world systems have to deal with multiple clients simultaneously. In a
- typical multithreaded implementation of such a system, different threads will
- handle different clients. Logging is especially well suited to trace and debug
- complex distributed applications. A common approach to differentiate the
- logging output of one client from another is to instantiate a new separate
- logger for each client. This promotes the proliferation of loggers and
- increases the management overhead of logging.
- </p>
- <p>
- A lighter technique is to uniquely stamp each log request initiated from the
- same client interaction.
- </p>
- <p>
- To uniquely stamp each request, the user pushes contextual information into the
- <span class="code">NDC</span>, the abbreviation of <i>Nested Diagnostic Context</i>.
- The outline of the <span class="code">NDC</span> class is shown below.
+ 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>
<source language="c#"><![CDATA[
-namespace log4net
+log4net.GlobalContext.Properties["name"] = value;
+]]></source>
+ <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 behaviour for
+ custom types is to call the object's <span class="code">ToString()</span> method.
+ </p>
+
+ <section name="Active Property Values">
+ <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>
+ <source language="c#"><![CDATA[
+public class GCAllocatedBytesHelper
{
- public class NDC
- {
- /// Removes the top context from the stack.
- public static string Pop();
-
- /// Pushes a new context message.
- public static IDisposable Push(string message);
-
- /// Gets the current context information.
- internal static string Get();
- }
+ public override string ToString()
+ {
+ return GC.GetTotalMemory(true).ToString();
+ }
}]]></source>
- <p>
- The <span class="code">NDC</span> is managed per thread as a <i>stack</i> of contextual information. Note
- that all methods of the
- <span class="code">log4net.NDC</span>
- class are static. Assuming that <span class="code">NDC</span> printing is turned on, every time a log
- request is made, the appropriate log4net component will include the <i>entire</i>
- <span class="code">NDC</span> stack for the current thread in the log output. This is done without the
- intervention of the user, who is responsible only for placing the correct
- information in the <span class="code">NDC</span> by using the
- <span class="code">Push</span>
- and
- <span class="code">Pop</span>
- methods at a few well-defined points in the code. In contrast, the per-client
- logger approach commands extensive changes in the code.
- </p>
- <p>
- The
- <span class="code">NDC.Push</span>
- method returns an
- <span class="code">IDisposable</span>
- object that can be used to clean up the <span class="code">NDC</span> stack. This means that the user
- does not have to manually match up a
- <span class="code">Pop</span>
- call for each
- <span class="code">Push</span>
- call. The
- <span class="code">using</span>
- syntax can be used to modify the <span class="code">NDC</span> only for a specific block of code. For
- example:
- </p>
+ <p>
+ An instance of this type can be added to the <span class="code">log4net.GlobalContext</span>
+ during application startup:
+ </p>
<source language="c#"><![CDATA[
-NDC.Push("context");
-log.Info("Message");
-NDC.Pop();
+log4net.GlobalContext.Properties["GCAllocatedBytes"] = new GCAllocatedBytesHelper();
]]></source>
+ <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>
+
+ </section>
+
+ </section>
+
+ <section name="Context Stacks">
+ <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>
- Is equivalent to:
+ 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>
<source language="c#"><![CDATA[
-using(NDC.Push("context"))
+using(log4net.ThreadContext.Stacks["NDC"].Push("context"))
{
- log.Info("Message");
+ log.Info("Message");
}
]]></source>
<p>
- The
- <span class="code">using</span>
+ 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>
+ </section>
+
+ <section name="Nested Diagnostic Contexts">
<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 hierarchy trees. This allows each virtual host to possess its own copy
- of the logger hierarchy. Configuring multiple logger hierarchies is beyond the
- scope of this document.
+ 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>
</section>
<section name="Mapped Diagnostic Contexts">
<p>
- The <span class="code">MDC</span> (Mapped Diagnostic Context) is used to set thread specific named
- properties. These properties can be rendered by the
- <span class="code">PatternLayout</span>.
+ 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>
- <p>
- The outline of the <span class="code">MDC</span> class is shown below.
- </p>
- <source language="c#"><![CDATA[
-namespace log4net
-{
- public class MDC
- {
- /// Gets the context identified by the key parameter.
- public static string Get(string key);
-
- /// Puts a context value (the val parameter) as identified with
- /// the key parameter into the current thread's context map.
- public static void Set(string key, string value);
-
- /// Removes the key value mapping for the key specified.
- public static void Remove(string key);
- }
-}]]></source>
</section>
+
+ <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>
+
</section>
</body>
</document>
1.3 +17 -14 logging-log4net/xdocs/src/release/manual/faq.xml
Index: faq.xml
===================================================================
RCS file: /home/cvs/logging-log4net/xdocs/src/release/manual/faq.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- faq.xml 10 Jun 2004 12:45:52 -0000 1.2
+++ faq.xml 17 Jan 2005 19:16:08 -0000 1.3
@@ -38,13 +38,14 @@
In case of problems with an application, it is helpful to enable logging so
that the problem can be located. With log4net it is possible to enable logging at
runtime without modifying the application binary. The log4net package is designed
- so that log statements can remain in <i>shipped</i> code without incurring a
+ so that log statements can remain in <i>production</i> code without incurring a
high performance cost. It follows that the speed of logging (or rather not
logging) is crucial.
</p>
<p>
At the same time, log output can be so voluminous that it quickly becomes
- overwhelming. One of the distinctive features of log4net is the notion of <i>hierarchical
+ overwhelming. One of the distinctive features of log4net (and common to all of
+ the log4x libraries) is the notion of <i>hierarchical
loggers</i>. Using these loggers it is possible to selectively control
which log statements are output at arbitrary granularity.
</p>
@@ -75,7 +76,8 @@
output stream is not opened, is not writable or becomes full. This avoids
corrupting an otherwise working program by flooding the user's terminal because
logging fails. However, log4net will output a single message to
- <span class="code">System.Console.Error</span> indicating that logging can not be performed.
+ <span class="code">System.Console.Error</span> and <span>System.Diagnostics.Trace</span>
+ indicating that logging can not be performed.
</p>
</section>
<p><a href="#top">Back to Top</a></p>
@@ -125,7 +127,7 @@
<li>
log4net can direct its output to many sinks including: a file, the console, the NT EventLog or even e-mail.</li>
<li>
- log4net uses 5 levels, namely DEBUG, INFO, WARN, ERROR and FATAL.</li>
+ log4net categorizes logging into levels: DEBUG, INFO, WARN, ERROR and FATAL.</li>
<li>
The format of the log output can be easily changed by implementing a new layout class.</li>
<li>
@@ -186,8 +188,8 @@
<section name="What are Loggers?">
<p>
- The notion of loggers lies at the heart of log4net's configuration. Loggers define a
- hierarchy and give the programmer <em>run-time</em> control on which statements
+ The logger concept lies at the heart of log4net's configuration. Loggers are organized into a
+ hierarchy and give the programmer <em>run-time</em> control on which logging statements
are printed or not.
</p>
<p>
@@ -202,16 +204,17 @@
<p>
Contrary to the GNU Public License (GPL) the Apache Software License does not
make any claims over your extensions. By extensions, we mean totally new code
- that invokes existing log4net classes. <em>You are free to do whatever you wish with
+ that invokes existing log4net code. <em>You are free to do whatever you wish with
your proprietary log4net extensions.</em> In particular, you may choose to
- never release your extensions to the wider public.
+ never release your extensions to the wider public. For details see the
+ <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
</p>
<p>
- We are very careful not to change the log4net client API so that newer log4net
+ We are very careful not to unnecessarily change the log4net client API so that newer log4net
releases are backward compatible with previous versions. We are a lot less
scrupulous with the internal log4net API. Thus, if your extension is designed to
- work with log4net version <span class="code">n</span>, then when log4net release version <span class="code">n+1</span>
- comes out, you will probably need to adapt your proprietary extensions to the
+ work with the internals of a specific log4net version, then when the next release
+ of log4net comes out, you will probably need to adapt your proprietary extensions to the
new release. Thus, you will be forced to spend precious resources in order to
keep up with log4net changes. This is commonly referred to as the "stupid-tax".
By donating the code and making it part of the standard distribution, you save
@@ -536,8 +539,8 @@
So why exactly is this faster? Well to start with the <span class="code">IsDebugEnabled</span>
is not called for each log statement, it is called once per logger. Furthermore as the
<span class="code">isDebugEnabled</span> variable is <span class="code">private static readonly</span>
- the JIT compiler can at <em>run-time</em> optimize out the <span class="code">if</span> test altogether. This means that
- at runtime the JIT compiler won't even compile the logging statements into native code, i.e.
+ the JIT compiler can at <em>run-time</em> optimize out the <span class="code">if</span> test altogether.
+ This means that at runtime the JIT compiler won't even compile the logging statements into native code, i.e.
all the logging just disappears.
</p>
<p>
@@ -545,7 +548,7 @@
you can change the logging configuration while your program is running. If you need to
investigate an issue in your application, you don't have to stop the application, setup the
logging and restart the application, you can change the logging configuration and the
- log4net will reload it (see <span class="code">ConfigureAndWatch</span> APIs for more
+ log4net will reload it (see <span class="code">XmlConfigurator.ConfigureAndWatch</span> APIs for more
information). However if the JIT has compiled out all of the logging statements
then they are gone and you can't get them back by reloading the configuration file. Effectively
this means that the logging configuration can only be set when the application loads and
1.2 +73 -14 logging-log4net/xdocs/src/release/manual/introduction.xml
Index: introduction.xml
===================================================================
RCS file: /home/cvs/logging-log4net/xdocs/src/release/manual/introduction.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- introduction.xml 13 Feb 2004 19:04:19 -0000 1.1
+++ introduction.xml 17 Jan 2005 19:16:08 -0000 1.2
@@ -36,8 +36,8 @@
http://logging.apache.org/log4j</a> for more information on log4j.<br />
The log4net framework, source code, binaries, documentation, examples and related
materials are published under the terms of the
- Apache Software License version 1.1, a copy of which has been included with
- this distribution in the LICENSE.txt file.
+ <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>,
+ a copy of which has been included with this distribution in the LICENSE.txt file.
</p>
<p>
This document is an introduction to the log4net API, its unique features and
@@ -85,7 +85,7 @@
<li>Microsoft .Net Framework 1.0 (1.0.3705)</li>
<li>Microsoft .Net Framework 1.1 (1.1.4322)</li>
<li>Microsoft .Net Compact Framework 1.0 (1.0.5000)</li>
- <li>Mono 0.25</li>
+ <li>Mono 1.0</li>
<li>Microsoft Shared Source CLI 1.0</li>
</ul>
<p>
@@ -116,7 +116,7 @@
</p>
<p>
Loggers are named entities. Logger names are case-sensitive and they follow the
- hierarchical naming rule:
+ following hierarchical naming rule:
</p>
<dl class="rule">
<dt>Named Hierarchy</dt>
@@ -197,23 +197,40 @@
{
public interface ILog
{
+ /* Test if a level is enabled for logging */
+ bool IsDebugEnabled { get; }
+ bool IsInfoEnabled { get; }
+ bool IsWarnEnabled { get; }
+ bool IsErrorEnabled { get; }
+ bool IsFatalEnabled { get; }
+
+ /* Log a message object */
void Debug(object message);
void Info(object message);
void Warn(object message);
void Error(object message);
void Fatal(object message);
+ /* Log a message object and exception */
void Debug(object message, Exception t);
void Info(object message, Exception t);
void Warn(object message, Exception t);
void Error(object message, Exception t);
void Fatal(object message, Exception t);
-
- bool IsDebugEnabled { get; }
- bool IsInfoEnabled { get; }
- bool IsWarnEnabled { get; }
- bool IsErrorEnabled { get; }
- bool IsFatalEnabled { get; }
+
+ /* Log a message string using the System.String.Format syntax */
+ void DebugFormat(string format, params object[] args);
+ void InfoFormat(string format, params object[] args);
+ void WarnFormat(string format, params object[] args);
+ void ErrorFormat(string format, params object[] args);
+ void FatalFormat(string format, params object[] args);
+
+ /* Log a message string using the System.String.Format syntax */
+ void DebugFormat(IFormatProvider provider, string format, params object[] args);
+ void InfoFormat(IFormatProvider provider, string format, params object[] args);
+ void WarnFormat(IFormatProvider provider, string format, params object[] args);
+ void ErrorFormat(IFormatProvider provider, string format, params object[] args);
+ void FatalFormat(IFormatProvider provider, string format, params object[] args);
}
}]]></source>
<p>
@@ -557,6 +574,12 @@
</td>
</tr>
<tr>
+ <td>log4net.Appender.AnsiColorTerminalAppender</td>
+ <td>
+ Writes color highlighted logging events to a an ANSI terminal window.
+ </td>
+ </tr>
+ <tr>
<td>log4net.Appender.AspNetTraceAppender</td>
<td>
Writes logging events to the ASP trace context. These can then be rendered at
@@ -603,6 +626,12 @@
</td>
</tr>
<tr>
+ <td>log4net.LocalSyslogAppender</td>
+ <td>
+ Writes logging events to the local syslog service (UNIX only).
+ </td>
+ </tr>
+ <tr>
<td>log4net.Appender.MemoryAppender</td>
<td>
Stores logging events in an in memory buffer.
@@ -624,6 +653,12 @@
</td>
</tr>
<tr>
+ <td>log4net.Appender.RemoteSyslogAppender</td>
+ <td>
+ Writes logging events to a remote syslog service using UDP networking.
+ </td>
+ </tr>
+ <tr>
<td>log4net.Appender.RemotingAppender</td>
<td>
Writes logging events to a remoting sink using .NET remoting.
@@ -652,6 +687,12 @@
</td>
</tr>
<tr>
+ <td>log4net.Appender.TelnetAppender</td>
+ <td>
+ Clients connect via Telnet to receive logging events.
+ </td>
+ </tr>
+ <tr>
<td>log4net.Appender.TraceAppender</td>
<td>
Writes logging events to the .NET trace system.
@@ -790,7 +831,7 @@
<p>
More complex and custom event filtering can be done using the filter chain
defined on each appender. Filters must implement the
- <span class="code">IFilter</span>.
+ <span class="code">log4net.Filter.IFilter</span> interface.
</p>
<p>
The following filters are defined in the log4net package:
@@ -816,6 +857,18 @@
</td>
</tr>
<tr>
+ <td>log4net.Filter.LevelRangeFilter</td>
+ <td>
+ Matches against a range of levels.
+ </td>
+ </tr>
+ <tr>
+ <td>log4net.Filter.LoggerMatchFilter</td>
+ <td>
+ Matches against a the start of the logger name.
+ </td>
+ </tr>
+ <tr>
<td>log4net.Filter.MdcFilter</td>
<td>
Matches a substring from a specific <span class="code">MDC</span> value.
@@ -828,9 +881,9 @@
</td>
</tr>
<tr>
- <td>log4net.Filter.LevelRangeFilter</td>
+ <td>log4net.Filter.PropertyFilter</td>
<td>
- Matches against a range of levels.
+ Matches a substring from a specific property value.
</td>
</tr>
<tr>
@@ -862,7 +915,7 @@
</p>
<p>
For example, the PatternLayout with the conversion pattern
- <span class="code">"%r [%t] %-5p %c - %m%n"</span>
+ <span class="code">"%timestamp [%thread] %-5level %logger - %message%newline"</span>
will output something akin to:
</p>
<source language="text"><![CDATA[
@@ -903,6 +956,12 @@
<td>log4net.Layout.RawTimeStampLayout</td>
<td>
Extracts the timestamp from the logging event.
+ </td>
+ </tr>
+ <tr>
+ <td>log4net.Layout.RawUtcTimeStampLayout</td>
+ <td>
+ Extracts the timestamp from the logging event in Universal Time.
</td>
</tr>
<tr>
1.2 +1 -1 logging-log4net/xdocs/src/release/manual/plugins.xml
Index: plugins.xml
===================================================================
RCS file: /home/cvs/logging-log4net/xdocs/src/release/manual/plugins.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- plugins.xml 13 Feb 2004 19:04:19 -0000 1.1
+++ plugins.xml 17 Jan 2005 19:16:08 -0000 1.2
@@ -74,7 +74,7 @@
Example usage:
</p>
<source language="C#"><![CDATA[
-LogManager.GetLoggerRepository().PluginMap.Add(new RemoteLoggingServerPlugin("LoggingSink"));]]></source>
+LogManager.GetRepository().PluginMap.Add(new RemoteLoggingServerPlugin("LoggingSink"));]]></source>
</li>
</ul>
1.2 +1 -1 logging-log4net/xdocs/src/release/manual/repositories.xml
Index: repositories.xml
===================================================================
RCS file: /home/cvs/logging-log4net/xdocs/src/release/manual/repositories.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- repositories.xml 13 Feb 2004 19:04:19 -0000 1.1
+++ repositories.xml 17 Jan 2005 19:16:08 -0000 1.2
@@ -47,7 +47,7 @@
<p>
Named logging repositories can be created using the <span class="code">LogManager.CreateRepository</span>
method. The repository for can be retrieved using the
- <span class="code">LogManager.GetLoggerRepository</span> method.
+ <span class="code">LogManager.GetRepository</span> method.
A repository created in this way will need to be configured programmatically.
</p>