Serilog 使用简单的C# API来配置日志记录。当外部配置需要时,可以使用Serilog.Settings.AppSettings包(.NET 框架)或Serilog.Settings.Configuration(.NET Core) 谨慎混合。
本文目录:
创建记录器#
使用 LoggerConfiguration
对象创建记录器:
1 | Log.Logger = new LoggerConfiguration().CreateLogger(); |
上面的示例将创建一个记录器,该记录器不会在任何地方记录事件。要查看日志事件,必须配置接收器。
接收器#
日志事件接收器通常将日志事件记录到某些外部表示形式,通常是控制台、文件或数据存储。Serilog 接收器通过 NuGet 分发。维基上列出了一个精选的可用接收器列表。
此示例将使用控制台接收器包(它漂亮地打印日志数据)和文件接收器包,后者将日志事件写入一组含有日期戳的文本文件。
1 | Install-Package Serilog.Sinks.Console |
使用 WriteTo
对象配置接收器。
1 | Log.Logger = new LoggerConfiguration() |
多个接收器可以同时处于活动状态。添加额外的接收器非常简单,就像链接 WriteTo
块一样:
1 | Log.Logger = new LoggerConfiguration() |
输出模板#
基于文本的接收器使用输出模板来控制格式设置。这可以通过 outputTemplate
参数进行修改:
1 |
|
如上例所示,默认模板使用内置属性,如 Timestamp
和 Level
。来自事件的属性(包括使用扩充器附加的属性)也可以显示在输出模板中。
{Message:lj}
格式选项使消息中嵌入的数据输出在 JSON(j)中,但字符串文本除外,这些文本是原样输出的。
对于更紧凑的级别名称,分别使用 {Level:u3}
三个字符大写或 {Level:w3}
小写作为级别名称的格式。
添加 {Properties:j}
到输出模板以包括其他上下文信息。
最低级别#
Serilog 实现了日志事件处理的”最低级别”这一常见概念。
1 | Log.Logger = new LoggerConfiguration() |
MinimumLevelDebug
对象提供要指定为最小值的日志事件级别之一。在上面的示例中,将处理 Debug
级别和更高级别的日志事件,并最终写入控制台。
级别
用法
Verbose
详细级别是最嘈杂的级别,很少(如果有的话)为生产应用启用。
Debug
调试级别用于内部系统事件,这些事件不一定可以从外部观察到,但在确定发生情况时非常有用。
Information
信息级别事件描述系统中发生的与其职责和功能相对应的事情。通常,这些是系统可以执行的可观察操作。
Warning
当服务降级、危及或可能超出其预期参数时,将使用警告级别事件。
Error
当功能不可用或预期中断时,将使用错误事件。
Fatal
最关键的级别,致命事件需要立即关注。
默认级别- 如果没有指定 MinimumLevel
,则将处理 Information
级别事件和更高级别的事件。
覆盖接收器#
有时,最好将详细日志写入一种介质,但将不太详细的日志写入另一种介质。
1 | Log.Logger = new LoggerConfiguration() |
在此示例中,调试日志将写入滚动文件,而只有 Information
级别日志和更高级别的日志将写入控制台。
所有提供的接收器都支持配置 restrictedToMinimumLevel
参数。
记录器与接收器最小值- 必须认识到,日志记录级别只能针对接收器升高,不能降低。因此,如果记录器 MinimumLevel
设置为 Information
,则以 Debug
为指定级别的接收器仍将看到 Information
级别事件。这是因为记录器级配置控制哪些日志记录语句将导致事件创建,而接收器级配置仅筛选这些事件。要创建具有更详细级别的单个记录器,请使用单独的 LoggerConfiguration
。
扩充器#
Enrichers
是添加、删除或修改附加到日志事件的属性的简单组件。例如,这可用于将线程 ID 附加到每个事件。
1 | class ThreadIdEnricher : ILogEventEnricher |
使用 Enrich
配置对象添加扩充器。
1 | Log.Logger = new LoggerConfiguration() |
上面的配置显示了如何在输出格式中使用由扩充器添加的属性。
如果扩充的属性值在整个应用程序运行过程中是不变的,则 WithProperty
快捷方法可用于简化配置。
1 | Log.Logger = new LoggerConfiguration() |
对于使用结构化存储的接收器,可以查看和筛选属性值,则扩充器及其附加的属性通常更有用。
过滤器#
可以通过筛选有选择地记录事件。过滤器只是 LogEvent
上的谓词,一些常见的场景由匹配类处理。
1 | Log.Logger = new LoggerConfiguration() |
子记录器#
有时,对接收器看到的内容进行更精细的控制是必要的。为此,Serilog
允许完整的日志记录管道充当接收器。
1 | Log.Logger = new LoggerConfiguration() |
对于子记录器处理不合适的场景,可以创建多个独立的顶级管道。只能将一个管道分配给 Log.Logger
,但应用可以使用所需的其他 ILogger
实例。