Serilog完全指南：.NET结构化日志新范式详解
项目地址: https://gitcode.com/gh_mirrors/se/serilog 你还在为.NET应用日志杂乱无章难以分析而烦恼吗？传统日志只能提供文本信息，排查问题时如同大海捞针。本文将带你全面掌握Serilog这一.NET平台的结构化日志新范式，从基础配置到高级应用，让你轻松实现日志的结构化采集、存储和分析，显著提升问题诊断效率。读完本文，你将能够：理解结构化日志的核心优势、掌握Serilog的基本配置与使用方法、学会高级功能如日志上下文管理和事件 enrichment，以及了解在不同场景下的最佳实践。
什么是结构化日志
传统日志通常是无结构的文本信息，例如：
2023-10-01 10:30:00 [INFO] User login succeeded. UserId: 123, Username: john_doe
这种日志虽然包含关键信息，但需要通过复杂的正则表达式才能提取出UserId、Username等字段。而结构化日志（Structured Logging）则将日志事件的各个属性作为独立的结构化数据进行记录，例如：
{
"Timestamp": "2023-10-01T10:30:00",
"Level": "Information",
"Message": "User login succeeded",
"UserId": 123,
"Username": "john_doe"
}
结构化日志的优势在于：
- 便于查询与分析：可以直接通过属性进行过滤和聚合，无需复杂的文本解析
- 丰富的上下文信息：能够记录对象、数组等复杂数据结构
- 支持高级分析工具：可以无缝集成ELK Stack、Splunk等日志分析平台
Serilog简介
Serilog是一个为.NET应用设计的诊断日志库，它从底层构建为支持结构化事件数据的日志系统。项目的核心特点包括：
- 基于消息模板（Message Templates）的结构化日志API
- 丰富的输出目标（Sinks）支持，包括控制台、文件、数据库等
- 强大的日志事件 enrichment 能力
- 高效的性能，在禁用日志级别时几乎无开销
- 优秀的.NET Core支持，包括与ASP.NET Core的深度集成
Serilog的源代码组织清晰，主要模块包括：
- src/Serilog/Core/：包含日志核心功能实现
- src/Serilog/Configuration/：配置相关类
- src/Serilog/Events/：日志事件相关类型定义
- src/Serilog/Context/：日志上下文管理
快速开始
安装Serilog
Serilog通过NuGet包进行分发，基本安装命令如下：
dotnet add package Serilog
dotnet add package Serilog.Sinks.Console # 控制台输出
dotnet add package Serilog.Sinks.File # 文件输出
基本配置
以下是一个简单的Serilog配置示例，将日志同时输出到控制台和文件：
using Serilog;
Log.Logger = new LoggerConfiguration()
.MinimumLevel.Information() // 设置最小日志级别
.WriteTo.Console() // 输出到控制台
.WriteTo.File("app.log", // 输出到文件
rollingInterval: RollingInterval.Day) // 按天滚动
.CreateLogger();
// 使用日志
Log.Information("Application started");
Log.Warning("Low disk space detected");
// 应用退出时确保日志刷新
await Log.CloseAndFlushAsync();
上述代码中，LoggerConfiguration.cs 类提供了流畅的API来配置日志行为。通过链式调用，我们可以轻松添加多个日志输出目标（Sinks）并配置其行为。
结构化日志示例
Serilog的核心优势在于结构化日志支持。使用消息模板语法，我们可以记录结构化数据：
var user = new { Id = 123, Name = "John Doe", Email = "john@example.com" };
var loginTime = DateTime.Now;
var elapsedMs = 42;
Log.Information("User {@User} logged in at {LoginTime:yyyy-MM-dd} (took {ElapsedMs} ms)",
user, loginTime, elapsedMs);
在这个例子中：
{@User}语法告诉Serilog序列化整个对象{LoginTime:yyyy-MM-dd}使用标准.NET格式字符串指定日期格式{ElapsedMs}记录耗时信息
这条日志会被记录为包含User、LoginTime和ElapsedMs属性的结构化事件，而不仅仅是文本。当输出为JSON格式时，它会看起来像这样：
{
"Timestamp": "2023-10-01T14:30:00.000Z",
"Level": "Information",
"Message": "User {User} logged in at 2023-10-01 (took 42 ms)",
"User": {
"Id": 123,
"Name": "John Doe",
"Email": "john@example.com"
},
"LoginTime": "2023-10-01T14:30:00.000Z",
"ElapsedMs": 42
}
核心功能详解
日志级别
Serilog支持以下日志级别（从低到高）：
Verbose：最详细的调试信息Debug：调试信息Information：普通运行时信息Warning：警告但非错误情况Error：错误情况Fatal：致命错误，可能导致应用终止
可以通过 LoggingLevelSwitch.cs 在运行时动态调整日志级别：
var levelSwitch = new LoggingLevelSwitch(LogEventLevel.Information);
Log.Logger = new LoggerConfiguration()
.MinimumLevel.ControlledBy(levelSwitch)
.WriteTo.Console()
.CreateLogger();
// 动态调整日志级别
levelSwitch.MinimumLevel = LogEventLevel.Debug;
日志Enrichment
Enrichment功能允许我们向所有日志事件添加额外属性。例如，添加应用程序名称或环境信息：
Log.Logger = new LoggerConfiguration()
.Enrich.WithProperty("Application", "MyApp")
.Enrich.WithProperty("Environment", "Production")
.Enrich.FromLogContext() // 允许使用LogContext动态添加属性
.WriteTo.Console()
.CreateLogger();
LoggerEnrichmentConfiguration.cs 类提供了丰富的enrichment选项。我们还可以创建自定义enricher来添加特定于应用的上下文信息。
日志上下文
使用 LogContext.cs，我们可以在特定代码范围内添加上下文属性：
using (LogContext.PushProperty("RequestId", Guid.NewGuid()))
using (LogContext.PushProperty("UserId", currentUser.Id))
{
Log.Information("Processing request");
// 此范围内的所有日志都会包含RequestId和UserId属性
ProcessRequest();
}
这种机制特别适用于Web应用，可将请求ID、用户ID等上下文信息自动附加到该请求处理过程中的所有日志事件。
高级应用
过滤日志事件
Serilog允许根据日志属性过滤事件，只保留感兴趣的日志：
Log.Logger = new LoggerConfiguration()
.Filter.ByIncludingOnly(e =>
e.Level >= LogEventLevel.Warning ||
e.Properties.ContainsKey("CriticalFeature"))
.WriteTo.Console()
.CreateLogger();
LoggerFilterConfiguration.cs 提供了更多过滤选项，包括按源上下文、属性值等过滤。
异常处理
Serilog简化了异常日志记录，异常对象会自动被捕获并结构化记录：
try
{
// 可能抛出异常的代码
var data = File.ReadAllText("data.json");
}
catch (Exception ex)
{
Log.Error(ex, "Failed to read data file");
}
日志输出将包含异常类型、消息、堆栈跟踪以及所有内部异常信息，便于问题诊断。
性能优化
Serilog在设计时就注重性能。以下是一些优化建议：
- 使用适当的日志级别：在生产环境提高最小日志级别
- 避免不必要的计算：使用条件日志记录避免在禁用级别时的开销
// 只有在Debug级别启用时才计算复杂对象
Log.Debug("User profile: {Profile}", () => GetUserProfile());
- 批处理日志事件：对于某些sink，可以启用批处理以提高性能
.WriteTo.File("app.log",
batchPostingLimit: 100, // 批处理大小
period: TimeSpan.FromSeconds(2)) // 批处理间隔
BatchingOptions.cs 提供了批处理相关的配置选项。
最佳实践与常见问题
消息模板最佳实践
-
使用有意义的属性名称：避免使用
{0}、{1}等位置参数，而是使用有意义的名称如{UserId}、{OrderId} -
使用正确的操作符：
{Property}：使用ToString()转换{@Property}：序列化对象{$Property}：保留原始类型（如数字、布尔值）{Property:format}：应用格式（如{Date:yyyy-MM-dd}）
-
避免敏感信息：确保日志中不包含密码、令牌等敏感数据
常见问题解答
Q: 如何在ASP.NET Core中集成Serilog？
A: 可以使用Serilog.AspNetCore包，它提供了与ASP.NET Core的深度集成，包括请求日志、依赖注入等功能。
Q: 如何配置JSON格式输出？
A: 使用Serilog.Formatting.Compact包，配置文件sink时指定JSON格式化器：
.WriteTo.File(new CompactJsonFormatter(), "app.json")
Q: 如何在单元测试中验证日志？
A: 可以使用Serilog.Sinks.Testing包，或创建一个收集日志事件的自定义sink。
总结与展望
Serilog为.NET应用程序带来了强大的结构化日志能力，通过其直观的API和丰富的功能集，我们可以轻松实现高质量的日志记录。从基本配置到高级功能如上下文管理和事件过滤，Serilog提供了全面的解决方案来满足各种日志需求。
随着.NET生态系统的不断发展，Serilog持续保持活跃开发，未来将继续提供更多创新功能。无论你是构建小型应用还是大型企业系统，Serilog都能帮助你更好地理解应用行为、快速诊断问题。
鼓励你立即尝试将Serilog集成到你的.NET项目中，体验结构化日志带来的优势。如有疑问，可查阅官方文档或通过项目的GitHub仓库获取帮助。
最后，不要忘记收藏本文，以便日后查阅Serilog使用技巧和最佳实践！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
