Log4net实用说明

Log4net实用说明

Appender
Filter
Layout
Logger
ObjectRender
Repository
PatterLayout格式化字符表
配置文件说明

Appender

1. Appenders用来定义日志的输出方式，即日志要写到那种介质上去
2. 常用的Appender:
   • AdoNetAppender 将日志记录到数据库中。可以采用SQL和存储过程两种方式
   • AnsiColorTerminalAppender 将日志高亮输出到ANSI终端
   • AspNetTraceAppender 能用asp.net中Trace的方式查看记录的日志
   • BufferingForwardingAppender 在输出到子Appenders之前先缓存日志事件
   • ConsoleAppender 将日志输出到应用程序控制台
   • EventLogAppender 将日志写到Windows Event Log
   • FileAppender 将日志输出到文件
   • ForwardingAppender 发送日志事件到子Appenders
   • LocalSyslogAppender 将日志写到local syslog service (仅用于UNIX环境下)
   • MemoryAppender 将日志存到内存缓冲区
   • NetSendAppender 将日志输出到Windows Messenger service.这些日志信息将在用户终端的对话框中显示
   • OutputDebugStringAppender 将日志输出到Debuger，如果程序没有Debuger，就输出到系统Debuger。如果系统Debuger也不可用，将忽略消息
   • RemoteSyslogAppender 通过UDP网络协议将日志写到Remote syslog service
   • RemotingAppender 通过.NET Remoting将日志写到远程接收端
   • RollingFileAppender 将日志以回滚文件的形式写到文件中
   • SmtpAppender 将日志写到邮件中
   • SmtpPickupDirAppender 将消息以文件的方式放入一个目录中，像IIS SMTP agent这样的SMTP代理就可以阅读或发送它们
   • TelnetAppender 客户端通过Telnet来接受日志事件
   • TraceAppender 将日志写到.NET trace 系统
   • UdpAppender 将日志以无连接UDP数据报的形式送到远程宿主或用UdpClient的形式广播
3. 格式参考

Filter

1. 使用过滤器可以过滤掉Appender输出的内容
2. 常用的过滤器:
   • DenyAllFilter 阻止所有的日志事件被记录
   • LevelMatchFilter 只有指定等级的日志事件才被记录
   • LevelRangeFilter 日志等级在指定范围内的事件才被记录
   • LoggerMatchFilter 与Logger名称匹配，才记录
   • PropertyFilter 消息匹配指定的属性值时才被记录
   • StringMathFilter 消息匹配指定的字符串才被记录

Layout

1. Layout用于控制Appender的输出格式，可以是线性的也可以是XML
2. 最常用的Layout应该是经典格式的PatternLayout，其次是SimpleLayout，RawTimeStampLayout和ExceptionLayout。然后还有IRawLayout，XMLLayout等几个，使用较少.Layout可以自己实现，需要从log4net.Layout.LayoutSkeleton类继承，来输出一些特殊需要的格式，在后面扩展时就重新实现了一个Layout.
3. Layout描述:
   • SimpleLayout简单输出格式，只输出日志级别与消息内容.
   • RawTimeStampLayout 用来格式化时间，在向数据库输出时会用到.样式如“yyyy-MM-dd HH:mm:ss“.
   • ExceptionLayout需要给Logger的方法传入Exception对象作为参数才起作用，否则就什么也不输出。输出的时候会包含Message和Trace.
   • PatterLayout使用最多的一个Layout，能输出的信息很多，PatterLayout格式化字符表

Logger

1. Logger是直接和应用程序交互的组件.Logger只是产生日志，然后由它引用的Appender记录到指定的媒介，并由Layout控制输出格式.
2. Logger提供了多种方式来记录一个日志消息，也可以有多个Logger同时存在.每个实例化的Logger对象对被log4net作为命名实体（Named Entity）来维护.log4net使用继承体系，也就是说假如存在两个Logger,名字分别为a.b.c和a.b.那么a.b就是a.b.c的祖先.每个Logger都继承了它祖先的属性.所有的Logger都从Root继承,Root本身也是一个Logger.
3. 日志的等级，它们由高到底分别为：
   • OFF > FATAL > ERROR > WARN > INFO > DEBUG > ALL
   • 高于等级设定值方法（如何设置参见“配置文件详解”）都能写入日志， Off所有的写入方法都不写到日志里，ALL则相反.例如当我们设成Info时，logger.Debug就会被忽略而不写入文件，但是FATAL,ERROR,WARN,INFO会被写入，因为他们等级高于INFO.
4. 在具体写日志时，一般可以这样理解日志等级：
   • FATAL（致命错误）：记录系统中出现的能使用系统完全失去功能，服务停止，系统崩溃等使系统无法继续运行下去的错误。例如，数据库无法连接，系统出现死循环.
   • ERROR（一般错误）：记录系统中出现的导致系统不稳定，部分功能出现混乱或部分功能失效一类的错误。例如，数据字段为空，数据操作不可完成，操作出现异常等.
   • WARN（警告）：记录系统中不影响系统继续运行，但不符合系统运行正常条件，有可能引起系统错误的信息。例如，记录内容为空，数据内容不正确等.
   • INFO（一般信息）：记录系统运行中应该让用户知道的基本信息。例如，服务开始运行，功能已经开户等.
   • DEBUG （调试信息）：记录系统用于调试的一切信息，内容或者是一些关键数据内容的输出.
5. Logger实现的ILog接口，ILog定义了5个方法（Debug,Inof,Warn,Error,Fatal）分别对不同的日志等级记录日志.

ObjectRender

1. 它将告诉logger如何把一个对象转化为一个字符串记录到日志里.（ILog中定义的接口接收的参数是Object，而不是String.）

   例如你想把Orange对象记录到日志中，但此时logger只会调用Orange默认的ToString方法而已.所以要定义一个OrangeRender类来实现ObjectRender.IObjectRender接口，然后注册它（也可以直接实现一个自定义的Layout）.这时logger就会知道如何把Orange记录到日志中了.

Repository

1. Repository主要用于日志对象组织结构的维护.

PatterLayout格式化字符表

1. 转换字符说明

   • a 等价于appdomain

     appdomain引发日志事件的应用程序域的友好名称.（使用中一般是可执行文件的名字）

   • c 等价于logger
   • C 等价于type
   • class 等价于type
   • d 等价于date

     date发生日志事件的本地时间. 使用 DE>%utcdate 输出UTC时间. date后面还可以跟一个日期格式，用大括号括起来. DE>例如：%date{HH:mm:ss,fff}或者%date{dd MMM yyyy HH:mm:ss,fff}. 如果date后面什么也不跟，将使用ISO8601 格式. 日期格式和.Net中DateTime类的ToString方法中使用的格式是一样. 另外log4net还有3个自己的格式Formatter. 它们是 "ABSOLUTE", "DATE"和"ISO8601"分别代表 AbsoluteTimeDateFormatter, DateTimeDateFormatter和Iso8601DateFormatter. 例如：%date{ISO8601}或%date{ABSOLUTE}. 它们的性能要好于ToString.

   • exception 异常信息

     日志事件中必须存了一个异常对象，如果日志事件不包含没有异常对象，将什么也不输出。异常输出完毕后会跟一个换行. 一般会在输出异常前加一个换行，并将异常放在最后.

   • F 等价于 file

     file发生日志请求的源代码文件的名字. 警告：只在调试的时候有效. 调用本地信息会影响性能.

   • identity

     当前活动用户的名字(Principal.Identity.Name).警告：会影响性能. （我测试的时候%identity返回都是空的.）

   • l 等价于 location
   • L 等价于 line
   • location

     引发日志事件的方法（包括命名空间和类名），以及所在的源文件和行号. 警告：会影响性能。没有pdb文件的话，只有方法名，没有源文件名和行号.

   • level 日志事件等级
   • line 引发日志事件的行号.

     警告：会影响性能。

   • logger 记录日志事件的Logger对象的名字.

     可以使用精度说明符控制Logger的名字的输出层级，默认输出全名. 注意，精度符的控制是从右开始的。例如：logger 名为 "a.b.c"， 输出模型为%logger{2} ，将输出"b.c".

   • m 等价于 message
   • M 等价于 method
   • message 由应用程序提供给日志事件的消息。
   • mdc

     MDC (旧为：ThreadContext.Properties) 现在是事件属性的一部分。 保留它是为了兼容性，它等价于 property.

   • method

     发生日志请求的方法名（只有方法名而已）. 警告：会影响性能。

   • n 等价于 newline
   • newline 换行符
   • ndc

     NDC (nested diagnostic context)

   • p 等价于 level
   • P 等价于 property
   • properties 等价于 property
   • property

     输出事件的特殊属性。例如： %property{user} 输出user属性。属性是由loggers或appenders添加到时间中的。 有一个默认的属性"DE>log4net:HostName"总是会有。DE> %property将输出所有的属性.

   • r 等价于 timestamp
   • t 等价于 thread
   • timestamp 从程序启动到事件发生所经过的毫秒数。
   • thread 引发日志事件的线程，如果没有线程名就使用线程号.
   • type 引发日志请求的类的全名.

     可以使用精度控制符。例如： 类名是 "log4net.Layout.PatternLayout", 格式模型是%type{1} 将输出"PatternLayout". （也是从右开始的) 警告：会影响性能。

   • u 等价于 identity
   • username当前用户的WindowsIdentity。（类似：HostName/Username）警告：会影响性能。
   • utcdate

     发生日志事件的UTC时间。DE>后面还可以跟一个日期格式，用大括号括起来。DE>例如：%utcdate{HH:mm:ss,fff}或者%utcdate{dd MMM yyyy HH:mm:ss,fff}。如果utcdate后面什么也不跟，将使用ISO8601 格式 。日期格式和.Net中DateTime类的ToString方法中使用的格式是一样。另外log4net还有3个自己的格式Formatter。 它们是 "ABSOLUTE", "DATE"和"ISO8601"分别代表 AbsoluteTimeDateFormatter, DateTimeDateFormatter和Iso8601DateFormatter。例如：%date{ISO8601}或%date{ABSOLUTE}。它们的性能要好于ToString。

   • w 等价于 username
   • x 等价于 ndc
   • X 等价于 mdc
   • % %%输出一个百分号

2. 关于调用本地信息（caller location information）的说明：

   %type %file %line %method %location %class %C %F %L %l %M 都会调用本地信息。这样做会影响性能。本地信息使用System.Diagnostics.StackTrace得到。.Net 1.0 不支持System.Diagnostics.StackTrace 类。

   本地信息在调试模式下可以正常获取，在非调试模式下可能获取不到，或只能获取一部分。（根据我的测试，其实是需要有一个程序数据库（.pdb）文件。）

   %property属性要用代码来设置才能使用（也就是扩展一下），默认属性log4net:HostName不用设置。

3. 转义字符的修饰符：

   • %20logger 如果logger名不足20个字符，就在左边补空格。
   • %-20logger 如果logger名不足20个字符，就在右边补空格。
   • %.30logger 超过30个字符将截断。
   • %20.30logger logger名要在20到30之间，少了在左边补空格，多了截断。
   • %-20.30logger logger名要在20到30之间，少了在右边补空格，多了截断。

配置文件解释

1. 配置文件构成
   • 主要有两大部分，一是申明一个名为“log4net“的自定义配置节，
     • 1: <configSections><section name="log4net"type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" /></configSections>;
     • 2: <log4net>节的具体配置，这是下面要重点说明的.
2. lognet
   • 所有的配置都要在<log4net>元素里定义.
     • 支持的属性：
       • debug可选，取值是true或false，默认是false。设置为true，开启log4net的内部调试. * update可选，取值是Merge(合并)或Overwrite(覆盖)，默认值是Merge. 设置为Overwrite，在提交配置的时候会重置已经配置过的库.
       • threshold可选，取值是repository（库）中注册的level，默认值是ALL.
         • 支持的子元素：
           • appender 0或多个
           • logger 0或多个
           • renderer 0或多个
           • root最多一个
           • param 0或多个
3. root
   • 实际上就是一个根logger，所有其它logger都默认继承它，如果配置文件里没有显式定义，则框架使用根日志中定义的属性. root元素没有属性。
   • 支持的子元素：appender-ref 0个或多个，要引用的appender的名字. level最多一个。 只有在这个级别或之上的事件才会被记录。param 0个或多个， 设置一些参数.
4. logger
   • 支持的属性：name 必须的，logger的名称
     • additivity 可选，取值是true或false，默认值是true。设置为false时将阻止父logger中的appender.
   • 支持的子元素：
     • appender-ref 0个或多个, 要引用的appender的名字.
   • level
     • 最多一个, 只有在这个级别或之上的事件才会被记录.
   • param
     • 0个或多个, 设置一些参数.
5. appender配置

    <appender name="RollingFileAppender" type="log4net.Appender.RollingFileAppender,log4net">
        <!--日志文件路径，“/”与“/”作用相同，到达的目录相同，文件夹不存在则新建 -->
        <!--按文件大小方式输出时在这里指定文件名，并且当天的日志在下一天时在文件名后自动追加当天日期形成新文件。-->
        <!--按照日期形式输出时，直接连接元素DatePattern的value形成文件路径。此处使用这种方式 -->
        <!--param的名称,可以直接查对应的appender类的属性名即可,这里要查的就是RollingFileAppender类的属性 -->
        <param name="File" value="D:/Log/" />
        <!--是否追加到文件-->
        <param name="AppendToFile" value="true" />
        <!--记录日志写入文件时，不锁定文本文件，防止多线程时不能写Log,官方说线程非安全-->
        <lockingModel type="log4net.Appender.FileAppender+MinimalLock" />
        <!--使用Unicode编码-->
        <Encoding value="UTF-8" />
        <!--最多产生的日志文件数，超过则只保留最新的n个。设定值value="－1"为不限文件数-->
        <param name="MaxSizeRollBackups" value="10" />
        <!--是否只写到一个文件中-->
        <param name="StaticLogFileName" value="false" />
        <!--按照何种方式产生多个日志文件(日期[Date],文件大小[Size],混合[Composite])-->
        <param name="RollingStyle" value="Composite" />
        <!--按日期产生文件夹和文件名［在日期方式与混合方式下使用］-->
        <!--此处按日期产生文件夹，文件名固定。注意&quot; 的位置-->
        <param name="DatePattern" value="yyyy-MM-dd/&quot;ReflectionLayout.log&quot;" />
        <!--这是按日期产生文件夹，并在文件名前也加上日期-->
        <param name="DatePattern" value="yyyyMMdd/yyyyMMdd&quot;-TimerServer.log&quot;" />
        <!--这是先按日期产生文件夹，再形成下一级固定的文件夹-->
        <param name="DatePattern" value="yyyyMMdd/&quot;TimerServer/TimerServer.log&quot;" />
        <!--每个文件的大小。只在混合方式与文件大小方式下使用。
        超出大小后在所有文件名后自动增加正整数重新命名，数字最大的最早写入。
        可用的单位:KB|MB|GB。不要使用小数,否则会一直写入当前日志-->
        <param name="maximumFileSize" value="500KB" />
        <!--计数类型为1，2，3…-->
        <param name="CountDirection" value="1"/>
        <!--过滤设置，LevelRangeFilter为使用的过滤器。 -->
        <filter type="log4net.Filter.LevelRangeFilter">
            <param name="LevelMin" value="DEBUG" />
            <param name="LevelMax" value="WARN" />
        </filter>
        <!--记录的格式。一般用log4net.Layout.PatternLayout布局-->
        <!--此处用继承了log4net.Layout.PatternLayout的自定义布局，TGLog.ExpandLayout2
        为命名空间。%property{Operator}、%property{Action}是自定义的输出-->
        <layout type="TGLog.ExpandLayout2.ReflectionLayout,TGLog">
            <param name="ConversionPattern" value="记录时间：%date 线程ID:[%thread] 日志级别：%-5level 记录类：%logger     操作者ID：%property{Operator} 操作类型：%property{Action}%n             当前机器名:%property%n当前机器名及登录用户：%username %n               记录位置：%location%n 消息描述：%property{Message}%n                    异常：%exception%n 消息：%message%newline%n%n" />
        </layout>
    </appender>