进阶 pydantic.dev 2026-11-20 05:57:40 · 5 阅读

第15章 日志与 Traces:为什么日志不够用

开发者经常问我:"我都有日志了,为什么还需要 trace?"这个问题我自己也困惑了很多年。 简单说:一行日志只记录某个时间点发生了一件事。而一个 span 记录的是一次操作,带有 trace ID、span ID、parent span ID,以及开始和结束时间。这些字段能告诉你哪些操作属于同一个请求、谁调用了谁、时间花在了哪里。普通日志不带这些信息,你只能靠猜。 详细的答案,演示比解释更直观。

一个耗时两秒的结账请求

下面是一个结账处理函数。它并发加载购物车和折扣信息,然后向用户扣款。三个用户同时结账,其中一个的折扣服务很慢。

(代码块保持原样不译) 输出如下: (日志输出保持原样)

其中一次结账花了大约两秒。是哪个用户?最后那条 "checkout finished" 对应三条 "checkout started" 中的哪一条?日志无法回答。

只有三个请求时,你眯着眼还能推出来。但如果每秒三百个请求,不同请求的日志行交错在一起,就完全无从下手了。

加上 request ID

常见的做法是加一个 request ID:把它存进 contextvars.ContextVar,再用 filter 加到每条日志里。用它替换第一个例子里的 logging.basicConfig 调用:

(代码保持原样)

然后 checkout 在第一条日志之前调用 request_id.set(uuid.uuid4().hex[:8])。由于 asyncio 会把 context 复制到每个 task,fetch_cart 和 fetch_discounts 能看到同一个 ID:

(日志保持原样)

这样好多了。按 16bac7c6 过滤,就能看到一个请求的全部日志。但要读懂它,你还是得手动做时间戳减法。

"cart loaded" 和 "discounts loaded" 之间相隔 1.9 秒,但折扣并不是花了 1.9 秒。两个调用是同时开始的,所以折扣花了 2.0 秒,购物车花了 78 毫秒。两行日志之间的时间差会被算到中间运行的代码头上,而日志并没有标明那是什么代码。一个没人打日志的阻塞调用,看起来和折扣服务变慢一模一样。

“可是我有带 request ID 的结构化日志”

这是我听到最多的回答,而且确实有道理。假设每行日志都是 JSON,每个服务都传递 request ID,每个操作结束时都记录 duration_ms。下面是同一个程序里那次慢结账、用 JSON 格式化后的输出:

(JSON 保持原样)

就这个请求而言,这些信息够用了。duration_ms 表明折扣花了 2001 ms。如果你的所有请求都是这样,那继续用日志没问题。

但在三种情况下就不够了。

同一个操作运行了两次

比如 fetch_discounts 超时后重试,或者结账流程对每个商品都加载一次折扣。此时请求里会有两条 discounts loaded。request ID 只能说明它们属于这个请求,却说不清 charge 等待的是哪一条,也说不清是结账流程里的哪次调用发出的。要做到这一点,每个操作都需要自己的 ID 和调用者的 ID。

操作永远没结束

duration_ms 是操作结束时才写入的。如果折扣服务一直挂起直到客户端放弃,或者进程被杀掉,这个请求就只有一条 checkout started,别的什么都没有。你知道出了问题,但不知道问题在哪。Logfire SDK 启动一个 span 时可以先发送一个 pending span,这样即使操作永远没结束,也会留下它及其父操作的记录。

你的依赖库不打你的 request ID

你的 HTTP 客户端、数据库驱动、支付 SDK 都不知道你的 request_id 字段。别的团队的 service 可能把它叫作 correlation_id。request ID 只覆盖你自己写的日志,而 OpenTelemetry instrumentation 连依赖库也能覆盖,并且各家 OpenTelemetry SDK 默认读写同一个 traceparent 头。

要补齐这些,就得加更多字段:每个操作的 ID、调用者的 ID、"started" 事件,以及一个在服务间传递 ID 的 header。下面就是你亲手造出来的东西:

你给日志加的字段OpenTelemetry 的对应物
Request IDtrace_id
Operation IDspan_id
调用者的 Operation IDparent_span_id
"started" 事件和 duration_msSpan 的 start_time 和 end_time
携带 request ID 和调用方操作 ID 的 headertraceparent header,包含 trace_id 和调用方的 span_id

这些正是 span 的字段,只不过是你手动维护在日志里的。你等于重新发明了 trace,一个字段一个字段地造,没有标准格式,也没有工具能理解它。

表格最后一行那个 header 其实已经是标准了。W3C Trace Context 定义了 traceparent,用于在服务之间传递 trace ID 和调用方的 span ID:

traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

HTTP 客户端和服务端的 OpenTelemetry instrumentation 会自动读写它,不用你操心。

同样的代码,用 span 实现

下面还是那个结账程序,改用 Pydantic Logfire。每个函数都是一个 span,用 @logfire.instrument 创建。运行前先 pip install logfire 安装,再按入门指南用 logfire auth 登录:

(代码保持原样)

没有 request ID,没有 filter,也没有 "started" 日志。每次结账都有自己的 trace。下面是慢的那次的 span 列表,后三个都是 checkout span 的子 span:

Span开始时间耗时
checkout user_id=20 ms2176 ms
fetch cart0 ms69 ms
fetch discounts1 ms2001 ms
charge2002 ms174 ms

Logfire 会把这些画成瀑布图,但光是这张表就已经回答了问题:fetch cart 和 fetch discounts 是并行执行的,折扣花了 2001 ms,charge 在两者都完成之后才开始。你不用做任何减法。

跨请求能问的问题

排查一个慢请求是调试。接下来的问题通常是:“这种情况多久发生一次?发生在哪?”用日志,你得从消息字符串里解析耗时;用 span,duration 就是一列数据。

Logfire 把完成的 span 存进一张可以用 SQL 查询的 records 表:

(SQL 保持原样)

这样就能拿到结账每一步的 p95。用 parent_span_id IS NULL 过滤可以只看整个结账流程,用 attributes->>'user_id' 分组则可以按用户拆分。

没人写过的日志行

日志只包含有人决定记录的内容。如果没人给数据库查询打日志,它就只是两个时间戳之间的空白。

Instrumentation 库会为不是你写的代码创建 span。在 Logfire 里,每个库只需一行代码:

logfire.instrument_fastapi(app) logfire.instrument_httpx() logfire.instrument_asyncpg()

每个请求、每次出站 HTTP 调用、每条 SQL 查询都变成一个带时长和父关系的 span。HTTPX 和 FastAPI 的 instrumentation 还会读写 traceparent 头,所以一个跨越三个服务的请求仍然是一条完整的 trace。

日志可以保留

Trace 不是用来取代日志的。有些东西是事件而非操作:缓存未命中、重试决策、校验警告。它们没有时长,日志行才是合适的形态。

改变的是:span 内的日志行会自动带上 span 的上下文。用 LogfireLoggingHandler 把标准库日志发给 Logfire:

(代码保持原样)

discounts loaded 会作为 checkout span 的子记录存储,共享同一个 trace ID。你现有的 logger.info 调用照常工作,而且每条都能说明自己来自哪个请求。

所以,有日志还需要 trace 吗?如果你的日志已经带上了 request ID、操作 ID、调用者的操作 ID、开始和结束时间,那你其实已经拥有 trace 的全部数据,只是以文本形式存储。Span 用 OpenTelemetry 格式承载同样的字段,tracing 后端能直接读取,Logfire 还能让你把它们当 SQL 列来查询。

评论 (0)