log4net

INSIDE部分

    导论

    在导论里面,我们将给出一些基本原理性的内容,内容的来源当时是个人的理解和体会,可能有失偏颇,非常期望读者能够给与意见.log4net是一个设计出色且兼顾实用的开源软件。它有哪些设计得非常出色的地方，为什么要这样设计，它的设计遵循了哪些原则，这是非常值得我们探讨的问题。log4net提供全部源代码，而且本身不是一个非常大的项目,所以将其消化并不是一件非常困难的事情.我们常常有这样的体会,有时候读一本厚厚的砖头式的书,所需时间周期长,而且很有可能半途而废,其效果反而不如读一本薄薄的精要收获来的多.(当然这里需要说明的是盲目地以书的厚薄来评估一本书的价值是非常愚蠢的).log4net正是这样的精要.

    log4net应该属于工具库类软件。按照我们可以从Apache网站上获得的正式文档，log4net是Apache日志服务项目的一部分。这个项目主要是为应用程序的开发提供调试和审计的功能。它是一个非常小的工具箱，那么，作为一个工具软件，须遵循的原则首先是:
    1 何时何处需要，何时何处获得
    当然这里也包括另外一个意思，当你不需要时候，它能够自动被垃圾回收器自动回收.用户使用一个工具库的时候无需任何或者只需要非常少的初始化，能够智能地识别它所运行的环境并且动态的适应需求，而且对于系统的结构没有任何影响的.理想的工具库能够是自包含,自解释的，近似于系统的可扩充的元数据。在.NET中相关的对应概念，叫做自定义属性。理想的情况应该如下所示:
     .....

    [LogService(“c: / log - file.txt”,Condition.AnyException]
     public  static  void  Main()
    {
        //
        // some code
        int  i  =  0 ;
        int  j  =  Int32.Max  /  i
        // ..
     }

    在上面示例中，开发人员无需再函数中书写任何代码，LogService就能够将运行中的异常信息捕获保存在”c:/log-file.txt”中,包括上例中的除零异常.
    当然log4net是一个软件,而不是一个理想品.不过它的初始化操作也非常简单.log4net可以和通过程序或者使用xml配置文件的方式进行初始化.不过一般应用中大多数都是使用xml配置文件的方式.这种使用方式包括设置配置文件，加载配置文件，然后在程序中调用.配置文件可以定义一份通用的，然后多个程序或项目中使用，加载配置文件只需要在AssemblyInfo.cs(vb)中通过一条语句实现.在程序中调用，如howto部分所示，也非常简单.
    第二条原则:系统使用单根结构的层次式消息传播与处理系统
    作为一个系统，其内外部肯定有消息的产生与传播以及对应的处理方式，这些包括内部的消息，外部传入的消息以及内部向外部发布消息的机制.为什么系统要使用单根结构而不是多根结构，我还没有找到办法对其进行说明和解释，这个似乎只能通过经验和现在的各个面向对象系统的应用情况来证明了。
    在log4net中，系统的对象是独立于程序编译系统的命名对象，详细一点说，就是程序员用命名信息向系统请求产生一个logger对象，而不是通过类实例化一个logger对象，将命名信息作为其一个属性。如下所示:   

log4net.ILog log  =  log4net.LogManager.GetLogger( " parent.child.grandchild " );

而不是如此：
   

log4net.ILog log  =  new  log4net.Log( " parent.child.grandchild " )

上面两种方式看起来大同小异，甚至在部分具体程序实现的时候也是基本相同，但是在解决问题的思路上就有很大差别了。log4net的所有命名对象的根为root,root是一个从系统初始化到系统销毁期间自始至终存在的一个logger,你也可以通过

log4net.ILog log  =  log4net.LogManager.GetLogger( " root " )

来获得.
    系统外部通过调用系统logger对象的info,debug,fatal等等方法发给系统的信息依次发给各个层次的logger,最终到root,如上所定义的log对象，当程序员书写如下代码，
   

log.Info( " this is a test information " );

向日志系统传递信息的时候,日志系统的处理是逐层的,首先传给logger("parent.child.grandchild"),然后传给logger("parent.child"),然后传给logger("parent"),然后传给logger("root"),当然这是在各个命名对象存在的情况下,即程序员已经定义分配了各个命名对象.如果程序员只定义了若干个命名对象而不是所有的命名对象，那么只有已经定义分配到的命名对象才会接受到相关信息。这样对于提高系统的运行效率和节省系统资源有好处.
    第三条原则,就是系统内部按功能的高内聚低耦合的规则分工协作，这点也许平淡无奇，这种设计方式有助于系统的分析，实现和学习研究，也便于后面的详叙.另外这种方式在目前各个系统中应用很广.
    接下来我们将详细讨论log4net的组成，配置，与使用
    1.组成
        log4net 有四种主要的组件，分别是Logger（记录器）, Repository（库）, Appender（附着器）以及 Layout（布局）. 
        1.1 记录器
        Logger是应用程序需要交互的主要组件，它用来产生日志消息。产生的日志消息并不直接显示，还要预先经过Layout的格式化处理后才会输出。 Logger提供了多种方式来记录一个日志消息，你可以在你的应用程序里创建多个Logger。Log4net框架定义了一个叫做LogManager的类，用来管理所有的logger对象。

    1.2 Repository

        Repository主要用于负责日志对象组织结构的维护。在log4net的以前版本中，框架仅支持分等级的组织结构(hierarchical organization)。这种等级结构本质上是库的一个实现，并且定义在log4net.Repository.Hierarchy 名字空间中。要实现一个Repository，需要实现log4net.Repository.ILoggerRepository 接口。但是通常并不是直接实现该接口，而是以log4net.Repository.LoggerRepositorySkeleton为基类继承。体系库 (hierarchical repository )则由log4net.Repository.Hierarchy.Hierarchy类实现。

        1.3 Appender

        一个好的日志框架应该能够产生多目的地的输出。比如说输出到控制台或保存到一个日志文件。log4net 能够很好的满足这些要求。它使用一个叫做Appender的组件来定义输出介质。正如名字所示，这些组件把它们附加到Logger日志组件上并将输出传递到输出流中。你可以把多个Appender组件附加到一个日志对象上。 Log4net框架提供了几个Appender组件。关于log4net提供的Appender组件的完整列表可以在log4net框架的帮助手册中找到。有了这些现成的Appender组件，一般来说你没有必要再自己编写了。但是如果你愿意，可以从log4net.Appender.AppenderSkeleton类继承。

        

        1.4 Layout
        Layout 组件用于向用户显示最后经过格式化的输出信息。输出信息可以以多种格式显示，主要依赖于我们采用的Layout组件类型。可以是线性的或一个XML文件。Layout组件和一个Appender组件一起工作。API帮助手册中有关于不同Layout组件的列表。一个Appender对象，只能对应一个Layout对象。要实现你自己的Layout类，你需要从log4net.Layout.LayoutSkeleton类继承，它实现了ILayout接口。 
        
        总结起来的关系就是，Respository提供命名对象的组织和管理，为Logger的基础，Logger通过Appender输出日志信息，Appender通过Layout对输出信息进行格式化，开发人员在程序中一般只需和Logger部分打交道.

    2.配置（XML配置文件方式)
      

<? xml version="1.0" encoding="utf-8"  ?>  

< configuration >  

   < configSections >  

     < section  name ="log4net"  

      type ="log4net.Config.Log4NetConfigurationSectionHandler, 

            log4net-net-1.0"  

     />  

   </ configSections >  

  

   < log4net >  

  

     < root >  

       < level  value ="WARN"  />  

       < appender-ref  ref ="LogFileAppender"  />  

       < appender-ref  ref ="ConsoleAppender"  />  

     </ root >  

  

     < logger  name ="testApp.Logging" >  

       < level  value ="DEBUG" />  

     </ logger >  

    

     < appender  name ="LogFileAppender"  

             type ="log4net.Appender.FileAppender"  >  

       < param  name ="File"  value ="log-file.txt"  />  

       < param  name ="AppendToFile"  value ="true"  />  

  

       < layout  type ="log4net.Layout.PatternLayout" >  

         < param  name ="Header"  value ="[Header]/r/n" />  

         < param  name ="Footer"  value ="[Footer]/r/n" />  

         < param  name ="ConversionPattern"  

           value ="%d [%t] %-5p %c [%x]  - %m%n"  

          />  

       </ layout >  

  

       < filter  type ="log4net.Filter.LevelRangeFilter" >  

         < param  name ="LevelMin"  value ="DEBUG"  />  

         < param  name ="LevelMax"  value ="WARN"  />  

       </ filter >  

     </ appender >  

    

     < appender  name ="ConsoleAppender"  

              type ="log4net.Appender.ConsoleAppender"  >  

       < layout  type ="log4net.Layout.PatternLayout" >  

         < param  name ="ConversionPattern"  

           value ="%d [%t] %-5p %c [%x] - %m%n"  

         />  

       </ layout >  

     </ appender >  

    

   </ log4net >  

</ configuration >

  关于各个部分的介绍如下:
    <root>

    <root>

          <level value="WARN" />

          <appender-ref ref="LogFileAppender" />

          <appender-ref ref="ConsoleAppender" />

      </root> 

        在框架的体系里，所有的日志对象都是根日志(root logger)的后代。 因此如果一个日志对象没有在配置文件里显式定义，则框架使用根日志中定义的属性。在<root>标签里，可以定义level级别值和Appender的列表。如果没有定义LEVEL的值，则缺省为DEBUG。可以通过<appender-ref>标签定义日志对象使用的Appender对象。<appender-ref>声明了在其他地方定义的Appender对象的一个引用。在一个logger对象中的设置会覆盖根日志的设置。而对Appender属性来说，子日志对象则会继承父日志对象的Appender列表。这种缺省的行为方式也可以通过显式地设定<logger>标签的additivity属性为false而改变。

        <logger name="testApp.Logging" additivity="false"> 
        </logger> 
        Additivity的值缺省是true. 
        
        <Logger>

         <logger name="testApp.Logging">

              <level value="DEBUG"/>

        </logger> 

        <logger> 元素预定义了一个具体日志对象的设置。然后通过调用LogManager.GetLogger(“testAPP.Logging”)函数，你可以检索具有该名字的日志。如果LogManager.GetLogger(…)打开的不是预定义的日志对象，则该日志对象会继承根日志对象的属性。知道了这一点，我们可以说，其实<logger>标签并不是必须的。 

    <appender>

          <appender name="LogFileAppender"

                      type="log4net.Appender.FileAppender" >

              <param name="File" value="log-file.txt" />

              <param name="AppendToFile" value="true" />

              <layout type="log4net.Layout.PatternLayout">

                <param name="Header" value="[Header]/r/n" />

                <param name="Footer" value="[Footer]/r/n"/>

                <param name="ConversionPattern"

                      value="%d [%t] %-5p %c - %m%n"

                   />

              </layout>

     <filter type="log4net.Filter.LevelRangeFilter">

            <param name="LevelMin" value="DEBUG" />

            <param name="LevelMax" value="WARN" />

        </filter>

    </appender> 

        在<root>标签或单个的<logger>标签里的Appender对象可以用<appender>标签定义。<appender>标签的基本形式如上面所示。它定义了appender的名字和类型。 另外比较重要的是<appender>标签内部的其他标签。不同的appender有不同的<param>标签。在这里，为了使用FileAppender,你需要一个文件名作为参数。另外还需要一个在<appender>标签内部定义一个Layout对象。Layout对象定义在它自己的<layout>标签内。<layout>标签的type属性定义了Layout的类型(在本例里是PatternLayout)，同时也确定了需要提供的参数值。Header和Footer标签提供了一个日志会话(logging session)开始和结束时输出的文字。有关每种appender的具体配置的例子，可以在log4net/doc/manual/example-config-appender.html中得到。

log4net.Layout.PatternLayout中的转换模式(ConversionPattern)

%m(message):输出的日志消息，如ILog.Debug(…)输出的一条消息

%n(new line):换行

%d(datetime):输出当前语句运行的时刻

%r(run time):输出程序从运行到执行到当前语句时消耗的毫秒数

%t(thread id):当前语句所在的线程ID

%p(priority): 日志的当前优先级别，即DEBUG、INFO、WARN…等

%c(class):当前日志对象的名称，例如：

       模式字符串为：%-10c -%m%n

       代码为：

ILog log=LogManager.GetLogger(“Exam.Log”);

log.Debug(“Hello”);

    则输出为下面的形式：

Exam.Log       - Hello

%L：输出语句所在的行号

%F：输出语句所在的文件名

%-数字：表示该项的最小长度，如果不够，则用空格填充

例如，转换模式为%r [%t]%-5p %c - %m%n 的 PatternLayout 将生成类似于以下内容的输出：

176 [main] INFO  org.foo.Bar - Located nearest gas station.

<filter>

最后，让我们看看在Appender元素里的<filter>标签。它定义了应用到Appender对象的过滤器。本例中，我们使用了LevelRangeFilter过滤器,它可以只记录LevelMin和LevelMax参数指定的日志级别之间的日志事件。可以在一个Appender上定义多个过滤器（Filter）,这些过滤器将会按照它们定义的顺序对日志事件进行过滤。其他过滤器的有关信息可以在log4net的SDK文档中找到。 

    3.使用
        log4net框架定义了一个ILog接口，所有的logger类都必须实现这个接口。如果你想实现一个自定义的logger，你必须首先实现这个接口。你可以参考在/extension目录下的几个例子。 
        ILog接口的定义如下： 
        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 ex); 
                 // ... 
                
                //Boolean 属性用来检查Logger的日志级别 
                //（我们马上会在后面看到日志级别） 
                 bool isDebugEnabled; 
                 bool isInfoEnabled; 
                 //… 其他方法对应的Boolean属性 
            } 
            Log4net框架定义了一个叫做LogManager的类，用来管理所有的logger对象。它有一个GetLogger()静态方法，用我们提供的名字参数来检索已经存在的Logger对象。如果框架里不存在该Logger对象，它也会为我们创建一个Logger对象。代码如下所示：

log4net.ILog log = log4net.LogManager.GetLogger("logger-name");

通常来说，我们会以类（class）的类型（type）为参数来调用GetLogger()，以便跟踪我们正在进行日志记录的类。传递的类(class)的类型(type)可以用typeof(Classname)方法来获得，或者可以用如下的反射方法来获得：

System.Reflection.MethodBase.GetCurrentMethod().DeclaringType

尽管符号长了一些，但是后者可以用于一些场合，比如获取调用方法的类(class)的类型(type)。

日志的级别

正如你在ILog的接口中看到的一样，有五种不同的方法可以跟踪一个应用程序。事实上，这五种方法是运作在Logger对象设置的不同日志优先级别上。这几种不同的级别是作为常量定义在log4net.spi.Level类中。你可以在程序中使用任何一种方法。但是在最后的发布中你也许不想让所有的代码来浪费你的CPU周期，因此，框架提供了7种级别和相应的Boolean属性来控制日志记录的类型。 

Level有以下几种取值

级别	允许的方法	Boolean 属性	优先级别
OFF			Highest
FATAL	void Fatal(...);	bool IsFatalEnabled;
RROR	void Error(...);	bool IsErrorEnabled;
WARN	void Warn(...);	bool IsWarnEnabled;
INFO	void Info(...);	bool IsInfoEnabled;
DEBUG	void Debug(...);	bool IsDebugEnabled;
ALL			Lowest

表1 Logger的日志级别

在log4net框架里，通过设置配置文件，每个日志对象都被分配了一个日志优先级别。如果没有给一个日志对象显式地分配一个级别，那么该对象会试图从他的祖先继承一个级别值。

ILog接口的每个方法都有一个预先定义好了的级别值。正如你在表1看到的，ILog的Inof()方法具有INFO级别。同样的，以此类推，Error()方法具有ERROR级别。当我们使用以上的任何一种方法时，log4net框架会检查日志对象logger的级别和方法的级别。只有当方法的级别高于日志级别时，日志请求才会被接受并执行。

举例说明，当你创建了一个日志对象，并且把他的级别设置为INFO。于是框架会设置日志的每个Boolean属性。当你调用相应的日志方法时，框架会检查相应的Boolean属性，以决定该方法能不能执行。如下的代码：  

Logger.Info("message");

Logger.Debug("message");

Logger.Warn("message");

对于第一种方法，Info()的级别等与日志的级别（INFO），因此日志请求会被传递，我们可以得到输出结果”message”。

对于第二种方法，Debug()的级别低于日志对象logger的日志级别(INFO)，因此，日志请求被拒绝了，我们得不到任何输出。同样的，针对第三行语句，我们可以很容易得出结论。

在表1中有两个特殊的级别：ALL和OFF。ALL表示允许所有的日志请求。OFF是拒绝所有的请求。

你也可以显式地检查Logger对象的Boolean属性，如下所示：

if (logger.IsDebugEnabled) 
        { 
              Logger.Debug("message"); 
         }