Serilog结构化日志实战：从消息模板到生产级脱敏与性能优化

上个月排查一个线上订单状态不一致的问题，我在生产环境翻了两小时日志。雪上加霜的是，那套系统的日志还是一行行的字符串拼接，里面混着请求时间、用户手机号、异常堆栈，全部塞在一个文本框里。我明知道问题就藏在某个日志片段中，想按用户ID筛一下却发现根本筛不了——因为日志里压根没有"用户ID"这个字段，它只是某一行字符串里被拼进去的一段数字。那时候我真正意识到，日志这件事，如果还停留在"拼字符串给人看"的阶段，工程化是无从谈起的。也是从那次之后，我把项目里的日志方案整体迁移到了Serilog，这套 .NET 下的结构化日志库，极大改变了我们排障、监控和做数据挖掘的方式。

这篇文章不打算写成官方文档的翻译稿，我想从一个实际落地者的角度，把 Serilog 从认知到工程落地的完整链路梳理一遍。内容会用真实的使用场景来讲：为什么需要结构化日志、Serilog 的核心抽象怎么理解、NuGet 包如何选型、.WriteTo.File 文件名格式怎么写才不踩坑、和 ASP.NET Core 集成时有哪些注意事项，以及生产环境里最让人头疼的脱敏、性能和排错问题。无论你是第一次接触 Serilog，还是已经用过但总感觉哪里没玩明白，这篇文章都值得你花十分钟看完。

1. 文本日志的账本：为什么拼字符串这种方式必须换掉

1.1 一个让我彻底转向结构化日志的线上事故

先还原一下那个让我痛下决心改造日志的事故现场。业务侧反馈说用户在下单之后，订单状态经常卡在"待支付"，但实际上钱已经扣了。要查这个问题，最直接的办法就是把这几个小时的交易日志全部捞出来，按用户手机号去筛。文本日志长这样：

code复制2025-01-12 14:03:22.123 INFO 用户 138****8888 发起支付，订单号 20250112140322001，金额 99.00
2025-01-12 14:03:22.134 INFO 用户 138****8888 支付回调处理开始，订单号 20250112140322001
2025-01-12 14:03:22.567 ERROR 支付回调处理失败: 状态=未支付

问题是什么呢？我想查这个用户的所有请求，命令是写出来了，日志也能 grep 到，但是因为所有信息都被揉在一个字符串里，细节字段完全没法被程序理解。你说我能不能用正则强行抠出手机号？这个小项目可以，但一旦字段多了、日志量大了、跨系统查了，纯文本的解析成本会指数级上升。更要命的是，这种写法对"埋点"完全不友好，日志分析平台拿过来也只能做全文检索，没法按字段聚合。

后来我们同期做的一个新服务用了 Serilog + Seq，同样的排查场景，我只需要在 Seq 的搜索框里输入 UserId = 138...，相关的所有日志、上下文、属性、异常堆栈全部结构化地列出来，秒级定位。那次对比，让我彻底认账了：日志不是写给人读的，更是写给机器读的。

1.2 从"给人看"到"给机器读"：结构化日志的本质变化

所谓结构化日志，本质上就是每个日志事件不再是一个"字符串"，而是一组属性包加上一条消息模板。比如上面那条日志，用结构化方式写出来是这样的：

csharp复制logger.Information("用户 {UserId} 发起支付，订单号 {OrderId}，金额 {Amount}", userId, orderId, amount);

Serilog 在内部会把这条日志解析成一个 LogEvent对象，里面有时间戳、日志级别、消息模板，还有一个包含 UserId、OrderId、Amount 的属性字典。当它输出到控制台或文件时，会渲染成人类可读的文本；当它输出到 Json 格式的 Sink 时，属性会变成一个 JSON 对象，机器可以直接解析。

这意味着什么？意味着日志从"一段文字"变成了"一条记录"。记录是自带 Schema 的，字段可以被索引、被过滤、被聚合、被用于告警。这就是为什么很多日志平台（Elasticsearch、Seq、Loki）都能针对 JSON 日志做字段级查询，因为它们拿到的是结构化数据，而不只是日志字符串。

这里有个很多人没想透的点：结构化日志和日志平台（比如 ELK）并不是同一个东西。ELK 里的 Logstash 也得靠解析规则才能把文本变成字段，而 Serilog 在应用侧就已经把字段定义好了，输出端直接消费即可。所以从整个链路上看，在应用侧做结构化日志，是让日志后端真正智能起来的最短路径，没有之一。

2. Serilog 的核心抽象：Logger、Sink、Enricher 的分工与协作

2.1 消息模板：结构化日志的最小单元

Serilog 里最核心的 API 就是 LoggerConfiguration，所有能力都围绕它展开。而所有日志事件都是从消息模板（Message Template）开始的。消息模板长这样：

code复制"User {UserId} logged in from {IpAddress}"

这里 {UserId} 和 {IpAddress} 是命名占位符。写日志的时候你传入对应参数，Serilog 会完成两件事：把这些参数按名保存为结构属性，同时渲染出可读的文本消息。正是因为占位符有名字，下游才能按名取字段。这是"结构化"的根基。

很多刚上手的人会把消息模板当成字符串拼接来用，写出这种代码：

csharp复制// 错误示范：模板退化成字符串
logger.Information($"User {userId} logged in");

这样写看似没什么问题，实际上 Serilog 拿到的是一个已经拼好的字符串，userId 会被直接渲染进文本里，而不会成为结构属性。你在日志平台里就查不到 UserId = 123 这类字段了。这是最基础也最常见的误用，没有之一。

2.2 Sink：日志事件最终流向哪里

Serilog 有一个非常优雅的抽象叫 Sink，它决定了每个日志事件最终被写到什么地方。控制台有 Console Sink，文件有 File Sink，数据库有 MSSqlServer、Postgres 等 Sink，日志平台有 Seq、Elasticsearch、OpenTelemetry 等 Sink。你完全可以在一条配置里同时挂多个 Sink：

csharp复制Log.Logger = new LoggerConfiguration()
    .WriteTo.Console()
    .WriteTo.File("logs/app-.log", rollingInterval: RollingInterval.Day)
    .WriteTo.Seq("http://localhost:5341")
    .CreateLogger();

也就是说，一个业务事件被记录下来之后，控制台、文件、日志平台可以各取所需。开发时把 Console 打开看实时输出，测试环境写文件，生产环境推到集中日志平台，互不干扰。这个组合式设计，比有些框架里"只能配一个输出器"的方案要灵活太多，也是我用它替换 NLog 的一个主要原因。

2.3 Enricher 与 LogContext：把公共字段自动塞进每条日志

但如果你每条日志都得手动传环境、进程号、线程号，那也会很啰嗦。这时候 Enricher 就派上用场了。Enricher 是一个"属性增强器"，Serilog 官方和社区提供了很多，比如：

csharp复制.Enrich.WithEnvironmentName()
.Enrich.WithProcessId()
.Enrich.WithThreadId()
.Enrich.FromLogContext()

WithEnvironmentName() 会给每条日志自动加上运行环境字段，WithThreadId() 加上线程 ID。你会看到每一条日志都自动带有这些公共属性，不需要在业务代码里反复传。这个设计把"业务日志参数"和"运行环境元数据"解耦得很干净。

而 FromLogContext() 更值得单独说。它把 Serilog 的 LogContext 作用域属性和日志事件衔接起来：

csharp复制using (LogContext.PushProperty("OrderId", orderId))
{
    logger.Information("开始处理订单");
    // 这里面的所有日志都会带上 OrderId 字段
}

这一招在跟踪请求链、批处理任务的时候特别好用。你只需要在某个作用域开头推一个属性，后面几十条日志自动带上同一个 OrderId，日志平台里一条链路就这样被串起来了。

3. 最小可运行配置：NuGet 包选型与 .WriteTo.File 文件名格式实操

3.1 NuGet 包选型：常用包和它们各自的作用

Serilog 生态采用的是"核心包 + 可插拔 Sink 包"的组合模式，所以你不需要一次性装一大堆依赖。以 .NET 8 项目为例，我通常只装下面这些：

这里强调一个教训：不要一看日志有问题就疯狂装 Sink 包，你没用到的 Sink 都是净成本。Serilog 的模块化是它的优点，但也意味着你得搞清楚到底需要哪些。我见过项目里装了 Serilog.Sinks.MongoDB、Serilog.Sinks.RabbitMQ，结果配置里根本没用，白白增加依赖和启动扫描负担。

版本方面需要注意一点：Serilog 3.x 是当前主力版本，和 .NET 8 配合得很顺畅。如果你的项目还在 .NET Core 3.1 或者 .NET 5，建议先确认目标框架的兼容性再升级，没必要追新。

3.2 用 C# 代码配置 Logger：最稳的起步姿势

直接上代码。这是我在 Web API 项目里最常用的最小配置组合：

csharp复制Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Information()
    .MinimumLevel.Override("Microsoft", LogEventLevel.Warning)
    .MinimumLevel.Override("Microsoft.EntityFrameworkCore", LogEventLevel.Warning)
    .Enrich.FromLogContext()
    .Enrich.WithEnvironmentName()
    .WriteTo.Console()
    .WriteTo.File(
        path: "logs/app-.log",
        rollingInterval: RollingInterval.Day,
        fileSizeLimitBytes: 200 * 1024 * 1024,
        retainedFileCountLimit: 30,
        rollOnFileSizeLimit: true,
        shared: true,
        flushToDiskInterval: TimeSpan.FromSeconds(5))
    .CreateLogger();

有人会问我，为什么先用代码配置而不是 appsettings.json。我的习惯是先代码后配置。代码配置有编译期检查，能避免因为 JSON 里少写一个字段导致运行时日志直接消失的问题。等基础跑通了，再把配置项挪到 appsettings.json 也不迟。Serilog.Settings.Configuration 包就是干这个的，把上面的配置翻译成 JSON 也完全没问题。

给项目接日志的时候，我建议把它放在 Program.cs 的 Main 方法最开始处，在服务启动之前就把 Log.Logger 建好。这样就算后面依赖注入还没初始化，你也能用 Log.Information() 输出启动日志，问题能被第一时间看到。

3.3 .WriteTo.File 文件名格式：滚动、日期占位符和文件数量控制

这一小节要专门回答一个大家反复搜的热门问题：Serilog .WriteTo.File 文件名格式如何写。很多人第一次配 WriteTo.File 的时候，以为文件名里直接拼日期就行，结果发现文件始终叫同一个名字，根本不按日期滚动。

其实 Serilog 的文件名格式是由 path 参数和 rollingInterval 参数共同决定的。默认情况下的写法如下：

csharp复制.WriteTo.File("logs/app-.log", rollingInterval: RollingInterval.Day)

注意 app- 和 .log 之间那个横杠，这个位置是给日期占位符留的。Serilog 会根据 rollingInterval 决定文件名里日期的粒度：

如果你的日志量特别大，可以改用 RollingInterval.Hour，日志量极大时用 RollingInterval.Minute 也行。这里有个冷知识：Serilog 文件名里的日期占位符其实可以显式写成 {Date}，例如：

csharp复制.WriteTo.File("logs/app-{Date}.log", rollingInterval: RollingInterval.Day)

两者效果等价，但显式 {Date} 更直观，团队里别人读代码时一眼能看懂。如果你想在文件名里带更多运行信息，还可以用 {ProcessId} 之类的扩展占位符，不过这个来自特定 Enricher，配置前最好确认一下。

还有一个高频坑：没有设 fileSizeLimitBytes 和 retainedFileCountLimit，文件会无限增大，磁盘被日志撑爆。 上面配置里我限了单文件 200MB，最多保留 30 个文件，触发文件大小上限后自动滚动到下一个文件。shared: true 这个参数也常常被人忽略，它允许多个进程同时写同一个日志文件，对跑多个实例的服务很有用，代价是性能略降，但通常可接受。

flushToDiskInterval 是异步刷盘间隔，默认是实时写。我设了 5 秒刷新，是为了在高频日志场景下减少磁盘 IO 压力，代价是挂掉的那一瞬间可能丢几秒日志。这个取舍要根据业务容忍度来调。

4. 与 ASP.NET Core 集成：请求上下文、日志级别过滤与性能控制

4.1 使用 UseSerilog 接管 ASP.NET Core 的日志管道

在 Web 项目里，光建一个静态 Log.Logger 还不够，你要让整个 ASP.NET Core 的日志系统都走 Serilog 管道。这就要用到 Serilog.AspNetCore 包里的 UseSerilog 扩展方法。典型写法如下：

csharp复制var builder = WebApplication.CreateBuilder(args);

builder.Host.UseSerilog((context, services, configuration) => configuration
    .ReadFrom.Configuration(context.Configuration)
    .ReadFrom.Services(services)
    .Enrich.FromLogContext()
    .WriteTo.Console()
    .WriteTo.File("logs/app-.log", rollingInterval: RollingInterval.Day));

var app = builder.Build();
app.UseSerilogRequestLogging();
app.Run();

UseSerilog 做了一件很关键的事：把 ILoggerFactory 替换成 Serilog 的实现。这样你在 Controller、Service 里注入的 ILogger<T>，实际上全部走 Serilog 管道。

这里有一个很多人踩过的坑：如果你自己代码里先 Log.Logger = ...，同时又在 builder.Host.UseSerilog() 里配置了一遍，会导致日志输出两份。不要两边重复初始化。如果要用 UseSerilog，Program.cs 里通常就直接把配置写在这个 lambda 里，而 Main 里的静态 Log.Logger 可以只兜底一些启动早期的日志，两者最好是同一个实例。

4.2 请求日志与结构化上下文：从装饰性输出到可检索字段

app.UseSerilogRequestLogging() 这个中间件几乎是必配的。它会给每个 HTTP 请求自动写一条结构化日志，包含请求方法、路径、状态码、耗时等。启用前你要在 Program.cs 里先调用它，顺序放在路由中间件之前即可。

更进一步的玩法是在请求链路里塞上下文。配合 LogContext，你可以定义一个中间件来提取请求头里的 TraceId 或者用户身份，压入日志上下文：

csharp复制app.Use(async (context, next) =>
{
    var traceId = context.Request.Headers["X-Trace-Id"].FirstOrDefault() ?? Guid.NewGuid().ToString();
    using (LogContext.PushProperty("TraceId", traceId))
    using (LogContext.PushProperty("UserId", context.User?.Identity?.Name))
    {
        await next();
    }
});

这个中间件一旦放进管道，当前请求范围内产生的所有日志都会自动带上 TraceId 和 UserId。后面整个调用链的任何 _logger.LogInformation(...) 都能拿到这个属性。日志平台按 TraceId 一搜，一个请求从入口到数据库的全部过程就串起来了。比如"订单支付回调失败"的日志和"发起支付"的日志，光看文本是分散的，但因为它们共享同一个 TraceId，日志平台里就是一条完整的链路。

4.3 日志级别覆写与过滤表达式：屏蔽框架噪音，保留业务信息

ASP.NET Core 自带的大量框架日志很吵，默认情况下如果把所有日志级别开到 Information，控制台简直要被 Microsoft.* 的日志刷屏。我的做法是用 MinimumLevel.Override 单独压低框架日志级别：

csharp复制.MinimumLevel.Override("Microsoft", LogEventLevel.Warning)
.MinimumLevel.Override("Microsoft.AspNetCore", LogEventLevel.Warning)
.MinimumLevel.Override("Microsoft.EntityFrameworkCore.Database.Command", LogEventLevel.Warning)

Microsoft.EntityFrameworkCore.Database.Command 这条特别值得单独控制。开发时你想看 EF Core 生成的 SQL，可以把它提到 Information 级别；生产环境通常压到 Warning，否则每条 SQL 都是一条日志，量太大了。

另一个高频场景是健康检查刷屏。Kubernetes 里健康检查每秒探一次 /health，每个探针都会产生一条请求日志，日志平台瞬间被刷爆。解决办法是过滤：

csharp复制.Filter.ByExcluding(Matching.WithProperty<string>("RequestPath", p => p.StartsWith("/health")))

如果你的 Serilog 版本比较新（2.9+），还可以用表达式语法：

csharp复制.Filter.ByExcluding("RequestPath like '/health%'")

注意这里的语法版本之间差异不小，用之前查一下当前版本的 API 文档比较稳妥。过滤表达式是一个非常强的工具，熟用之后你能做到很多分钟级的日志治理规则，而不需要改业务代码。

5. 生产级加固：脱敏、性能陷阱与常见的排查排错

5.1 敏感信息脱敏：不能把密码打进结构化字段

日志里记录了用户的手机号、邮箱、身份证，在开发环境看着无所谓，到了生产环境就是合规问题。Serilog 本身不会帮你判断哪些字段敏感，所以在落库之前就要考虑脱敏。

最简单的做法是避免记录敏感字段，比如日志模板里根本不接收 Password、Token、身份证号这些参数。但业务上有时确实需要追踪某个订单或者某个请求，那就可以用脱敏器。比如自定义一个 Enricher，把属性值里满足手机号或者密码模式的内容替换掉：

csharp复制public class MaskingEnricher : ILogEventEnricher
{
    public void Enrich(LogEvent logEvent, ILogEventPropertyFactory propertyFactory)
    {
        var props = logEvent.Properties.ToDictionary(p => p.Key, p => p.Value);
        foreach (var prop in props)
        {
            if (IsSensitive(prop.Key))
            {
                logEvent.AddPropertyIfAbsent(propertyFactory.CreateProperty(prop.Key, "***"));
            }
        }
    }
}

然后注册进去：

csharp复制.Enrich.With<MaskingEnricher>()

如果你用的是 Destructure 机制，还有一种更精细的玩法是控制对象反序列化策略，比如把某个类型里的特定属性替换成掩码。这个能力在记录复杂请求对象时非常有用，比在日志模板里手动脱敏要安全得多，因为开发人员根本不可能忘记遮掩，策略在框架层就兜住了。

5.2 三个最常见的性能陷阱

第一个陷阱是我前面提到的字符串插值模板。logger.Information($"User {userId} logged in") 除了丢字段，还会带来不必要的字符串开销。消息模板的正确写法是让 Serilog 在内部做格式化，它能把模板中的占位符当成属性名字，只有在最终输出时才渲染字符串。而且 Serilog 3.x 对消息模板做了缓存和优化，性能非常可观。

第二个陷阱是在消息参数里直接传大对象：

csharp复制logger.Information("Request payload: {@Payload}", payload);

这里 @ 是告诉 Serilog 对对象做结构化展开。有用，但如果你传给它的对象是一个几十个字段的 DTO，而日志级别被过滤掉的话，这会有不少开销。更合理的是只记录需要追踪的关键字段，或者在过滤表达式里精确控制，避免在热路径上把整个大对象序列化。

第三个陷阱是同步文件 I/O 阻塞业务线程。默认的 File Sink 是同步写入的，虽然 Serilog 内部有批量缓冲，但在极端高并发下文件写入会成为瓶颈。解决办法是用 Serilog.Sinks.Async 包，把写盘操作丢到后台线程：

csharp复制.WriteTo.Async(a => a.File("logs/app-.log", rollingInterval: RollingInterval.Day))

实测下来，高吞吐场景下启用异步 Sink 之后，业务接口的 P99 延迟能降 20%~40%，这个数字在日志量大的服务里非常可观。

5.3 排错自检清单：日志没写、重复日志、字段丢失

日志这东西平时看似简单，真出起问题来也让人头疼。这里整理我实际遇到过的高频故障和对应的排查思路，做成一张自检表：

还有一个老生常谈的问题：在进程退出前记得调用 Log.CloseAndFlush()。有时候你发现日志少了几行甚至几十行，原因往往就是进程退出时异步缓冲还没刷盘，日志就丢了。在 Program.cs 的 Main 里包一层 try/finally 是最稳妥的做法。

最后一个生产环境的建议：如果你的服务是部署在容器里的，控制台 Sink 很容易被 Kubernetes 的日志采集器收集，这时候你不需要再往容器里写文件。换句话说，容器环境优先控制台 + JSON 格式，虚拟机环境优先文件 + 留存策略，这两种部署模式对应完全不同的配置思路，别一套配置走天下。

说回我自己的体会。日志改造这件事，投入产出比其实非常高——你花一天时间把 Serilog 结构化日志在项目里落地，后续每次排查问题都能省下几个小时。我现在接手新项目的第一件事，就是看它日志是怎么打的。如果是 Serilog 结构化日志，我心里立刻有底；如果还是字符串拼接，我就会先建议团队把日志方案整体升级。因为一个连日志都没结构化的系统，就像一本没有目录的账本，平时看不出问题，出事的时候才追悔莫及。这套方案从认知到落地并不复杂，难的是下定决心去做，并且把每个细节都按生产标准来要求。