Serilog: 强大的 .NET 日志库

Serilog 是一个功能强大的日志记录库，专为 .NET 平台设计。它提供了丰富的 API 和可插拔的输出器及格式化器，使得开发者能够轻松定制和扩展日志记录功能。在本文中，我们将探索 Serilog 的基础知识、API 使用、配置和一些常见的示例。

1. 日志级别

Serilog 支持多个日志级别，按照严重性从高到低排列如下：

• Fatal: 程序无法继续运行，必须立即解决的问题。
• Error: 发生了错误，需要处理。
• Warning: 警告，需关注但不必立即处理。
• Information: 提供有用的消息，通常用于调试。
• Debug: 调试信息，帮助开发者调试程序。
• Verbose: 详细的日志信息，通常用于复杂问题的调试。

2. 日志输出

Serilog 支持多种日志输出方式，包括：

• Console: 输出到控制台。
• File: 输出到文件。
• Seq: 输出到日志收集器 Seq。
• Elasticsearch: 输出到 Elasticsearch。

此外，Serilog 也支持自定义日志输出器。

3. 日志格式

Serilog 提供了多种格式化日志消息的方式：

• 简单文本格式：常见的日志输出格式。
• JSON 格式：适合结构化日志。
• Message Templates 格式：一种灵活的格式，允许在日志消息中插入占位符。

4. 安装

Serilog 可以通过 NuGet 安装：

Install-Package Serilog

5. 基础使用示例

在应用程序中使用 Serilog 十分简单。以下是一个简单的控制台日志输出示例：

using Serilog;

class Program
{
    static void Main()
    {
        Log.Logger = new LoggerConfiguration()
            .MinimumLevel.Debug()
            .WriteTo.Console()
            .CreateLogger();

        Log.Information("Hello, Serilog!");

        Log.CloseAndFlush();
    }
}

此代码将在控制台输出 Hello, Serilog!。

6. 日志级别示例

Serilog 允许设置不同的日志级别。以下示例演示了如何记录各种级别的日志消息：

using Serilog;

class Program
{
    static void Main()
    {
        Log.Logger = new LoggerConfiguration()
            .MinimumLevel.Verbose()
            .WriteTo.Console()
            .CreateLogger();

        Log.Verbose("This is a verbose log message.");
        Log.Debug("This is a debug log message.");
        Log.Information("This is an informational log message.");
        Log.Warning("This is a warning log message.");
        Log.Error("This is an error log message.");
        Log.Fatal("This is a fatal log message.");

        Log.CloseAndFlush();
    }
}

7. 消息模板

Serilog 支持消息模板，允许开发者在日志中使用占位符。以下示例展示了如何使用消息模板：

using Serilog;

class Program
{
    static void Main()
    {
        Log.Logger = new LoggerConfiguration()
            .MinimumLevel.Debug()
            .WriteTo.Console(outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception}")
            .CreateLogger();

        Log.Information("Hello, {Name}!", "Serilog");

        Log.CloseAndFlush();
    }
}

上述代码将在控制台输出如下格式的日志：

2023-09-15 22:23:54.576 +08:00 [INF] Hello, Serilog!

8. 日志属性

Serilog 支持在日志中添加附加属性。以下示例展示了如何记录额外的信息：

using Serilog;

class Program
{
    static void Main()
    {
        Log.Logger = new LoggerConfiguration()
            .MinimumLevel.Debug()
            .WriteTo.Console()
            .CreateLogger();

        Log.Information("Processed {@Count} records in {Time} ms.", new { Count = 10, Time = 123 });

        Log.CloseAndFlush();
    }
}

此代码会输出：

Processed { Count: 10, Time: 123 } records in 0 ms.

9. 文件输出配置

Serilog 允许将日志输出到文件，并通过 rollingInterval 设置日志滚动方式。以下示例展示了如何按天滚动文件并设置输出模板：

Log.Logger = new LoggerConfiguration()
    .WriteTo.File(
        $"logs\\log-.txt", 
        rollingInterval: RollingInterval.Day, 
        outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception}")
    .CreateLogger();

Log.Information("This is a log message!");

Log.CloseAndFlush();

这将创建类似于 log-20230914.txt 的文件，每天一个新文件。

10. 结构化日志记录

Serilog 支持结构化日志记录，这意味着可以将复杂的数据（如对象、集合等）以结构化的方式存储和输出。例如：

using Serilog;

class Program
{
    static void Main()
    {
        var weather = new WeatherForecast
        {
            Date = DateTime.Now,
            TemperatureC = 22,
            Summary = "Sunny"
        };

        Log.Information("Weather forecast: {@Weather}", weather);

        Log.CloseAndFlush();
    }
}

public class WeatherForecast
{
    public DateTime Date { get; set; }
    public int TemperatureC { get; set; }
    public string Summary { get; set; }
}

此代码将输出类似于：

Weather forecast: {"Date":"2023-09-15T22:39:53.8634787+08:00","TemperatureC":22,"Summary":"Sunny","$type":"WeatherForecast"}

11. 日志过滤

Serilog 允许使用过滤器控制输出。以下示例仅输出错误级别以上的日志：

using Serilog;

class Program
{
    static void Main()
    {
        Log.Logger = new LoggerConfiguration()
            .MinimumLevel.Debug()
            .WriteTo.Console()
            .Filter.ByIncludingOnly(logEvent => logEvent.Level >= LogEventLevel.Error)
            .CreateLogger();

        Log.Verbose("This is a verbose log message.");
        Log.Error("This is an error log message.");

        Log.CloseAndFlush();
    }
}

此代码只会在控制台输出错误和更高严重级别的日志。

12. 扩展与自定义输出器

Serilog 支持自定义输出器，允许开发者将日志输出到不同的目的地（例如 Elasticsearch、数据库等）。以下是一个创建自定义控制台输出器的例子：

using Serilog;
using Serilog.Configuration;
using Serilog.Events;

public static class CustomConsoleSinkExtensions
{
    public static LoggerConfiguration CustomConsole(
        this LoggerSinkConfiguration sinkConfiguration,
        ITextFormatter formatter = null,
        LogEventLevel restrictedToMinimumLevel = LevelAlias.Minimum)
    {
        return sinkConfiguration.Sink(
            new CustomConsoleSink(formatter),
            restrictedToMinimumLevel);
    }
}

public class CustomConsoleSink : ILogEventSink
{
    private readonly ITextFormatter _formatter;

    public CustomConsoleSink(ITextFormatter formatter)
    {
        _formatter = formatter ?? throw new ArgumentNullException(nameof(formatter));
    }

    public void Emit(LogEvent logEvent)
    {
        var message = new StringWriter();
        _formatter.Format(logEvent, message);
        Console.WriteLine(message.ToString());
    }
}

然后可以通过以下方式将其添加到日志配置中：

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

13. 总结

Serilog 是一个功能强大的 .NET 日志库，支持丰富的日志记录方式、输出方式和格式化选项。它的可扩展性和灵活性使得开发者能够根据应用程序的需求定制日志记录方式。从简单的控制台日志到复杂的结构化日志和自定义输出器，Serilog 都能轻松应对。

希望本文对您理解 Serilog 和高效使用该库有所帮助！