你的位置:首页 > ASP.net教程

[ASP.net教程]Apache log4net 手册介绍【翻译】


原文地址

本文内容

  • 配置
  • 配置属性
  • 应用程序 appSettings
  • 配置文件
  • 配置语法
  • 追加器(Appenders)
  • 筛选器(Filters)
  • 布局(Layouts)
  • 根记录器(Root Logger)
  • 记录器(Loggers)
  • 渲染(Renderers)
  • 参数(Parameters)
  • 扩展参数(Extension Parameters)
  • 紧凑 Parameter 语法(Compact Parameter Syntax)

下载 Demo、log4net

Apache log4net™ 手册——介绍【翻译】

配置


向应用程序代码插入日志请求需要大量的规划和努力。观察表明,约 4% 的代码是专门用来记录日志的。因此,即使中等规模的应用程序也会嵌入成千上万的日志语句。鉴于日志语句在应用程序中的数量,在无需手动修改的情况下,管理这些日志语句,就成为当务之急。

log4net 环境是完全可用编程配置的。然而,利用配置文件来配置 log4net 更灵活。目前,配置文件主要是

下面尝试在 MyApp 应用程序中使用 log4net。

位于本文 Demo 中的 MyApp 演示。

using Com.Foo;
 
// Import log4net classes.
using log4net;
using log4net.Config;
 
public class MyApp 
{
  // Define a static logger variable so that it references the
  // Logger instance named "MyApp".
  private static readonly ILog log = LogManager.GetLogger(typeof(MyApp));
 
  static void Main(string[] args) 
  {
    // Set up a simple configuration that logs on the console.
    BasicConfigurator.Configure();
 
    log.Info("Entering application.");
    Bar bar = new Bar();
    bar.DoIt();
    log.Info("Exiting application.");
  }
}


导入 log4net 相关类。然后,定义一个静态的 logger 变量,用 log4net 静态方法和它自己的完整的命名空间限定名来初始化。

MyApp 使用 Bar 类,它位于另一个命令空间中:

// Import log4net classes.
using log4net;
 
namespace Com.Foo
{
  public class Bar 
  {
    private static readonly ILog log = LogManager.GetLogger(typeof(Bar));
 
    public void DoIt()
    {
      log.Debug("Did it again!");
    }
  }
}


调用 BasicConfigurator.Configure() 方法会创建了一个最简单的 log4net。也就是,向 root 记录器添加一个 ConsoleAppender——控制台追加器。用log4net.Layout.PatternLayout 格式化输出,设置格式为“%-4timestamp [%thread] %-5level %logger %ndc - %message%newline”

默认时,root 记录器被分配为 Level.DEBUG

MyApp 输出为:

0  [main] INFO MyApp - Entering application.
36  [main] DEBUG Com.Foo.Bar - Did it again!
51  [main] INFO MyApp - Exiting application.

另外,log4net 中的“孩子”记录器只会连接到他们已存的“祖先”。具体地,名为 Com.Foo.Bar 记录器被直接连接到 root 记录器,从而规避不存在的 Com 或Com.Foo 记录器。这显著提高了性能,并减少 log4net 的内存占用。

MyApp 类通过调用 BasicConfigurator.Configure() 方法配置 log4net(无需在配置文件配置 log4net)。其他类只需要引用 log4net 命名空间,检索期望的记录器就可以。

前面的例子总是输出相同的日志信息。但是,很容易修改 MyApp 的配置,这样日志输出就可以在运行时控制。下面是稍微修改后的程序。

位于本文 Demo 中的 MyApp2 演示。

using Com.Foo;
 
// Import log4net classes.
using log4net;
using log4net.Config;
 
public class MyApp 
{
  private static readonly ILog log = LogManager.GetLogger(typeof(MyApp));
 
  static void Main(string[] args) 
  {
    // BasicConfigurator replaced with 
    new System.IO.FileInfo(args[0]));
 
    log.Info("Entering application.");
    Bar bar = new Bar();
    bar.DoIt();
    log.Info("Exiting application.");
  }
}


方法可以解析配置文件,并相应地设置日志。在命令行指定配置文件的路径。

下面配置文件,输出结果跟使用 BasicConfigurator 的结果一样。

<log4net>
  <!-- A1 is set to be a ConsoleAppender -->
  <appender name="A1" type="log4net.Appender.ConsoleAppender">
 
    <!-- A1 uses PatternLayout -->
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%-4timestamp [%thread] %-5level %logger %ndc - %message%newline" />
    </layout>
  </appender>
  
  <!-- Set root logger level to DEBUG and its only appender to A1 -->
  <root>
    <level value="DEBUG" />
    <appender-ref ref="A1" />
  </root>
</log4net>

假设,我们不想看到任何关于 Com.Foo 包的输出。下面的配置文件可能是实现这一目标的一种方法。

位于本文 Demo 中的 MyApp3 演示。

<log4net>
  <!-- A1 is set to be a ConsoleAppender -->
  <appender name="A1" type="log4net.Appender.ConsoleAppender">
 
    <!-- A1 uses PatternLayout -->
    <layout type="log4net.Layout.PatternLayout">
      <!-- Print the date in ISO 8601 format -->
      <conversionPattern value="%date [%thread] %-5level %logger %ndc - %message%newline" />
    </layout>
  </appender>
  
  <!-- Set root logger level to DEBUG and its only appender to A1 -->
  <root>
    <level value="DEBUG" />
    <appender-ref ref="A1" />
  </root>
  
  <!-- Print only messages of level WARN or above in the package Com.Foo -->
  <logger name="Com.Foo">
    <level value="WARN" />
  </logger>
</log4net>

用上面配置文件配置 MyApp 将显示如下结果:

2000-09-07 14:07:41,508 [main] INFO MyApp - Entering application.
2000-09-07 14:07:41,529 [main] INFO MyApp - Exiting application.

由于记录器 Com.Foo.Bar 没有分配级别,它会从 Com.Foo 继承,而 Com.Foo 在配置文件中被设置成 WARN 等级。Bar.DoIt 方法中的记录语句具有 DEBUG 级别,而 DEBUG 等级比 WARN 要低。因此,DoIt() 方法的日志请求被抑制。

下面的配置文件使用多个追加器(appenders)。

位于本文 Demo 中的 MyApp4 演示。

<log4net>
  <appender name="Console" type="log4net.Appender.ConsoleAppender">
    <layout type="log4net.Layout.PatternLayout">
      <!-- Pattern to output the caller's file name and line number -->
      <conversionPattern value="%5level [%thread] (%file:%line) - %message%newline" />
    </layout>
  </appender>
  
  <appender name="RollingFile" type="log4net.Appender.RollingFileAppender">
    <file value="example.log" />
    <appendToFile value="true" />
    <maximumFileSize value="100KB" />
    <maxSizeRollBackups value="2" />
 
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%level %thread %logger - %message%newline" />
    </layout>
  </appender>
  
  <root>
    <level value="DEBUG" />
    <appender-ref ref="Console" />
    <appender-ref ref="RollingFile" />
  </root>
</log4net>

MyApp 使用上面配置文件将输出如下信息到控制台。

 INFO [main] (MyApp.cs:16) - Entering application.
DEBUG [main] (Bar.cs:12) - Doing it again!
 INFO [main] (MyApp.cs:19) - Exiting application.

另外,root 记录器的第二个附加目的地,输出也会被定向到 example.log 文件。当文件达到100KB时,该文件将被转存。当转存时,example.log 自动移动到example.log.1。

本文 Demo 中,为了达到演示效果,将 100KB 设置得小点,能尽快看到结果。

注意,获得上面那些不同的日志行为,我们不需要重新编译代码。可以很容易地登录一个电子邮件地址,重定向所有 Com.Foo 输出到 NT 事件记录器,或转发事件记录到远程 log4net 服务器,这将根据本地服务器策略日志。

关于使用

配置属性


log4net 的配置可以通过装配级别(assembly-level)的属性来配置,而不用编程的方法。

  • log4net.Config. 让 通过下面属性配置:

    • ConfigFile

      如果指定了该属性, 会使用配置文件名。该配置文件路径是相对应用程序基目录(AppDomain.CurrentDomain.BaseDirectory)。

    • 该属性不能跟下面的 ConfigFileExtension 属性一起使用。

    • ConfigFileExtension

      如果指定了该属性,它就是配置文件的扩展名。装配文件名作为基文件名,后面加配置文件后缀。例如,如果装配是从 TestApp.exe 加载的,并且,ConfigFileExtension 属性设置为 log4net,那么配置文件名为 TestApp.exe.log4net。这相当于设置 ConfigFile 属性为 TestApp.exe.log4net

    • 配置文件的路径是应用程序基目录(AppDomain.CurrentDomain.BaseDirectory)。

    • 该属性不能与 ConfigFile 属性一起使用。

    • Watch

      如果该标识指定为 true,那么,框架将监控配置文件,并且当配置文件被修改时,重新加载。

    如果既没有指定 ConfigFile,也没有指定 ConfigFileExtension 属性,那么应用程序配置文件(如 TestApp.exe.config)作为 log4net 的配置文件。

    用法:

  • // Configure log4net using the .config file
    [assembly: log4net.Config.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."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.
                  


    上面的属性只能在装配文件(程序集)中出现一次。若出现多次,生成时,会报错。

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.

应用程序 appSettings


如果你使用 attributes 来配置 log4net,你的应用程序配置文件 appSettings 小节有两个配置可以用于覆盖你在装配文件中给出的值。

键为 "log4net.Config" 设置会覆盖配置文件名(相对于你应用程序基目录);键为 "log4net.Config.Watch" 的设置决定是否监控文件的变化。

即便装配文件属性为

[assembly: log4net.Config.false)] 

已经配置你的应用程序使用 "TestApp.exe.config" 作为配置文件,并且不监控配置文件的变化。把下面配置添加到你的应用程序配置文件, 将覆盖之前的配置,适应 "log4net.config" 作为 log4net 配置文件,并且监控配置文件的变化。
<appSettings>
 <add key="log4net.Config" value="log4net.config"/>
 <add key="log4net.Config.Watch" value="True"/>
</appSettings>

配置文件


使用文件来指定 log4net 配置。有两种方式读取文件:

  • 使用 .NET System.Configuration API
  • 直接读取文件内容

.config Files

如果配置的数据是在应用程序的配置文件中,如 MyApp.exe.configWeb.config,那么 System.Configuration API 是唯一可用的。因为,System.Configuration API 不支持重新加载配置文件,配置的设置不能通过 log4net.Config. 方法来监控。使用 System.Configuration API 来读取配置数据的主要优点是,它比直接访问配置文件需要的权限更小。

使用 System.Configuration API 配置应用程序的唯一方法,是调用 log4net.Config.

为了在 .config 文件嵌入配置数据,小节的名称必须能够被 .NET 配置文件分析器识别,这是通过使用 configSections 元素。小节必须指定 log4net.Config.Log4NetConfigurationSectionHandler,用于解析配置的小节。小节的类型必须是完全的装配限定名(fully assembly qualified name),因为,这是通过 .NET 配置文件分析器加载,而不是 log4net。对于 log4net 必须指定正确的装配名。下面是一个简单的示例配置,该文件指定了正确的节处理程序用于log4net。

<? version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" />
  </configSections>
  <log4net>
    <appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender" >
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%date [%thread] %-5level %logger [%ndc] - %message%newline" />
      </layout>
    </appender>
    <root>
      <level value="INFO" />
      <appender-ref ref="ConsoleAppender" />
    </root>
  </log4net>
</configuration>

上面的示例,指定了 log4net 程序集(log4net 的 dll 文件)。该程序集必须位于 .NET 运行时能够找到的地方。例如,它位于跟应用程序相同的目录。如果 log4net 程序集被存放在 GAC(全局程序集缓存),那么完全限定的程序集名必须指定文化、版本和公钥。

当使用 .config 文件指定配置时,小节名和

Reading Files Directly

可以直接读取任何

通过 log4net.Config.

添加 log4net.Config.

配置可以从文件中的 log4net 元素读取。在文件中,只能指定一个 log4net 元素,但它可以位于

<? version="1.0" encoding="utf-8" ?>
<log4net>
  <appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender" >
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%date [%thread] %-5level %logger [%ndc] - %message%newline" />
    </layout>
  </appender>
  <root>
    <level value="INFO" />
    <appender-ref ref="ConsoleAppender" />
  </root>
</log4net>

或是,嵌入其他元素内:

<? version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="log4net" type="System.Configuration.IgnoreSectionHandler" />
  </configSections>
  <log4net>
    <appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender" >
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%date [%thread] %-5level %logger [%ndc] - %message%newline" />
      </layout>
    </appender>
    <root>
      <level value="INFO" />
      <appender-ref ref="ConsoleAppender" />
    </root>
  </log4net>
</configuration>

上面例子显示,配置的数据如何嵌入到 .config 文件,即使该文件直接被 log4net 读取。注意:如果 .NET 配置文件分析器发现,没有通过 configSections 元素注册,那么,.NET 配置文件分析器将抛出一个异常。因此,上面的例子,log4net 小节被注册,但是 type 指定的处理程序是 System.Configuration.IgnoreSectionHandler。这是一个内置类,指示将采用另一个方法读取配置的小节。

配置语法

log4net 包含解析

下面是一个可用的

<log4net>
  <appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender" >
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%date [%thread] %-5level %logger [%ndc] - %message%newline" />
    </layout>
  </appender>
  <root>
    <level value="INFO" />
    <appender-ref ref="ConsoleAppender" />
  </root>
</log4net>

log4net 元素支持如下属性:

属性

描述

debug

可选。Value must be either true or false. The default value is false. Set this attribute to true to enable internal log4net debugging for this configuration.

update

可选。Value must be either Merge or Overwrite. The default value is Merge. Set this attribute to Overwrite to reset the configuration of the repository being configured before applying this configuration.

threshold

可选。Value must be the name of a level registered on the repository. The default value is ALL. Set this attribute to limit the messages that are logged across the whole repository, regardless of the logger that the message is logged to.

log4net 元素支持如下子元素:

元素

描述

appender

零个或多个。Defines an appender.

logger

零个或多个。Defines the configuration of a logger.

renderer

零个或多个。Defines an object renderer.

root

可选。只能有一个。Defines the configuration of the root logger.

param

零个或多个。Repository specific parameters

追加器(Appenders)


Appenders 是 log4net 元素的子元素。每个 appender 必须具有唯一的名字。必须指定 appender 的实现类型 type。

下面展示定义一个 log4net.Appender.ConsoleAppender 的 appender。appender 名为 ConsoleAppender。

<appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender" >
  <layout type="log4net.Layout.PatternLayout">
    <conversionPattern value="%date [%thread] %-5level %logger [%ndc] - %message%newline" />
  </layout>
</appender>

appender 元素支持如下属性:

属性

描述

name

必需。Value must be a string name for this appender. The name must be unique among all the appenders defined in this configuration file. This name is used by the <appender-ref> element of a Logger to reference an appender.

type

必需。Value must be the type name for this appender. If the appender is not defined in the log4net assembly this type name must be fully assembly qualified.

appender 元素支持如下子元素:

元素

描述

appender-ref

零个或多个。Allows the appender to reference other appenders. Not supported by all appenders.

filter

零个或多个。Defines the filters used by this appender.

layout

可选。只能有一个。Defines the layout used by this appender.

param

零个或多个。Appender specific parameters.

配置 appenders 的信息参看 Example Appender Configuration 文档。

筛选器(Filters)


Filters 是只能定义在 appender,作为它的子元素。

filter 元素支持如下属性:

属性

描述

type

必需。Value must be the type name for this filter. If the filter is not defined in the log4net assembly this type name must be fully assembly qualified.

filter 元素支持如下子元素:

元素 描述
param

零个或多个。Filter specific parameters.

Filter 形成一个事件必须通过的链。沿着这个链的任何 filter 能够接受时间并停止处理,拒绝事件并停止处理,或让事件到下一个 filter。如果事件到达 filter 链的末端,而没有被拒绝,将隐式接受,并被记录。

<filter type="log4net.Filter.LevelRangeFilter">
  <levelMin value="INFO" />
  <levelMax value="FATAL" />
</filter>

上面配置将记录所有在 INFO 和 FATAL 级别之间的事件。

如果我们只想记录具有指定字符串(如,database),那么需要指定如下 filter:

<filter type="log4net.Filter.StringMatchFilter">
  <stringToMatch value="database" />
</filter>
<filter type="log4net.Filter.DenyAllFilter" />

第一个 filter 将查找事件信息文本中的子字符串 'database'。若发现,则 filter 接受消息,并且 filter 处理将停止,记录信息;否则,事件将被传递给下一个 filter 处理。如果不存在下一个 filter,那么,事件会隐式接受并记录。但是,我们不想记录不匹配的事件,因此,我们需要使用 log4net.Filter.DenyAllFilter,来拒绝所有到达的事件。这个 filter 只在 filter 链的末端有用。

If we want to allow events that have either 'database' or 'ldap' in the message text we can use the following filters:

<filter type="log4net.Filter.StringMatchFilter">
  <stringToMatch value="database"/>
</filter>
<filter type="log4net.Filter.StringMatchFilter">
  <stringToMatch value="ldap"/>
</filter>
<filter type="log4net.Filter.DenyAllFilter" />

布局(Layouts)


Layout 元素只能定义在 appender,作为它的子元素。 Layout 就是具体日志的格式。

layout 元素支持如下属性:

属性

描述

type

必需。Value must be the type name for this layout. If the layout is not defined in the log4net assembly this type name must be fully assembly qualified.

layout 元素支持的子元素:

元素

描述

param

零个或多个。Layout specific parameters.

下面示例演示如何使用 log4net.Layout.PatternLayout 配置布局。

<layout type="log4net.Layout.PatternLayout">
  <conversionPattern value="%date [%thread] %-5level %logger [%ndc] - %message%newline" />
</layout>

根记录器(Root Logger)


Only one root logger element may only be defined and it must be a child of <log4net> element. The root logger is the root of the logger hierarchy. All loggers ultimately inherit from this logger.

An example root logger:

<root>
  <level value="INFO" />
  <appender-ref ref="ConsoleAppender" />
</root>

root 元素没有属性。

root 元素支持的子元素:

元素

描述

appender-ref

零个或多个。Allows the logger to reference appenders by name.

level

可选。只能有一个。Defines the logging level for this logger. This logger will only accept event that are at this level or above.

param

零个或多个。Logger specific parameters.

记录器(Loggers)


Logger 元素只能定义在 log4net 元素,作为它的子元素。

示例:

<logger name="LoggerName">
  <level value="DEBUG" />
  <appender-ref ref="ConsoleAppender" />
</logger>

logger 元素支持的属性如下表所示:

属性

描述

name

必需。Value must be the name of the logger.

additivity

可选。Value may be either true or false. The default value is true. Set this attribute to false to prevent this logger from inheriting the appenders defined on parent loggers.

logger 元素支持的子元素如下表所示:

元素

描述

appender-ref

零个或多个。Allows the logger to reference appenders by name.

level

可选。只能有一个。Defines the logging level for this logger. This logger will only accept event that are at this level or above.

param

零个或多个。Logger specific parameters.

渲染(Renderers)


Renderer 元素只能定义在 log4net 元素,作为其子元素。

示例:

<renderer renderingClass="MyClass.MyRenderer" renderedClass="MyClass.MyFunkyObject" />

renderer 元素支持的属性如下表所示:

属性

描述

renderingClass

必需。Value must be the type name for this renderer. If the type is not defined in the log4net assembly this type name must be fully assembly qualified. This is the type of the object that will take responsibility for rendering the renderedClass.

renderedClass

必需。Value must be the type name for the target type for this renderer. If the type is not defined in the log4net assembly this type name must be fully assembly qualified. This is the name of the type that this renderer will render.

renderer 元素没有子元素。

参数(Parameters)


Parameter 元素是很多元素的子元素。

示例:

<param name="ConversionPattern" value="%date [%thread] %-5level %logger [%ndc] - %message%newline" />

param 元素支持的属性如下表所示:

属性

描述

name

必需。Value must be the name of the parameter to set on the parent object.

value

可选。One of value or type attributes must be specified. The value of this attribute is a string that can be converted to the value of the parameter.

type

可选。One of value or type attributes must be specified. The value of this attribute is a type name to create and set as the value of the parameter. If the type is not defined in the log4net assembly this type name must be fully assembly qualified.

param 元素支持子元素如下表所示:

元素

描述

param

零个或多个。Parameter specific parameters.

An example param that uses nested param elements:

<param name="evaluator" type="log4net.spi.LevelEvaluator">
  <param name="Threshold" value="WARN"/>
<param>

扩展参数(Extension Parameters)


配置 parameters 直接映射到一个对象的可写属性。可用的属性取决于被配置对象的实际类型。log4net SDK 文档包含 log4net 程序集中所有组件的 API 引用。

紧凑 Parameter 语法(Compact Parameter Syntax)


所有 parameters 可交替使用参数名作为元素名,而不是使用 param 元素和 name 属性指定。

示例:

<param name="evaluator" type="log4net.spi.LevelEvaluator">
  <param name="Threshold" value="WARN"/>
<param>

可以写为:

<evaluator type="log4net.spi.LevelEvaluator">
  <threshold value="WARN"/>
<evaluator>

 

下载 Demo、log4net

Apache log4net™ 手册——概述【翻译】