今日 TL;DR
一次 AI 请求可能跨越检索、模型调用和工具执行。Trace 把步骤串起来,日志记录具体发生了什么,指标帮助观察整体趋势。三者都要考虑采样、隐私和成本;一次模型调用成功也不等于用户任务完成。
为什么今天学这个
本课按日历进入第 11 周。前两周课程目前存在缺档,本课不假装你已完成:先记住两个前置概念,任务有一个可判定的完成条件,模型输出和外部内容都不天然可信。明天会在这些信号的基础上设计队列与状态机。
排查一个“回答慢”的工单时,总耗时只能告诉我们用户等了多久,却不能说明时间花在检索还是模型上。另一方面,只盯单次请求也看不出问题是否普遍。可观测性是从系统产生的信号推断内部状态:先用指标发现范围,再用 Trace 缩小到步骤,用日志查具体错误。
一张图讲清楚
Trace 表示一次跨步骤的路径,span 表示其中一个有起止时间的操作;一个 Trace 可以有多个 span。日志是具体事件记录;指标是在一段时间内汇总的测量,例如请求次数和延迟分布。图中的步骤是示例,真实系统还可能有并发与重试。
三个核心要点
- 先定义任务结果,再埋点。 区分 HTTP 成功、模型调用成功和用户任务成功。比如检索到资料但回答没有引用,接口可能返回 200,业务仍可能失败。定义成功规则时保留无法自动判断的情况,别把未经验证的模型自评当成事实。
- 用共同上下文把步骤串起来。 给一次任务关联 trace ID,让检索、模型和工具各自记录耗时及状态;跨进程传递上下文。一次重试应能看出各次尝试与最终结果,不能把重试覆盖成一次成功。OpenTelemetry 的 Trace 文档描述了 span、上下文与父子关系。
- 指标看趋势,日志与 Trace 查原因。 按服务、操作和结果等低基数字段聚合成功率及延迟分布。用户 ID、请求 ID 或完整提示词不适合作为指标标签:它们可能让时间序列数量失控;敏感文本进入任何信号前还需数据最小化、脱敏与访问控制。
最小可运行示例
以下示例只用 Python 标准库模拟一次请求,不需要 API key,也不声称这是完整 OpenTelemetry 实现。保存为 observe_demo.py,运行 python3 observe_demo.py:
import json
import time
import uuid
trace_id = uuid.uuid4().hex
measurements = []
def step(name, fn):
started = time.perf_counter()
try:
result = fn()
except Exception as exc:
elapsed = (time.perf_counter() - started) * 1000
measurements.append((name, elapsed, "error"))
print(json.dumps({"trace_id": trace_id, "step": name,
"event": "failed", "error_type": type(exc).__name__}))
raise
elapsed = (time.perf_counter() - started) * 1000
measurements.append((name, elapsed, "ok"))
print(json.dumps({"trace_id": trace_id, "step": name,
"event": "finished", "duration_ms": round(elapsed, 2)}))
return result
try:
docs = step("retrieve", lambda: ["示例文档"])
answer = step("generate", lambda: f"参考了 {len(docs)} 条文档")
print(json.dumps({"trace_id": trace_id, "task_status": "completed",
"answer": answer}, ensure_ascii=False))
finally:
print(json.dumps({"metric": "step_count", "value": len(measurements),
"errors": sum(status == "error" for _, _, status in measurements)}))
预期输出两条包含同一 trace_id 的步骤记录、一条完成记录,最后输出步骤数 2、错误数 0。耗时与 ID 每次不同。把 generate 改成抛出异常后,应出现错误事件且错误计数为 1;这也说明失败不能只靠 HTTP 状态猜。示例仅展示关联思路,单次计数不是监控系统的持续聚合指标,也不提供跨服务上下文传播。
生产环境会怎么翻车
- 症状:总耗时很高,却查不到慢步骤。 根因可能是异步队列或下游调用未传播上下文。为队列生产和消费建立关联,检查丢失比例;不要通过把用户文本塞入上下文来补链。
- 症状:成本暴涨、仪表盘变慢。 根因可能是把每个请求 ID 当作指标标签。把高基数标识留给受控 Trace 或日志,指标只保留有限枚举,并设置数据保留期限。
- 症状:日志泄露简历、密钥或提示词。 根因是记录了完整请求。默认只记录必要元数据;设置字段白名单和脱敏策略,并限制访问。脱敏并不保证绝对安全,仍需按数据政策处理。
- 症状:成功率很好但用户仍抱怨。 根因是只统计模型或 HTTP 成功。增加业务完成信号,区分超时、取消、模型拒绝和结果未通过验证;抽样复核业务标签质量。
- 症状:找不到失败请求的 Trace。 根因可能是采样或导出失败。监测采样比例、导出丢失和队列压力;按风险与成本决定是否提高错误路径采样,并确认方案符合实际采样架构。
动手练习
用 15–30 分钟把上面的示例增加一个 validate 步骤:当回答不含“参考”时返回失败。分别运行正常和失败输入。完成条件:三步使用相同 trace ID;失败日志只包含错误类型而不打印输入;最终计数反映实际失败。再写一句话说明为什么这份本地输出还不等于线上监控。
面试表达
30 秒回答
我会先定义用户任务成功,再把检索、模型和工具调用关联到同一条 Trace。指标用来发现成功率和延迟变化,Trace 用来定位慢或失败的步骤,日志补充事件细节。埋点默认不记录敏感正文,并控制指标标签数量和采样成本。
追问与 3 分钟回答
如果用户反馈很慢,我会先按时间、服务和操作看延迟分布及错误率,确认是普遍问题还是少量个例,再抽取相关 Trace 比较检索、模型和排队时长。发现工具调用反复重试时,还要确认超时、重试次数和最终状态。业务成功率需要从任务最终状态计算,不能把模型返回视作成功。上线前验证上下文是否跨服务传播、敏感字段是否被过滤,并监测导出失败与采样带来的盲区。若调用量不大,先做基础埋点和日志关联即可,不必一开始引入复杂平台。
今日自测
1. 基础理解
Trace 和 span 分别描述什么?
查看答案
Trace 描述一次请求或任务的路径;span 描述其中一个操作及其时间、状态和上下文。一个 Trace 通常包含多个相互关联的 span。
2. 工程取舍
为什么不能把 trace ID 直接用作所有指标的标签?
查看答案
每次请求都可能产生不同 ID,导致指标时间序列数量急剧增长。可以在受控的 Trace 和日志中保留关联标识,指标使用低基数维度。
3. 场景应用
HTTP 200 很多,但用户任务成功率下降,先查什么?
查看答案
核对业务成功判定是否可靠,再按任务最终状态和步骤拆分,查看验证失败、取消和工具错误;用样本 Trace 与受控日志定位,不应直接断言模型故障。
市场雷达
本期无新增市场信号。
权威来源
- OpenTelemetry:Traces — Trace、span 和上下文的基本概念。
- OpenTelemetry:Metrics — 指标测量和聚合的基本概念。
- OpenTelemetry:Logs — 日志信号及其与上下文关联。
明天会用到
明天进入队列与状态机:把今天记录的任务状态、排队时间和步骤结果放进可恢复的异步执行流程。