译Serilog 配置基础知识

Posted 2020-11-24 quinnz

Serilog 使用简单的C# API来配置日志记录。当外部配置需要时，可以使用Serilog.Settings.AppSettings包（.NET 框架）或Serilog.Settings.配置包 （.NET Core） 谨慎混合。

创建记录器

使用 LoggerConfiguration 对象创建记录器：

Log.Logger = new LoggerConfiguration().CreateLogger();
Log.Information("No one listens to me!");

上面的示例将创建一个记录器，该记录器不会在任何地方记录事件。要查看日志事件，必须配置接收器。

接收器

日志事件接收器通常将日志事件记录到某些外部表示形式，通常是控制台、文件或数据存储。Serilog 接收器通过 NuGet 分发。维基上列出了一个精选的可用接收器列表。

此示例将使用控制台接收器包（它漂亮地打印日志数据）和文件接收器包，后者将日志事件写入一组含有日期戳的文本文件。

Install-Package Serilog.Sinks.Console
Install-Package Serilog.Sinks.File

使用 WriteTo 对象配置接收器。

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console()
    .CreateLogger();

Log.Information("Ah, there you are!");

多个接收器可以同时处于活动状态。添加额外的接收器非常简单，就像链接 WriteTo 块一样：

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console()
    .WriteTo.File("log-.txt", rollingInterval: RollingInterval.Day)
    .CreateLogger();

输出模板

基于文本的接收器使用输出模板来控制格式设置。这可以通过 outputTemplate 参数进行修改：

    .WriteTo.File("log.txt",
        outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception}")

如上例所示，默认模板使用内置属性，如 Timestamp 和 Level。来自事件的属性（包括使用扩充器附加的属性）也可以显示在输出模板中。

{Message:lj} 格式选项使消息中嵌入的数据输出在 JSON（j）中，但字符串文本除外，这些文本是原样输出的。

对于更紧凑的级别名称，分别使用 {Level:u3} 三个字符大写或 {Level:w3} 小写作为级别名称的格式。

添加 {Properties:j} 到输出模板以包括其他上下文信息。

最低级别

Serilog 实现了日志事件处理的"最低级别"这一常见概念。

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Debug()
    .WriteTo.Console()
    .CreateLogger();

MinimumLevelDebug 对象提供要指定为最小值的日志事件级别之一。在上面的示例中，将处理 Debug 级别和更高级别的日志事件，并最终写入控制台。

级别	用法
Verbose	详细级别是最嘈杂的级别，很少（如果有的话）为生产应用启用。
Debug	调试级别用于内部系统事件，这些事件不一定可以从外部观察到，但在确定发生情况时非常有用。
Information	信息级别事件描述系统中发生的与其职责和功能相对应的事情。通常，这些是系统可以执行的可观察操作。
Warning	当服务降级、危及或可能超出其预期参数时，将使用警告级别事件。
Error	当功能不可用或预期中断时，将使用错误事件。
Fatal	最关键的级别，致命事件需要立即关注。

默认级别- 如果没有指定 MinimumLevel，则将处理 Information 级别事件和更高级别的事件。

覆盖接收器

有时，最好将详细日志写入一种介质，但将不太详细的日志写入另一种介质。

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Debug()
    .WriteTo.File("log.txt")
    .WriteTo.Console(restrictedToMinimumLevel: LogEventLevel.Information)
    .CreateLogger();

在此示例中，调试日志将写入滚动文件，而只有 Information 级别日志和更高级别的日志将写入控制台。

所有提供的接收器都支持配置 restrictedToMinimumLevel 参数。

记录器与接收器最小值- 必须认识到，日志记录级别只能针对接收器升高，不能降低。因此，如果记录器 MinimumLevel 设置为 Information ，则以 Debug 为指定级别的接收器仍将看到 Information 级别事件。这是因为记录器级配置控制哪些日志记录语句将导致事件创建，而接收器级配置仅筛选这些事件。要创建具有更详细级别的单个记录器，请使用单独的 LoggerConfiguration。

扩充器

Enrichers 是添加、删除或修改附加到日志事件的属性的简单组件。例如，这可用于将线程 ID 附加到每个事件。

class ThreadIdEnricher : ILogEventEnricher
{
    public void Enrich(LogEvent logEvent, ILogEventPropertyFactory propertyFactory)
    {
        logEvent.AddPropertyIfAbsent(propertyFactory.CreateProperty(
                "ThreadId", Thread.CurrentThread.ManagedThreadId));
    }
}

使用 Enrich 配置对象添加扩充器。

Log.Logger = new LoggerConfiguration()
    .Enrich.With(new ThreadIdEnricher())
    .WriteTo.Console(
        outputTemplate: "{Timestamp:HH:mm} [{Level}] ({ThreadId}) {Message}{NewLine}{Exception}")
    .CreateLogger();

上面的配置显示了如何在输出格式中使用由扩充器添加的属性。

如果扩充的属性值在整个应用程序运行过程中是不变的，则 WithProperty 快捷方法可用于简化配置。

Log.Logger = new LoggerConfiguration()
    .Enrich.WithProperty("Version", "1.0.0")
    .WriteTo.Console()
    .CreateLogger();

对于使用结构化存储的接收器，可以查看和筛选属性值，则扩充器及其附加的属性通常更有用。

过滤器

可以通过筛选有选择地记录事件。过滤器只是 LogEvent 上的谓词，一些常见的场景由匹配类处理。

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console()
    .Filter.ByExcluding(Matching.WithProperty<int>("Count", p => p < 10))
    .CreateLogger();

子记录器

有时，对接收器看到的内容进行更精细的控制是必要的。为此，Serilog 允许完整的日志记录管道充当接收器。

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console()
    .WriteTo.Logger(lc => lc
        .Filter.ByIncludingOnly(...)
        .WriteTo.File("log.txt"))
    .CreateLogger();

对于子记录器处理不合适的场景，可以创建多个独立的顶级管道。只能将一个管道分配给 Log.Logger，但应用可以使用所需的其他 ILogger 实例。