1. 结构化日志与Serilog核心价值解析
在传统.NET项目中，开发人员通常使用NLog或log4net等日志框架记录文本日志。这些日志以纯文本形式存储，每条日志独立成行，虽然便于人类阅读，但机器解析却异常困难。当我们需要从海量日志中筛选特定请求的完整链路时，文本日志的局限性就暴露无遗。
结构化日志的革命性在于将日志条目转化为机器可读的数据结构。以Serilog为例，当我们记录以下日志时：
csharp复制var order = new { Id = 1001, Amount = 299.99m };
log.Information("Processed order {@Order} in {Elapsed}ms", order, 120);
传统日志框架会输出：
code复制[INFO] Processed order { Id = 1001, Amount = 299.99 } in 120ms
而Serilog的结构化输出（以JSON Sink为例）则是：
json复制{
"Timestamp": "2023-08-20T09:30:00Z",
"Level": "Information",
"Message": "Processed order { Id = 1001, Amount = 299.99 } in 120ms",
"Properties": {
"Order": { "Id": 1001, "Amount": 299.99 },
"Elapsed": 120
}
}
这种结构化特性带来三个核心优势：
- 精准查询：可通过ElasticSearch等工具直接查询"Amount > 100的订单日志"
- 上下文关联：通过TransactionId等属性可追踪完整请求链路
- 存储优化：二进制格式比文本更节省空间，压缩率更高
重要提示：结构化日志不是替代文本日志，而是补充。生产环境建议同时配置Console（人类可读）和Elasticsearch（机器可读）两种Sink。
2. Serilog核心组件深度剖析
2.1 消息模板语法精要
Serilog的消息模板语法是其结构化能力的核心。以下示例展示了模板变量绑定的三种方式：
csharp复制var user = new { Name = "Alice", Age = 28 };
// 字符串化输出（加$前缀）
log.Debug("User $Name logged in", user.Name);
// 结构化输出（加@前缀）
log.Information("User {@User} logged in", user);
// 值拷贝输出（无前缀）
log.Warning("User {Name} logged {Count} times", user.Name, 5);
关键区别：
$前缀：调用对象的ToString()方法@前缀：递归展开对象属性（适合复杂对象）- 无前缀：浅拷贝当前值（适合基础类型）
2.2 Sink生态系统详解
Serilog通过Sink机制支持数十种输出目标，以下是常见生产级Sink选型建议：
| Sink类型 | 适用场景 | 性能影响 | 安装包 |
|---|---|---|---|
| Console | 开发环境调试 | 低 | Serilog.Sinks.Console |
| File | 本地日志归档 | 中 | Serilog.Sinks.File |
| Elasticsearch | 集中式日志分析 | 高 | Serilog.Sinks.ES |
| Seq | 实时日志监控 | 中 | Serilog.Sinks.Seq |
| AWS CloudWatch | 云环境日志收集 | 高 | Serilog.Sinks.AWSCloudWatch |
配置多Sink的典型示例：
csharp复制var log = new LoggerConfiguration()
.WriteTo.Console()
.WriteTo.File("logs/app.log")
.WriteTo.Elasticsearch(new ElasticsearchSinkOptions(new Uri("http://es:9200")))
.CreateLogger();
2.3 Enricher增强机制
Enricher可以为每条日志添加统一属性，非常适合注入环境信息：
csharp复制// 添加机器名和应用版本
Log.Logger = new LoggerConfiguration()
.Enrich.WithMachineName()
.Enrich.WithProperty("Version", Assembly.GetEntryAssembly().GetName().Version)
.CreateLogger();
// 输出示例
// {"MachineName":"WEB01","Version":"1.2.0",...}
推荐生产环境必备的Enricher：
WithThreadId：追踪多线程问题WithCorrelationId：请求链路追踪WithExceptionDetails：异常堆栈增强
3. .NET工程集成实战
3.1 ASP.NET Core集成方案
对于Web项目，推荐使用Serilog.AspNetCore包实现深度集成：
csharp复制// Program.cs
builder.Host.UseSerilog((ctx, lc) => lc
.ReadFrom.Configuration(ctx.Configuration)
.Enrich.FromLogContext());
// appsettings.json
{
"Serilog": {
"Using": ["Serilog.Sinks.Console"],
"MinimumLevel": {
"Default": "Information",
"Override": {
"Microsoft": "Warning",
"System": "Error"
}
},
"WriteTo": [
{ "Name": "Console" },
{
"Name": "File",
"Args": {
"path": "Logs/web.log",
"rollingInterval": "Day"
}
}
]
}
}
关键集成点：
- 自动捕获HTTP请求信息（URL、Method、StatusCode）
- 与Microsoft.Extensions.Logging无缝兼容
- 内置请求生命周期管理
3.2 高性能日志配置技巧
在高并发场景下，需特别注意以下性能优化点：
csharp复制// 异步批量写入配置
.WriteTo.Async(a => a
.File("logs/highperf.log",
buffered: true,
flushToDiskInterval: TimeSpan.FromSeconds(10)),
bufferSize: 10000)
// 内存限制保护
.WriteTo.File("logs/important.log",
fileSizeLimitBytes: 100_000_000,
retainedFileCountLimit: 10)
3.3 结构化异常处理
Serilog对异常处理进行了专门增强：
csharp复制try {
// 业务代码
} catch (Exception ex) {
log.Error(ex, "Order processing failed for {OrderId}", orderId);
// 输出结果包含完整的异常堆栈和OrderId上下文
}
异常日志会包含：
- 异常类型和消息
- 完整堆栈轨迹
- 自定义上下文属性
4. 生产环境最佳实践
4.1 日志分级策略建议
推荐采用以下日志级别标准：
| 级别 | 使用场景 | 采样建议 |
|---|---|---|
| Verbose | 调试级详细信息 | 开发环境全量 |
| Debug | 系统内部状态 | 生产环境10%采样 |
| Information | 业务关键路径 | 全量记录 |
| Warning | 预期内的异常情况 | 全量记录 |
| Error | 需要干预的系统错误 | 全量记录+告警 |
| Fatal | 导致服务崩溃的致命错误 | 立即告警 |
配置示例：
csharp复制.MinimumLevel.Override("Microsoft.EntityFrameworkCore", LogEventLevel.Warning)
4.2 日志查询优化方案
在Elasticsearch中高效查询结构化日志的技巧：
json复制// 查询特定用户的操作日志
GET /logs-*/_search
{
"query": {
"bool": {
"must": [
{ "match": { "Properties.User.Id": 1001 }},
{ "range": { "@timestamp": { "gte": "now-1d" }}}
]
}
}
}
4.3 安全合规注意事项
敏感信息过滤方案：
csharp复制.Destructure.With<SecureDataDestructuringPolicy>()
// 自定义脱敏策略
class SecureDataDestructuringPolicy : IDestructuringPolicy {
public bool TryDestructure(object value, ILogEventPropertyValueFactory p, out LogEventPropertyValue result) {
if (value is CreditCard card) {
result = new ScalarValue($"****-****-****-{card.LastFourDigits}");
return true;
}
result = null;
return false;
}
}
5. 常见问题排坑指南
5.1 性能问题排查
症状：日志写入导致请求延迟增加
排查步骤：
- 检查是否启用异步写入（
buffered: true） - 确认Sink没有配置同步刷新（
flushToDiskInterval应>0） - 使用
Serilog.Debugging包输出内部诊断日志
5.2 日志丢失分析
症状：应用崩溃后最后几条日志缺失
解决方案：
csharp复制// 注册应用退出钩子
AppDomain.CurrentDomain.ProcessExit += (s, e) => Log.CloseAndFlush();
5.3 序列化异常处理
症状：循环引用导致日志记录失败
配置方案：
csharp复制.Destructure.ToMaximumDepth(3)
.Destructure.ToMaximumStringLength(100)
经过多个生产项目验证，Serilog在日均千万级日志量的系统中表现稳定。某电商项目采用Serilog+Elasticsearch方案后，故障排查时间从平均4小时缩短至15分钟。关键在于合理设计日志结构和充分利用Sink组合。