Observability on Coding with Denglei

EF Core 慢查询排查实战：TagWith、OpenTelemetry 与执行计划

Tue, 16 Jun 2026 17:04:23 +0800

EF Core 性能问题里，最折磨人的不是“慢”，而是“慢得没规律”，线上卡，测试又无法复现。

很多小D、小W同学都经历过这种现场：

压测数据很好看
数据库 CPU 没打满
业务代码看起来也没什么大问题

你改了几个 Include，可能短期有效，但过两周又抖回来。根因往往不是某一行 LINQ 写错，而是整条排查链路没打通。

这篇文章就做一件事：给你一套能线上落地的 EF Core 慢查询定位闭环，从应用日志一路追到数据库执行计划，不靠猜。

问题背景：为什么本地快、线上慢

真实场景：订单列表接口平时 80ms 左右，高峰时段 P95 抬到 1s。你的第一反应是“数据库是不是扛不住了”，但监控显示：

数据库 CPU 长期低于 50%
连接池没有打满
磁盘 IO 没明显异常

排查下来，又遇到两个组合问题：

列表查询没有打 SQL 标签，日志里几百条 SQL 根本分不出谁是谁
某些筛选条件线上本地索引匹配不同，SQL 文本相同但参数分布不同，执行计划差异很大

也就是说，问题不是“不会优化 SQL”，而是“看不见慢点在哪”。

原理解析：慢查询定位为什么总是卡在一半

EF Core 的查询链路大致是：

LINQ 表达式翻译成 SQL
命令发送到数据库执行
结果集回传并在应用层物化

很多排查第一步都把 SQL 抓出来看看，忽略了第 2、3 步的上下文信息，比如：

这条 SQL 是哪个接口触发的
这次慢是数据库执行慢，还是返回数据太大导致物化慢
慢的是固定 SQL，还是同模板下某些参数更慢

要拿到这些信息，最实用的组合就是：

TagWith：给 SQL 打业务标签
OpenTelemetry：采集耗时、TraceId、SQL 标签并统一上报
执行计划：确认索引命中、回表、扫描和 Key Lookup

三者合起来，才能形成可服用、可验证的排查闭环。

EF Core 拦截器实战：SaveChangesInterceptor、CommandInterceptor 与审计落地

Tue, 16 Jun 2026 17:04:23 +0800

审计不是“给表补几个 CreatedBy 字段”，也不是“在业务方法里顺手记日志”。它本质上是系统级可追溯能力，设计目标是让系统在任何写路径下都能稳定回答四个问题：谁发起、改了什么、何时发生、通过哪条链路触发。

真正的难点不在 API 用法，而在系统设计阶段是否把审计定义成基础设施能力。这里聚焦两层落地：SaveChangesInterceptor 负责实体变更审计，CommandInterceptor 负责 SQL 执行审计，两者一起组成可观测、可追溯、可审计的最小闭环。

1. 问题背景：为什么审计必须在系统设计期落地

如果你刚开始做系统设计，通常会先把功能跑通，再逐步补监控、日志和审计。这条路径很正常，但系统从单一写入口演进到多入口后，审计会出现一些典型断层：

HTTP 请求有 TraceId，但数据库变更记录无法关联到具体调用链路。
Web 接口有审计字段，批处理、后台任务、集成事件消费链路没有统一审计。
SQL 慢查询能看到语句本身，但看不到对应业务场景和调用来源。
合规追查时能找到结果，找不到完整过程和责任主体。

这些现象不是某个人“写错了”，而是系统设计阶段还没有建立统一审计模型：

还没先定义统一的审计契约（身份、时间、来源、关联链路）。
写入路径没有统一审计入口，不同调用通道口径自然会分化。
变更审计和 SQL 观测没有打通，排障时很难快速复原完整链路。
只有开发约定，没有系统级自动机制，随着迭代推进就容易出现漏记。

这篇文章要解决的核心问题不是“把审计代码写到哪一层”，而是“如何在系统层提供默认生效、可验证、可扩展的审计能力”，并且让这套能力能跟着系统规模一起演进。

2. 原理解析：先拆职责，再落地拦截器

如果你是第一次从系统设计角度做审计，最稳妥的方法是先做职责拆分，再做实现落地。这里按“三步法”来理解：先统一实体变更审计，再统一 SQL 观测入口，最后明确拦截器边界。

2.1 第一步：用 SaveChangesInterceptor 统一实体变更审计

SaveChangesInterceptor 适合处理实体状态相关规则，例如：

Added 时补 CreatedAt/CreatedBy
Modified 时补 UpdatedAt/UpdatedBy
软删除时把 Deleted 改写成 Modified + IsDeleted

这类逻辑和实体状态强相关，放在拦截器里能覆盖所有调用路径，避免每个 Service 重复写一遍。

2.2 第二步：用 CommandInterceptor 统一 SQL 观测入口

DbCommandInterceptor 适合做 SQL 级别的统一观测：

慢 SQL 记录
SQL 失败统一日志
参数快照和调用耗时

它不适合做业务决策，但非常适合做“排障入口统一化”。

Serilog + OpenTelemetry：从请求日志到链路追踪的关联落地

Tue, 16 Jun 2026 17:04:23 +0800

这篇直接给落地方案，不再讲结构化日志的背景概念。目标只有一个：在 ASP.NET Core 服务里，把 Serilog 日志和 OpenTelemetry 链路追踪打通，排障时可以从一条错误日志直接跳到完整 Trace。

1. 问题背景：这篇要交付什么

按下面步骤做完，你会得到一条可执行排障链路：

日志里稳定带上 TraceId、SpanId、RequestPath、RequestMethod
业务日志统一输出 OrderId、TenantId 这类主键字段
下游 HTTP 调用失败时，日志可直接回跳到同一 TraceId
现场排障固定为 3 步：查日志 -> 拿 TraceId -> 打开链路

这篇示例默认运行环境：

.NET 8
Serilog
OpenTelemetry + OTLP

2. 原理解析：实施前约定与字段契约

先把约定定下来，后面配置才不会反复返工。

2.1 平台层字段（必须统一）

TraceId：整条请求链路唯一键
SpanId：当前节点唯一键
RequestPath：请求路径
RequestMethod：请求方法
StatusCode：响应码

2.2 业务层字段（按场景补充）

订单域：OrderId、CustomerId
多租户：TenantId
外部依赖：DependencyName、DownstreamStatusCode

2.3 字段命名规则（一次定死）

统一使用 PascalCase
同义字段只保留一个名字，比如只用 TraceId
业务字段保持稳定，不随文案调整

3. 示例代码：按步骤落地

3.1 安装依赖

Serilog.AspNetCore
Serilog.Sinks.Console
Serilog.Enrichers.Environment
OpenTelemetry.Extensions.Hosting
OpenTelemetry.Instrumentation.AspNetCore
OpenTelemetry.Instrumentation.Http
OpenTelemetry.Exporter.OpenTelemetryProtocol

3.2 第一步：配置 Serilog 与 OpenTelemetry

把这段放进 Program.cs，先打通基础链路：

Serilog：从结构化日志认知到 .NET 工程落地

Tue, 16 Jun 2026 17:04:23 +0800

问题背景

很多项目不缺日志，缺的是有用的日志。

平时接口跑得顺，大家都觉得日志够用。真到线上出问题，日志的短板会一下子暴露出来。

比如订单接口偶发超时，日志里只剩这么一句：

Create order failed for customer 1024, cost 3800ms, trace abc123

这种日志平时看着还行，真到线上排障时基本帮不上太多忙：

你没法直接按 CustomerId、TraceId、ElapsedMs 做过滤和聚合，只能全文搜索
同一个字段今天写 customerId，明天写 userId，后天又换成 client_id，查询条件根本沉淀不下来
想统计某类错误的数量、平均耗时、失败占比，往往还得写额外脚本二次清洗
日志平台能做的分析能力很弱，因为它拿到的只是一段文本，不是一条可分析的数据

问题往往不在于日志打得不够多，而在于日志从一开始就没按可检索、可聚合、可关联的方式去设计。

传统文本日志更像写给人看的备注，结构化日志才像写给系统消费的数据。业务一旦进入多人协作、线上排障、统一观测这些阶段，日志就不再只是打出来看一眼，而是排障、审计、告警、指标补充、链路追踪的一部分。走到这一步，结构化日志就不是锦上添花，而是该补的基础课。

原理解析

什么是结构化日志

很多人第一次接触结构化日志，会下意识把重点放在 JSON 输出上。其实 JSON 只是表现形式，核心不在日志长什么样，而在日志里的字段有没有明确语义，后续能不能被系统稳定识别。

先看两种写法的差异。

普通文本日志：

logger.LogInformation(
    $"Order {order.Id} created for customer {order.CustomerId}, amount {order.Amount}, cost {elapsedMs}ms"
);

这行代码最终只会产出一段字符串。人类看没问题，但日志平台拿到以后，并不知道哪一段是订单号，哪一段是金额，哪一段是耗时。

结构化日志：

logger.LogInformation(
    "Order {OrderId} created for customer {CustomerId}, amount {Amount}, cost {ElapsedMs}ms",
    order.Id,
    order.CustomerId,
    order.Amount,
    elapsedMs
);

换成这种写法以后，日志框架记录的就不再是一整段普通字符串，而是一个日志事件：

模板是 Order {OrderId} created for customer {CustomerId}, amount {Amount}, cost {ElapsedMs}ms
属性是 OrderId、CustomerId、Amount、ElapsedMs
元数据还包括时间、级别、异常、来源、线程、TraceId 这些上下文

输出到控制台时，它可以渲染成人能直接看的句子；送到 Elasticsearch、Seq、Loki 或 OpenTelemetry 后端时，它又能以字段化数据的形式被检索和聚合。

从 IApplicationBuilder 到 RequestDelegate：ASP.NET Core 请求管线性能与可观测性

Tue, 16 Jun 2026 17:04:23 +0800

很多团队做性能优化时，第一反应是改 SQL、加缓存、扩机器。结果接口还是慢，而且慢得不稳定。

这类问题里，有一部分根因并不在业务代码，而在请求进入业务之前就已经产生了: 中间件顺序、重复序列化、过重日志、异常处理位置不当，都会把每个请求的固定成本悄悄抬高。

这篇文章我们不讲抽象概念，直接从一个真实工程场景出发，拆开 ASP.NET Core 请求管线，回答三个问题:

请求管线到底是怎么执行的
哪些中间件写法会稳定拉低吞吐
如何在不牺牲可观测性的前提下，把链路成本控制住

1. 问题背景: 为什么明明 CPU 不高，RT 却在抖

先看一个常见现象:

峰值时段 P95 从 35ms 涨到 90ms
CPU 只到 45%
数据库监控正常
线程池没有明显爆满

像商场收银台排队: 收银员速度没变，库存系统也没卡，但每位顾客在真正结账前都要先填两张表、复印一次小票、走一段绕路。单人多花 10 秒，队伍就会在高峰时段整体失控。

在 Web 服务里，这段“真正结账前的绕路”就是请求管线上的固定开销。

典型问题包括:

将高成本日志中间件放在链路最前面，且对所有请求都做完整 Body 记录
鉴权、异常处理、路由等中间件顺序错误，导致重复执行或额外分支判断
在中间件中做同步阻塞 I/O
将一些本该按采样写出的指标，变成了每请求都完整打点

2. 原理解析: IApplicationBuilder 如何变成 RequestDelegate

ASP.NET Core 启动时，IApplicationBuilder 会把你注册的中间件构造成一个 RequestDelegate 链。

关键点只有两个，但经常被忽略:

中间件按“注册顺序”进入，按“逆序”包裹执行。每个中间件把后续链路作为自己的 next，形成嵌套闭包。
任意中间件都可以不调用 next()，从而短路后续链路。

一个简化模型如下:

RequestDelegate app = context => Task.CompletedTask;

app = MiddlewareC(app);
app = MiddlewareB(app);
app = MiddlewareA(app);

// 实际执行顺序: A -> B -> C -> Endpoint -> C -> B -> A

这意味着: