Serilog文档翻译系列（六） - 可用的接收器、增强器、格式化输出

01、提供的接收器

Serilog 使用接收器将日志事件以各种格式写入存储。许多接收器由更广泛的 Serilog 社区开发和支持；可以通过在 NuGet 上搜索 serilog 标签找到。

02、增强器

日志事件可以通过多种方式增强属性。通过 NuGet 提供了一些预构建的增强器：

Install-Package Serilog.Enrichers.Thread

增强配置是通过 Enrich 配置对象进行的：

var log = new LoggerConfiguration()
    .Enrich.WithThreadId()
    .WriteTo.Console()
    .CreateLogger();

通过日志写入的所有事件将携带一个名为 ThreadId 的属性，表示写入它们的托管线程的 ID。（根据约定，Enrich 上的任何 .WithXyz() 方法都会创建名为 Xyz 的属性。）

1、日志上下文

Serilog.Context.LogContext 可以用来动态添加和移除来自环境“执行上下文”的属性；例如，在一个事务期间写入的所有消息可能会携带该事务的 ID，等等。

此功能必须在配置时通过 .FromLogContext() 添加到日志记录器中：

var log = new LoggerConfiguration()
    .Enrich.FromLogContext()

然后，可以使用 LogContext.PushProperty() 向上下文添加和移除属性：

log.Information("No contextual properties");
using (LogContext.PushProperty("A", 1))
{
    log.Information("Carries property A = 1");
    using (LogContext.PushProperty("A", 2))
    using (LogContext.PushProperty("B", 1))
    {
        log.Information("Carries A = 2 and B = 1");
    }
    log.Information("Carries property A = 1, again");
}

将属性推送到上下文中会覆盖任何具有相同名称的现有属性，直到从 PushProperty() 返回的对象被释放，如示例中的属性 A 所示。

重要提示：必须按照添加的确切顺序从上下文中弹出属性。否则，行为是未定义的。

2、可用的增强器包

Serilog 项目提供：

• Serilog.Enrichers.Environment - WithMachineName() 和
  
  WithEnvironmentUserName()
• Serilog.Enrichers.Process - WithProcessId()
• Serilog.Enrichers.Thread - WithThreadId()

其他有趣的增强器：

• Serilog.Web.Classic - WithHttpRequestId() 和许多其他在经典 ASP.NET 应用程序中有用的增强器
• Serilog.Exceptions - WithExceptionDetails() 添加来自异常的额外结构化属性
• Serilog.Enrichers.Demystify - WithDemystifiedStackTraces()
• Serilog.Enrichers.ClientInfo - WithClientIp()、WithCorrelationId() 和 WithRequestHeader("header-name") 将添加具有客户端 IP、关联 ID 和 HTTP 请求头值的属性
• Serilog.Enrichers.ExcelDna - WithXllPath() 和许多其他在 Excel-DNA 插件中有用的增强器
• Serilog.Enrichers.Sensitive - WithSensitiveDataMasking() 在日志事件中掩盖敏感数据
• Serilog.Enrichers.GlobalLogContext - FromGlobalLogContext() 动态添加来自“全局上下文”的属性

03、格式化输出

Serilog 提供了多种输出格式机制。

1、格式化纯文本

写入纯文本输出的接收器，例如控制台和基于文件的接收器，通常接受输出模板以控制日志事件数据的格式。

这些接收器写入的事件格式可以使用 outputTemplate 配置参数进行修改。例如，要控制控制台接收器：

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console(outputTemplate:
        "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj}{NewLine}{Exception}")
    .CreateLogger();

输出模板中可以出现多个内置属性：

• Exception - 完整的异常消息和堆栈跟踪，以多行格式显示。如果事件没有关联的异常，则为空。
• Level - 日志事件级别，以完整级别名称格式化。要使用更紧凑的级别名称，可以使用格式如 {Level:u3} 或 {Level:w3} 来分别表示三个字符的大写或小写级别名称。
• Message - 日志事件的消息，呈现为纯文本。:l 格式说明符可以关闭字符串的引用，:j 则使用 JSON 风格渲染任何嵌入的结构化数据。
• NewLine - 属性值为 System.Environment.NewLine。
• Properties - 所有在输出中未出现的事件属性值。使用 :j 格式可以进行 JSON 渲染。
• Timestamp - 事件的时间戳，类型为 DateTimeOffset。
• TraceId - 创建事件时活动的追踪 ID（如果有）。
• SpanId - 创建事件时活动的跨度 ID（如果有）。

通过增强器附加的事件属性也可以出现在输出模板中。

2、格式化 JSON

许多接收器会将日志事件记录为 JSON，或者可以配置为这样做。要输出 JSON 而不是纯文本，可以指定格式化程序。以下示例使用来自 Serilog.Formatting.Compact 的格式化程序配置文件接收器。

Log.Logger = new LoggerConfiguration()
    .WriteTo.File(new CompactJsonFormatter(), "log.txt")
    .CreateLogger();

Serilog 项目提供了三种 JSON 格式化程序：

• Serilog.Formatting.Json.JsonFormatter - 这是 Serilog 包中历史默认的格式化程序。它生成完整的日志事件渲染，并支持一些配置选项。
• Serilog.Formatting.Compact.CompactJsonFormatter - 这是一个较新、更节省空间的 JSON 格式化程序，随 Serilog.Formatting.Compact 一起提供。
• Serilog.Formatting.Compact.RenderedCompactJsonFormatter - 也是随 Serilog.Formatting.Compact 提供的，该格式化程序将消息模板预先渲染为文本。

3、灵活的的格式化与 ExpressionTemplate

Serilog.Expressions 包含了 ExpressionTemplate 类，用于更复杂的文本和 JSON 格式化。表达式模板可以包含条件块、重复部分、对事件属性的计算以及自定义格式化函数。

ExpressionTemplate 实现了 ITextFormatter 接口，因此它可以与任何基于文本的 Serilog 接收器一起使用，包括控制台（带 ANSI 颜色主题）、文件、调试和电子邮件。

4、义格式化程序

纯文本和 JSON 格式化都是通过 ITextFormatter 接口实现的。该接口的实现可以将日志事件格式化为任何基于文本的格式。

自定义 JSON 格式化程序可以围绕 Serilog 中包含的 JsonValueFormatter 类构建。

格式提供程序

有多种选项可用于格式化单个类型的输出，例如日期。一个例子是大多数接收器接受的格式提供程序。

下面是一个使用 Serilog.Sinks.Console 接收器的简单控制台示例。这使用了默认的日期渲染行为。

class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public DateTime Created { get; set; }
}

public class Program
{
    public static void Main(string[] args)
    {
        Log.Logger = new LoggerConfiguration()
            .WriteTo.Console()
            .CreateLogger();

        var exampleUser = new User { Id = 1, Name = "Adam", Created = DateTime.Now };
        Log.Information("Created {@User} on {Created}", exampleUser, DateTime.Now);

        Log.CloseAndFlush();
    }
}

这将以下内容写入控制台。

[18:46:45 INF] Created {"Id": 1, "Name": "Adam", "Created": "2018-05-17T18:46:45.9064879+10:00", "$type": "User"} on 05/17/2018 18:46:45

在某些情况下，可能希望重写或指定 DateTime 的格式。可以通过实现 IFormatProvider 来实现这一点。这种策略适用于您传递给 Serilog 的任何类型。

class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public DateTime Created { get; set; }
}

class CustomDateFormatter : IFormatProvider
{
    readonly IFormatProvider basedOn;
    readonly string shortDatePattern;
    public CustomDateFormatter(string shortDatePattern, IFormatProvider basedOn)
    {
        this.shortDatePattern = shortDatePattern;
        this.basedOn = basedOn;
    }
    public object GetFormat(Type formatType)
    {
        if (formatType == typeof(DateTimeFormatInfo))
        {
            var basedOnFormatInfo = (DateTimeFormatInfo)basedOn.GetFormat(formatType);
            var dateFormatInfo = (DateTimeFormatInfo)basedOnFormatInfo.Clone();
            dateFormatInfo.ShortDatePattern = this.shortDatePattern;
            return dateFormatInfo;
        }
        return this.basedOn.GetFormat(formatType);
    }
}

public class Program
{
    public static void Main(string[] args)
    {
        var formatter = new CustomDateFormatter("dd-MMM-yyyy", new CultureInfo("en-AU"));
        Log.Logger = new LoggerConfiguration()
            .WriteTo.Console(formatProvider: new CultureInfo("en-AU")) // Console 1
            .WriteTo.Console(formatProvider: formatter)                // Console 2
            .CreateLogger();

        var exampleUser = new User { Id = 1, Name = "Adam", Created = DateTime.Now };
        Log.Information("Created {@User} on {Created}", exampleUser, DateTime.Now);

        Log.CloseAndFlush();
    }
}

以下是上述示例的输出，配置了两个控制台接收器。

[13:57:12 INF] Created {"Id": 1, "Name": "Adam", "Created": "2020-09-01T13:56:59.7803740-05:00", "$type": "User"} on 1/09/2020 1:57:12 PM
[13:57:12 INF] Created {"Id": 1, "Name": "Adam", "Created": "2020-09-01T13:56:59.7803740-05:00", "$type": "User"} on 01-Sep-2020 1:57:12 PM

注：相关源码都已经上传至代码库，有兴趣的可以看看。https://gitee.com/hugogoos/Planner