当前位置: 首页 > 工具软件 > NLog > 使用案例 >

(翻译)NLog配置文件(续)

柯书
2023-12-01

日志级别

  每条日志都设置有级别,并且每个日志记录器(logger)都会配置包含或忽略特定级别的日志。常见配置是指定最低日志级别,等于或高于该级别的日志才会记录。例如,如果日志级别为Info,则Info、Warn、Error和Fata级别的日志会记录,忽略Debug和Tracel级别的日志。
  降序排列的日志级别如下所示:

日志级别典型用途
Fatal发生严重问题,程序将要关闭
Error发生错误时间,但程序可能还能运行
Warn发生意外之事,但程序还能运行
Info发送邮件、用户更新资料等正常行为
Debug用于调试:已执行的查询、用户授权、会话过期等
Trace用于跟踪调试:函数X执行开始,函数X执行结束

  还有一类最高等级的日志级别,即Off,它不用于日志事件,但可用于日志规则筛选

Rules(规则集)

  NLog配置文件中的rules(规则集)部分配置使用的日志记录器对象及输出日志级别,同时指定日志输出对象。
  创建日志记录器对象(Logger-object)须指定名称,例如Log.LogManager.GetLogger(“blah blah”),也可以调用Log.LogManager.GetCurrentClassLogger()从类上下文中提取名称,此时名称格式为命名空间加类名。
  logger(日志记录器)元素定义规则集中的单条规则,筛选满足规则要求的日志记录器对象。

  • name:匹配日志记录器对象名称,可能包含通配符(*和?);
  • minlevel:最低输出日志级别;
  • maxlevel:最高输出日志级别;
  • level:指定单一输出日志级别;
  • levels:指定多个输出日志级别,用逗号隔开;
  • writeTo:指定多个日志输出对象(target),用逗号隔开;
  • final:标记为final的规则匹配时,该规则之后的规则都不再处理[2];
  • enabled:禁用enabled值为false的规则,但不会移除该规则;
  • ruleName:指定规则标识符,可在规则中调用Configuration.FindRuleByName和Configuration.RemoveRuleByName通过规则标识符处理规则。NLog 4.6.4版本引入该属性;
  • finalMinLevel:限制仅对指定的最低输出日志级别匹配日志记录器[3]。NLog 5.0版本引入该属性。

  下列示例的规则集中仅包含单条规则,该规则名称为通配符“*”,意为匹配所有日志记录器对象,同时设置只输出日志级别为Info或更高级别的日志,满足要求的日志会输出到控制台。

<targets>
       <target name="logconsole" xsi:type="Console" />
</targets>
<rules>
       <logger name="*" minlevel="Info" writeTo="logconsole" />
</rules>

  规则集中的规则按顺序执行,多条规则可以对应一个日志记录器,使用final属性能设置仅执行首条匹配的规则。
  注意:虽然单条规则的标签名称为logger,但它并不用来定义日志记录器,只是基于name属性定义的模式匹配一个或多个日志记录器。

日志记录器名称筛选

  使用规则的name属性匹配日志记录器名称,将规则与日志记录器关联。name属性值可能包含通配符(*和?)以匹配日志记录器名称。

  • *:匹配0或多个字符;
  • ?:匹配单个字符。

  代码中调用NLog.LogManager.GetCurrentClassLogger(),则日志记录器的名称形式为“命名空间.类名”,这样很容易用规则筛选同一命名空间中的所有类的日志记录器。

<logger name="Name.Space.*" writeTo="target1" />

  采用日志记录器名称筛选,可以设置单个类日志记录器的日志输出目标。

<logger name="Name.Space.Class1" writeTo="target2" /> <!-- Add final=true to stop output to target1 -->
<logger name="Name.Space.*" writeTo="target1" />

  还可以限制单个类日志记录器的日志输出级别。

<logger name="Name.Space.Class2" maxlevel="Warn" final="true" /> <!-- Blackhole that stops all but Error + Fatal -->
<logger name="Name.Space.*" writeTo="target1" />

  也可以完全阻断单个类日志记录器的日志输出。

<logger name="Name.Space.Class3" maxlevel="Off" final="true" /> <!-- Blackhole that stops everything -->
<logger name="Name.Space.*" writeTo="target1" />

  NLog 4.6之前的版本,只能在name属性值的开头和/或结尾处使用通配符*。

<rules>
  <logger name="*" minlevel="Info" writeTo="logconsole" />
  <logger name="Name.Space.*" minlevel="Debug" writeTo="f1" />  
  <logger name="*.Class1" minlevel="Trace" writeTo="f2" />
  <logger name="*.Library.*" minlevel="Warn" writeTo="f3" />
</rules>

  从NLog 4.6开始,可以在name属性值的任意位置使用通配符*和?。

<rules>
  <logger name="*TcpTestServer[*].Connection[07].*" minlevel="Trace" writeTo="logconsole" final="true" />
  <logger name="*TcpTestServer[*].Connection[??].*" minlevel="Debug" writeTo="logconsole" final="true" />
  <logger name="*" minlevel="Info" writeTo="logconsole" />
</rules>
日志级别筛选

  可以在规则中配置输出的日志级别,其它级别的日志不满足规则,则不予输出。常用属性为minlevel,其它属性用于高级配置。
  如果规则中包含多个声明日志级别的属性 (level,、levels、minlevel和maxlevel),仅使用最高优先级的属性,忽略其它属性。
  设置日志级别的相关属性,其处理顺序如下所示:

  1. level
  2. levels
  3. minlevel和maxlevel(二者优先级相同)
  4. none(输出所有级别的日志)

  例如,如果在规则中设置minlevel=“Warn” level=“Info”,则规则采用的日志级别为Info。
  假如规则标记为final,并且包含若干个声明日志级别的属性,final属性仅应用于特定日志级别[4]。

动态日志级别筛选

  日志规则的静态性可以提供高性能,但关于配置的选项一直非常有限。最近,NLog新版本已经在改善这一状况:[5]

  • NLog 4.6新增支持用变量设置日志级别属性(level、minlevel等);
<variable name='globalLevel' value='debug'/>
<rules>
  <logger minlevel='${globalLevel}'/>
</rules>
  • NLog 4.6.4新增支持基于配置API,使用RuleName属性查找规则;
  • NLog 4.6.7新增支持使用布局(如${gdc:globalLevel})在程序运行时动态改变声明日志级别的属性。详见动态路由规则

原文地址:https://github.com/NLog/NLog/wiki/Configuration-file

参考文献:
[1]https://www.cjavapy.com/article/183/
[2]no rules are processed after a final rule matches.个人理解是标记为final的规则,如果匹配了某个日志记录器对象,则该规则后面的规则就不再应用到该日志记录器对象上面。
[3]Loggers matching will be restricted to specified minimum level for following rules.
[4]In case a rule is marked as final and contains any level-declaring attributes, the final attribute applies only to the specified levels.
[5]The logging rules provides high performance because of their static nature. The options for configuration has been very limited. But recent changes has now been made to improve this:

 类似资料: