Added: websites/production/logging/content/log4net/log4net-1.2.13/release/manual/introduction.html ============================================================================== --- websites/production/logging/content/log4net/log4net-1.2.13/release/manual/introduction.html (added) +++ websites/production/logging/content/log4net/log4net-1.2.13/release/manual/introduction.html Sun Nov 10 08:24:41 2013 @@ -0,0 +1,1220 @@ + + + + + + + Apache log4net Manual: Introduction + + + + + + + + + + +
+ +
+
+
+ + + +

Apache log4net™ Manual - Introduction

+

Overview

+

+ This document is based on Short introduction to log4j by Ceki Gülcü. +

+

+ The log4net framework is based on Apache log4j™, see + http://logging.apache.org/log4j/ for more information on log4j. + The log4net framework, source code, binaries, documentation, examples and related + materials are published under the terms of the + Apache License, Version 2.0, + a copy of which has been included with this distribution in the LICENSE.txt file. +

+

+ This document is an introduction to the log4net API, its unique features and + design rationale. Log4net is an open source project based on the work of many + authors. It allows the developer to control which log statements are output + with arbitrary granularity. It is fully configurable at runtime using external + configuration files. +

+

+ Almost every large application includes its own logging or tracing API. + Inserting log statements into code is a low-tech method for debugging it. It + may also be the only way because debuggers are not always available or + applicable. This is usually the case for multithreaded applications and + distributed applications at large. +

+

+ Once an application has been deployed it may not be possible to utilize + development and debugging tools. An administrator can use effective logging + systems to diagnose and fix many configuration issues. +

+

+ Experience indicates that logging is an important component of the development + cycle. It offers several advantages. It provides precise context about the + execution of the application. Once inserted into the code, the generation of + logging output requires no human intervention. Moreover, log output can be + saved in persistent medium to be studied at a later time. In addition to its + use in the development cycle, a sufficiently rich logging package can also be + viewed as an auditing tool. +

+

+ Logging does have its drawbacks. It can slow down an application. If too + verbose, it can cause scrolling blindness. To alleviate these concerns, log4net + is designed to be reliable, fast and extensible. Since logging is rarely the + main focus of an application, the log4net API strives to be simple to + understand and to use. +

+
+ +

Frameworks

+

+ Log4net is available for several frameworks. For each supported framework an + assembly targeting that framework is built: +

+
    +
  • Microsoft® .NET Framework 1.0
  • +
  • Microsoft .NET Framework 1.1
  • +
  • Microsoft .NET Framework 2.0
  • +
  • Microsoft .NET Framework 3.5
  • +
  • Microsoft .NET Framework 4.0
  • +
  • Microsoft .NET Framework 3.5 Client Profile
  • +
  • Microsoft .NET Framework 4.0 Client Profile
  • +
  • Microsoft .NET Compact Framework 1.0
  • +
  • Microsoft .NET Compact Framework 2.0
  • +
  • Mono 1.0
  • +
  • Mono 2.0
  • +
  • Microsoft Shared Source CLI 1.0
  • +
  • CLI 1.0 Compatible
  • +
+

+ Not all frameworks are created equal and some features have been excluded from + some of the builds. See the Framework Support + document for more information. +

+
+ +

Loggers and Appenders

+

+ Log4net has three main components: loggers, appenders and layouts. + These three types of components work together to enable developers to log + messages according to message type and level, and to control at runtime how + these messages are formatted and where they are reported. These components are + helped by filters that control the actions of the appender and + object renderers that turn objects into strings. +

+ +

Logger hierarchy

+

+ The first and foremost advantage of any logging API over plain + System.Console.WriteLine + resides in its ability to disable certain log statements while allowing others + to print unhindered. This capability assumes that the logging space, that is, + the space of all possible logging statements, is categorized according to some + developer-chosen criteria. +

+

+ Loggers are named entities. Logger names are case-sensitive and they follow the + following hierarchical naming rule: +

+
+
Named Hierarchy
+
+

+ A logger is said to be an ancestor of another logger if its name + followed by a dot is a prefix of the descendant logger name. A logger is + said to be a parent of a child logger if there are no ancestors + between itself and the descendant logger. +

+

+ The hierarchy works very much in the same way as the namespace and class + hierarchy in .NET. This is very convenient as we shall soon see. +

+
+
+

+ For example, the logger named + "Foo.Bar" + is a parent of the logger named + "Foo.Bar.Baz". Similarly, + "System" + is a parent of + "System.Text" + and an ancestor of + "System.Text.StringBuilder". This naming scheme + should be familiar to most developers. +

+

+ The root logger resides at the top of the logger hierarchy. It is exceptional + in three ways: +

+
    +
  1. + It always exists
  2. +
  3. + It cannot be retrieved by name
  4. +
  5. + It always has an assigned level
  6. +
+

+ Loggers are retrieved using the static method from the + log4net.LogManager + class. The + GetLogger + methods take the name of the desired logger as a parameter. They are listed + below: +

+
+namespace log4net
+{
+    public class LogManager
+    {
+        public static ILog GetLogger(string name);
+        public static ILog GetLogger(Type type);
+    }
+}
+

+ The + GetLogger + methods that takes a + Type + parameter uses the fully qualified type name as the name of the logger to + retrieve. +

+

+ These + GetLogger + methods return an + ILog + interface. That is the representation of the Logger passed back to the + developer. The + ILog + interface is defined below: +

+
+namespace log4net
+{
+    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);
+        
+        /* 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);
+    }
+}
+

+ Loggers may be assigned levels. Levels are instances of the + log4net.Core.Level + class. The following levels are defined in order of increasing priority: +

+
    +
  • + ALL +
  • +
  • + DEBUG +
  • +
  • + INFO +
  • +
  • + WARN +
  • +
  • + ERROR +
  • +
  • + FATAL +
  • +
  • + OFF +
  • +
+

+ If a given logger is not assigned a level, then it inherits one from its + closest ancestor with an assigned level. More formally: +

+
+
Level Inheritance
+
+

+ The inherited level for a given logger X, is equal to the first + non-null level in the logger hierarchy, starting at X and proceeding + upwards in the hierarchy towards the root logger. +

+
+
+

+ To ensure that all loggers can eventually inherit a level, the root logger + always has an assigned level. The default value for the root logger is + DEBUG. +

+

+ Below are four tables with various assigned level values and the resulting + inherited levels according to the above rule. +

+

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Logger name + Assigned level + Inherited level
rootProotProot
XnoneProot
X.YnoneProot
X.Y.ZnoneProot
+
+

+ In Example 1 above, only the root logger is assigned a level. This level + value, + Proot, is inherited by the other loggers + X, + X.Y + and + X.Y.Z. +

+

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Logger name + Assigned level + Inherited level
rootProotProot
XPxPx
X.YPxyPxy
X.Y.ZPxyzPxyz
+
+

+ In Example 2 above, all loggers have an assigned level value. There is + no need for level inheritance. +

+

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Logger name + Assigned level + Inherited level
rootProotProot
XPxPx
X.YnonePx
X.Y.ZPxyzPxyz
+
+

+ In Example 3 above, the loggers + root, + X + and + X.Y.Z + are assigned the levels + Proot, + Px + and + Pxyz + respectively. The logger + X.Y + inherits its level value from its parent + X. +

+

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Logger name + Assigned level + Inherited level
rootProotProot
XPxPx
X.YnonePx
X.Y.ZnonePx
+
+

+ In Example 4 above, the loggers root and + X + and are assigned the levels + Proot + and + Px + respectively. The loggers + X.Y + and + X.Y.Z + inherits their level value from their nearest parent + X + having an assigned level. +

+

+ Logging requests are made by invoking one of the printing methods of a logger + instance (through the log4net.ILog). These printing methods are + Debug, + Info, + Warn, + Error, and + Fatal. +

+

+ By definition, the printing method determines the level of a logging request. + For example, if + log + is a logger instance, then the statement + log.Info("..") + is a logging request of level INFO. +

+

+ A logging request is said to be enabled if its level is higher than or + equal to the level of its logger. Otherwise, the request is said to be disabled. + A logger without an assigned level will inherit one from the hierarchy. This + rule is summarized below. +

+
+
Basic Selection Rule
+
+

+ A log request of level L in a logger with (either assigned or inherited, + whichever is appropriate) level K, is enabled if L >= K. +

+
+
+

+ This rule is at the heart of log4net. It assumes that levels are ordered. For + the standard levels, we have + DEBUG < INFO < WARN < ERROR < FATAL. +

+

+ Calling the + log4net.LogManager.GetLogger + method with the same name will always return a reference to the exact same + logger object. +

+

+ For example, in: +

+
+ILog x = LogManager.GetLogger("wombat");
+ILog y = LogManager.GetLogger("wombat");
+

+ x + and + y + refer to exactly the same logger object. +

+

+ Thus, it is possible to configure a logger and then to retrieve the same + instance somewhere else in the code without passing around references. In + fundamental contradiction to biological parenthood, where parents always + precede their children, log4net loggers can be created and configured in any + order. In particular, a "parent" logger will find and link to its descendants + even if it is instantiated after them. +

+

+ Configuration of the log4net environment is typically done at application + initialization. The preferred way is by reading a configuration file. This + approach will be discussed shortly. +

+

+ Log4net makes it easy to name loggers by software component. This can be + accomplished by statically instantiating a logger in each class, with the + logger name equal to the fully qualified name of the class. This is a useful + and straightforward method of defining loggers. As the log output bears the + name of the generating logger, this naming strategy makes it easy to identify + the origin of a log message. However, this is only one possible, albeit common, + strategy for naming loggers. Log4net does not restrict the possible set of + loggers. The developer is free to name the loggers as desired. +

+

+ Nevertheless, naming loggers after the class where they are located seems to be + the best strategy known so far. It is simple an obvious to the developers where + each log message came from. Most importantly it leverages the design of the + application to produce the design of the logger hierarchy. Hopefully some + thought has gone into the design of the application. +

+
+ +

Appenders

+

+ The ability to selectively enable or disable logging requests based on their + logger is only part of the picture. Log4net allows logging requests to print to + multiple destinations. In log4net speak, an output destination is called an appender. + Appenders must implement the log4net.Appenders.IAppender + interface. +

+

+ The following appenders are defined in the log4net package: +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Type + Description
log4net.Appender.AdoNetAppender + Writes logging events to a database using either prepared statements or stored + procedures. +
log4net.Appender.AnsiColorTerminalAppender + Writes color highlighted logging events to a an ANSI terminal window. +
log4net.Appender.AspNetTraceAppender + 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. +
log4net.Appender.BufferingForwardingAppender + Buffers logging events before forwarding them to child appenders. +
log4net.Appender.ColoredConsoleAppender + Writes logging events to the application's Console. The events may go to either + the standard our stream or the standard error stream. The events may have configurable + text and background colors defined for each level. +
log4net.Appender.ConsoleAppender + Writes logging events to the application's Console. The events may go to either + the standard our stream or the standard error stream. +
log4net.Appender.DebugAppender + Writes logging events to the .NET system. +
log4net.Appender.EventLogAppender + Writes logging events to the Windows Event Log. +
log4net.Appender.FileAppender + Writes logging events to a file in the file system. +
log4net.Appender.ForwardingAppender + Forwards logging events to child appenders. +
log4net.Appender.LocalSyslogAppender + Writes logging events to the local syslog service (UNIX only). +
log4net.Appender.MemoryAppender + Stores logging events in an in memory buffer. +
log4net.Appender.NetSendAppender + Writes logging events to the Windows Messenger service. These messages are + displayed in a dialog on a users terminal. +
log4net.Appender.OutputDebugStringAppender + Writes logging events to the debugger. If the application has no + debugger, the system debugger displays the string. If the application has no + debugger and the system debugger is not active, the message is ignored. +
log4net.Appender.RemoteSyslogAppender + Writes logging events to a remote syslog service using UDP networking. +
log4net.Appender.RemotingAppender + Writes logging events to a remoting sink using .NET remoting. +
log4net.Appender.RollingFileAppender + Writes logging events to a file in the file system. The RollingFileAppender can + be configured to log to multiple files based upon date or file size + constraints. +
log4net.Appender.SmtpAppender + Sends logging events to an email address. +
log4net.Appender.SmtpPickupDirAppender + Writes SMTP messages as files into a pickup directory. + These files can then be read and sent by an SMTP agent + such as the IIS SMTP agent. +
log4net.Appender.TelnetAppender + Clients connect via Telnet to receive logging events. +
log4net.Appender.TraceAppender + Writes logging events to the .NET trace system. +
log4net.Appender.UdpAppender + Sends logging events as connectionless UDP datagrams to a remote host or a + multicast group using a UdpClient. +
+
+

+ More than one appender can be attached to a logger. +

+

+ + Each enabled logging request for a given logger will be forwarded to all + the appenders in that logger as well as the appenders higher in the hierarchy. + + In other words, appenders are inherited additively from the logger hierarchy. + For example, if a console appender is added to the root logger, then all + enabled logging requests will at least print on the console. If in addition a + file appender is added to a logger, say X, then enabled logging requests + for X and X's children will print on a file and on the + console. It is possible to override this default behavior so that appender + accumulation is no longer additive by setting the additivity flag on the logger + to + false. +

+

+ The rules governing appender additivity are summarized below. +

+
+
Appender Additivity
+
+

+ The output of a log statement of logger X will go to all the appenders + in X and its ancestors. This is the meaning of the term "appender + additivity". +

+

+ However, if an ancestor of logger X, say Y, has the additivity + flag set to + false, then X's output will be directed to all + the appenders in X and it's ancestors up to and including Y but + not the appenders in any of the ancestors of Y. +

+

+ Loggers have their additivity flag set to + true + by default. +

+
+
+

+ The table below shows an example: +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Logger Name + Added Appenders + Additivity Flag + Output Targets + Comment
rootA1not applicableA1There is no default appender attached to root.
xA-x1, A-x2trueA1, A-x1, A-x2Appenders of "x" and root.
x.ynonetrueA1, A-x1, A-x2Appenders of "x" and root.
x.y.zA-xyz1trueA1, A-x1, A-x2, A-xyz1Appenders in "x.y.z", "x" and root.
securityA-secfalseA-secNo appender accumulation since the additivity flag is set to + false.
security.accessnonetrueA-secOnly appenders of "security" because the additivity flag in "security" is set + to + false.
+
+
+ +

Filters

+

+ Appenders can filter the events that are delivered to them. The filters can be + specified in the configuration to allow fine control of the events that are + logged through different appenders. +

+

+ The simplest form of control is to specify a + Threshold + on the appender. This works by logging only the events that have a level that + is greater than or equal to the threshold. +

+

+ More complex and custom event filtering can be done using the filter chain + defined on each appender. Filters must implement the + log4net.Filter.IFilter interface. +

+

+ The following filters are defined in the log4net package: +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Type + Description
log4net.Filter.DenyAllFilter + Drops all logging events. +
log4net.Filter.LevelMatchFilter + An exact match to the event's level. +
log4net.Filter.LevelRangeFilter + Matches against a range of levels. +
log4net.Filter.LoggerMatchFilter + Matches against a the start of the logger name. +
log4net.Filter.PropertyFilter + Matches a substring from a specific property value. +
log4net.Filter.StringMatchFilter + Matches a substring from the event's message. +
+
+

+ The filters can be configured to either accept or reject the event based upon + the match. +

+
+ +

Layouts

+

+ More often than not, users wish to customize not only the output destination + but also the output format. This is accomplished by associating a layout + with an appender. The layout is responsible for formatting the logging request + according to the user's wishes, whereas an appender takes care of sending the + formatted output to its destination. The + PatternLayout, part of the standard log4net + distribution, lets the user specify the output format according to conversion + patterns similar to the C language + printf + function. +

+

+ For example, the PatternLayout with the conversion pattern + "%timestamp [%thread] %-5level %logger - %message%newline" + will output something akin to: +

+
+176 [main] INFO  Com.Foo.Bar - Located nearest gas station.
+

+ The first field is the number of milliseconds elapsed since the start of the + program. The second field is the thread making the log request. The third field + is the level of the log statement. The fourth field is the name of the logger + associated with the log request. The text after the '-' is the message of the + statement. +

+

+ The following layouts are included in the log4net package: +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Type + Description
log4net.Layout.ExceptionLayout + Renders the exception text from the logging + event. +
log4net.Layout.PatternLayout + Formats the logging event according to a flexible + set of formatting flags. +
log4net.Layout.RawTimeStampLayout + Extracts the timestamp from the logging event. +
log4net.Layout.RawUtcTimeStampLayout + Extracts the timestamp from the logging event in Universal Time. +
log4net.Layout.SimpleLayout + Formats the logging event very simply: + [level] - [message] +
log4net.Layout.XmlLayout + Formats the logging event as an XML element. +
log4net.Layout.XmlLayoutSchemaLog4j + Formats the logging event as an XML element that + complies with the log4j event dtd. +
+
+
+ +

Object Renderers

+

+ Just as importantly, log4net will render the content of the log message + according to user specified criteria. For example, if you frequently need to + log + Oranges, an object type used in your current project, + then you can register an + OrangeRenderer + that will be invoked whenever an orange needs to be logged. +

+

+ Object rendering follows the class hierarchy. For example, assuming oranges are + fruits, if you register an + FruitRenderer, all fruits including oranges will be + rendered by the + FruitRenderer, unless of course you registered an + orange specific + OrangeRenderer. +

+

+ Object renderers have to implement the + log4net.ObjectRenderer.IObjectRenderer + interface. +

+

+ Please note that ObjectRenderers are not used by the DebugFormat, + InfoFormat, WarnFormat, + ErrorFormat and FatalFormat methods. +

+
+ +
+ +
+ + +
+
+
+
+
+ + +
+
+
+