Serilog文档翻译系列（三） - 基础配置

Serilog 使用简单的 C# API 来配置日志记录。当需要外部配置时，可以（慎用）通过使用 Serilog.Settings.AppSettings 包或 Serilog.Settings.Configuration 包进行混合配置。

创建日志记录器

日志记录器是通过 LoggerConfiguration 对象创建的：

Log.Logger = new LoggerConfiguration().CreateLogger();
Log.Information("No one listens to me!");
// Finally, once just before the application exits...
Log.CloseAndFlush();

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

接收器

日志事件接收器通常将日志事件记录到某些外部表示形式中，最常见的是控制台、文件或数据存储。Serilog 的接收器通过 NuGet 分发。在 Wiki 上，有一个精心整理的可用接收器列表。

这个示例将使用控制台接收器包和文件接收器包，控制台接收器包用于格式化日志数据输出到控制台，文件接收器包用于将日志事件写入一组按日期标记的文本文件。

$ dotnet add package Serilog.Sinks.Console
$ dotnet add 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）输出，但字符串文字会原样输出。

添加 {Properties:j} 到输出模板中，以包括额外的上下文信息。

在输出模板中添加 {Properties:j} 可以包含额外的上下文信息。这允许你将与日志事件相关联的所有属性（包括自定义属性）以 JSON 格式输出到日志文件中，从而提供额外的调试和跟踪信息。

最低级别

Serilog 实现了日志事件处理中常见的“最低级别”概念。

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

MinimumLevel 配置对象允许指定一个日志事件级别作为最低级别。在上面的示例中，级别为 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();

在这个例子中，调试级别的日志将被写入到滚动文件中，而只有级别及以上的日志会被写入到控制台。而只有信息级别日志和更高级别的日志将写入控制台

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

记录器与接收器的最低级别 - 需要了解的是，日志级别只能提高，而不能降低。也就是说，如果记录器的 MinimumLevel被设置为 Information，那么即使接收器的指定级别为 Debug，它仍然只会接收到 Information 级别的事件。这是因为记录器级别配置是控制哪些日志语句会导致事件的创建，而接收器级别配置是对这些事件进行筛选。如果你想要创建具有更详细级别的单一记录器，那么你应该使用单独的 LoggerConfiguration实例。

增强器

增强器是简单的组件，用于添加、删除或修改附加到日志事件的属性。例如，可以使用 增强器为每个事件附加线程 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();

增强器以及它们附加的属性通常与使用结构化存储的接收器一起使用时更加有用，因为在这些接收器中可以查看和过滤属性值。

过滤器

事件可以通过过滤器进行选择性记录。过滤器只是日志事件的筛选规则，其中一些常见场景由 Matching 类处理。

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 实例。

请注意，如果在 WriteTo.Logger() 回调中指定了解构策略，则这些策略将不会生效，因为子日志记录器处理的是已经创建的LogEvent对象。