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>
