log4net - Introduction

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 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. It cannot be retrieved by name
3. It always has an assigned level

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
	{
		void Debug(object message);
		void Info(object message);
		void Warn(object message);
		void Error(object message);
		void Fatal(object message);
		
		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; }
	}
}

Loggers may be assigned levels. Levels are instances of the log4net.spi.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.

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.

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

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.

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.

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:

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 behaviour 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:

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 IFilter.

The following filters are defined in the log4net package:

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

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 "%r [%t] %-5p %c - %m%n" 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:

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.

The log4net configuration can be configured using assembly-level attributes rather than specified programmatically.

• DOMConfiguratorAttribute

  The log4net.Config.DOMConfiguratorAttribute Allows the DOMConfigurator to be configured using the following properties:

  • ConfigFile

    If specified, this is the filename of the configuration file to use with the DOMConfigurator. This file path is relative to the application base directory (AppDomain.CurrentDomain.BaseDirectory).

    This property cannot be used in conjunction with the ConfigFileExtension property.

  • ConfigFileExtension

    If specified, this is the extension for the configuration file. The assembly file name is used as the base name with the this extension appended. For example if the assembly is loaded from the a file TestApp.exe and the ConfigFileExtension property is set to log4net then the configuration file name is TestApp.exe.log4net. This is equivalent to setting the ConfigFile property to TestApp.exe.log4net.

    The path to the configuration file is build by using the application base directory (AppDomain.CurrentDomain.BaseDirectory), the assembly file name and the configuration file extension.

    This property cannot be used in conjunction with the ConfigFileExtension property.

  • Watch

    If this flag is specified and set to true then the framework will watch the configuration file and will reload the config each time the file is modified.

  If neither of the ConfigFile or ConfigFileExtension properties are specified, the application configuration file (e.g. TestApp.exe.config) will be used as the log4net configuration file.

  Example usage:

  // Configure log4net using the .config file
  [assembly: log4net.Config.DOMConfigurator(Watch=true)]
  // This will cause log4net to look for a configuration file
  // called TestApp.exe.config in the application base
  // directory (i.e. the directory containing TestApp.exe)
  // The config file will be watched for changes.
  							

  // Configure log4net using the .log4net file
  [assembly: log4net.Config.DOMConfigurator(ConfigFileExtension="log4net",Watch=true)]
  // This will cause log4net to look for a configuration file
  // called TestApp.exe.log4net in the application base
  // directory (i.e. the directory containing TestApp.exe)
  // The config file will be watched for changes.
  							

  This attribute may only be used once per assembly.

Using attributes can be a clearer method for defining where the application's configuration will be loaded from. However it is worth noting that attributes are purely passive. They are information only. Therefore if you use configuration attributes you must invoke log4net to allow it to read the attributes. A simple call to LogManager.GetLogger will cause the attributes on the calling assembly to be read and processed. Therefore it is imperative to make a logging call as early as possible during the application start-up, and certainly before any external assemblies have been loaded and invoked.