LLM 应用为什么必须有 trace:一次对话里的五次模型调用
前言
一个 Agent 应用最开始的日志大概长这样:
[INFO] 收到请求 q="帮我查下上周的销售数据" [INFO] 检索命中 5 条 [INFO] 调用模型 model=gpt-4o tokens=1200 [INFO] 工具调用 query_db [INFO] 调用模型 model=gpt-4o tokens=2400 [INFO] 返回
单用户测试时够用。一旦并发上来,这堆日志就废了——20 个用户同时在问,日志交错在一起,你没法把"检索命中 5 条"和"调用模型 tokens=1200"对应到同一个请求上。
更根本的问题是:日志是扁平的,而 LLM 应用天然是树状的。
一次提问会展开成一棵调用树:
用户请求 ├── 改写查询(LLM 调用 1) ├── 向量检索 │ └── embedding 调用 ├── 重排(LLM 或 cross-encoder) ├── 生成回答(LLM 调用 2) │ ├── 工具调用:查数据库 │ └── 生成回答(LLM 调用 3,带工具结果) └── 后处理
要回答"这次为什么慢""这次为什么贵",必须有这棵树。日志给不了,trace 可以。
一、span 该怎么切
切 span 的原则只有一条:一个 span 对应一次你可能想单独度量的操作。
对 LLM 应用,粒度大致是这样:
| 层级 | span 名 | 代表什么 | 关键看什么 |
|---|---|---|---|
| 根 | invoke_agent | 一次完整的用户请求 | 端到端耗时、是否成功 |
| 中层 | chat | 一次模型调用 | 首 token 延迟、token 数、模型名 |
| 中层 | retrieve | 一次检索 | 召回条数、耗时、索引名 |
| 中层 | execute_tool | 一次工具调用 | 工具名、是否失败、耗时 |
| 叶 | embeddings | 一次向量化 | 条数、维度、耗时 |
关键在于中层 span 必须能反映"决策点"。比如一个 Agent 一次请求里调了 5 次 LLM(思考→调工具→再思考→再调工具→总结),那就该有 5 个 chat span,而不是一个把 5 次都盖住的 span。否则你没法回答"是第几次调用慢"。
同理,检索如果是"多路召回再融合",每一路都应该有独立 span——这样才知道是哪一路拖慢了整体。
二、属性记什么:对齐语义约定,别自己发明名字
OpenTelemetry 有一套 GenAI 语义约定(semantic conventions),专门规定 LLM 相关的属性和 span 名。主要属性:
| 属性 | 含义 | 例子 |
|---|---|---|
gen_ai.operation.name | 操作类型 | chat / embeddings / execute_tool |
gen_ai.provider.name | 模型提供方 | openai / anthropic / huaweicloud |
gen_ai.request.model | 请求的模型 | gpt-4o-mini |
gen_ai.response.model | 实际响应的模型 | gpt-4o-mini-2024-07-18 |
gen_ai.usage.input_tokens | 输入 token | 1200 |
gen_ai.usage.output_tokens | 输出 token | 340 |
gen_ai.response.finish_reasons | 结束原因 | ["stop"] |
为什么要用约定名而不是自己起名:因为你迟早要接现成的观测平台(Langfuse、Phoenix、或者华为云 APM 这类)。用了约定名,面板、聚合、告警都能直接用;自己起 llm.tokens_in 这种名字,等于每次换平台都要重写一遍查询。
⚠️ 需要说明的是,这套语义约定目前仍在演进。比如早期的 gen_ai.system 后来被建议改为 gen_ai.provider.name。实际落地时以你使用的 SDK 版本为准,别硬抄网上过期的文档。
除了约定属性,下面几个是业务侧的必需项:
| 属性 | 为什么必须 |
|---|---|
session.id | 把多轮对话串起来,看"第 3 轮为什么效果变差" |
user.id(脱敏后) | 定位"只有某个用户出问题"这类反馈 |
agent.name | 多 Agent 系统里区分是哪个 Agent |
retrieval.top_k / retrieval.hit_count | 检索效果出问题时,这是第一个要看的数 |
三、采样的坑:按比例采样会把证据丢掉
观测平台都按采样存数据,成本考虑。而默认的固定比例采样,在 LLM 应用里是错的。
原因:出问题的请求往往只占极少数。固定采 10%,意味着 90% 的失败链路你看不到。而失败链路恰恰是你唯一想看的东西。
正确做法是 tail sampling(尾部采样):先全量接收 span,等一条 trace 结束后再决定要不要丢。
典型策略:
policies:
- type: status_code # 出错的全留
status_code: { status_codes: [ERROR] }
- type: latency # 慢的留(比如 > 5s)
latency: { threshold_ms: 5000 }
- type: string_attribute # 特定用户/会话全留
string_attribute: { key: user.id, values: ["u_debug"] }
- type: probabilistic # 剩下的按比例采
probabilistic: { sampling_percentage: 5 }
顺序有意义:先保住异常,再对正常流量降采样。
代价是需要在收集端缓存整条 trace 一段时间(等它结束),内存开销比 head sampling 大。对 LLM 应用来说这笔开销值得——它换来了"每次事故都有完整现场"。
四、prompt 和 completion 到底存不存
这是落地时最纠结的问题。
存的好处:能复现。"用户说回答不对",你打开 trace 看到当时的 prompt 和模型输出,三分钟定位。不存的话只能猜。
存的代价:
| 代价 | 具体影响 |
|---|---|
| 体积 | 一条 trace 可能几十 KB 到几百 KB,存储成本是普通 API 的十倍以上 |
| 合规 | prompt 里可能有用户隐私、内部数据,存下来就受数据留存政策约束 |
| 泄露 | 观测平台往往权限更松,等于多了一个数据出口 |
三条可选的折中路线:
路线 A:只存摘要。记录 prompt_hash、字符数、token 数、前 200 字符。能做基线对比("这条 prompt 最近变长了"),但不能复现内容。
路线 B:按开关存。生产默认不存,出问题时打开采样率 100% 重跑一段时间。需要能快速改配置。
路线 C:加密存 + 短留存。加密入库,保留 7 天,只给值班人解密权限。
实践中比较合理的组合:结构化摘要常存(路线 A)+ 内容在异常时存(配合 tail sampling 的错误策略)。正常请求只留元数据,出错的请求把完整 prompt 留下来。这样存储成本可控,而真正需要看的场景都有数据。
五、埋点代码
下面是一段手动埋点的骨架,用 Python + OpenTelemetry。核心是父子关系靠 context 自动传播,不要手动指定 parent。
import json
from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode
tracer = trace.get_tracer("agent.llm")
def hash_short(text: str) -> str:
import hashlib
return hashlib.sha256(text.encode()).hexdigest()[:16]
def invoke_agent(question: str, session_id: str, user_id: str):
with tracer.start_as_current_span("invoke_agent") as span:
span.set_attribute("gen_ai.operation.name", "invoke_agent")
span.set_attribute("session.id", session_id)
span.set_attribute("user.id", user_id) # 传进来之前先脱敏
try:
rewritten = rewrite_query(question, session_id)
docs = retrieve(rewritten, top_k=5)
answer = generate(question, docs, session_id)
span.set_status(Status(StatusCode.OK))
return answer
except Exception as e:
span.set_status(Status(StatusCode.ERROR, str(e)[:200]))
span.record_exception(e)
raise
def chat(messages, model, temperature=0.2, stream=False):
with tracer.start_as_current_span("chat") as span:
span.set_attribute("gen_ai.operation.name", "chat")
span.set_attribute("gen_ai.provider.name", "openai")
span.set_attribute("gen_ai.request.model", model)
span.set_attribute("gen_ai.request.temperature", temperature)
span.set_attribute("llm.stream", stream)
# 默认只记摘要;需要复现时打开内容记录
prompt_text = json.dumps(messages, ensure_ascii=False)
span.set_attribute("llm.prompt.hash", hash_short(prompt_text))
span.set_attribute("llm.prompt.chars", len(prompt_text))
if RECORD_CONTENT: # 配置开关
span.set_attribute("llm.prompt.preview", prompt_text[:1000])
resp = _real_chat_call(messages, model, temperature, stream)
span.set_attribute("gen_ai.response.model", resp.model)
span.set_attribute("gen_ai.usage.input_tokens", resp.usage.input_tokens)
span.set_attribute("gen_ai.usage.output_tokens", resp.usage.output_tokens)
span.set_attribute("gen_ai.response.finish_reasons", [resp.finish_reason])
return resp
def retrieve(query: str, top_k: int = 5):
with tracer.start_as_current_span("retrieve") as span:
span.set_attribute("gen_ai.operation.name", "retrieve")
span.set_attribute("retrieval.query", query[:200])
span.set_attribute("retrieval.top_k", top_k)
docs = _vector_search(query, top_k)
span.set_attribute("retrieval.hit_count", len(docs))
span.set_attribute("retrieval.index", "kb_v3")
# 记录分数分布,判断"召回质量"而不只是"召回数量"
if docs:
span.set_attribute("retrieval.top_score", round(docs[0].score, 4))
span.set_attribute("retrieval.min_score", round(docs[-1].score, 4))
return docs
def execute_tool(name: str, args: dict):
with tracer.start_as_current_span("execute_tool") as span:
span.set_attribute("gen_ai.operation.name", "execute_tool")
span.set_attribute("tool.name", name)
span.set_attribute("tool.args.hash", hash_short(json.dumps(args, sort_keys=True)))
try:
result = _dispatch(name, args)
span.set_attribute("tool.ok", True)
return result
except Exception as e:
span.set_attribute("tool.ok", False)
span.set_attribute("tool.error", str(e)[:200])
span.set_status(Status(StatusCode.ERROR))
raise
多层嵌套时不需要手动传 parent——start_as_current_span 会读当前 context:
answer = invoke_agent("上周销售怎么样", "s_001", "u_42")
# 自动形成: invoke_agent
# ├── chat(改写查询)
# ├── retrieve
# └── chat(生成)
六、从 trace 里能看出什么
埋好之后,几类问题变得可查:
| 现象 | trace 里的特征 | 指向 |
|---|---|---|
| 答非所问 | retrieve 的 hit_count 正常但 top_score 很低 | 检索质量,不是生成质量 |
| 有时快有时慢 | chat span 的耗时方差大 | 模型侧波动 / 队列排队 |
| 越用越贵 | 同一 session.id 下 input_tokens 逐轮增长 | 上下文没做裁剪 |
| 工具总失败 | execute_tool 的 tool.ok=false 集中在某个工具 | 工具参数校验或下游故障 |
| 只有个别用户出问题 | 按 user.id 聚合,某些值异常 | 权限、配额或数据隔离 |
第三行值得展开。多轮对话里 input_tokens 的增长曲线,是最容易被忽略的成本信号。 单看每条请求都不高,但一条会话聊到第 8 轮时,输入可能已经翻了五六倍——因为历史全带着。trace 上按 session.id 把 input_tokens 画成折线,一眼就能看出来。
做了什么
给现有的问答服务补了 trace:
- 按
invoke_agent / chat / retrieve / execute_tool四类切 span,一次请求里多次 LLM 调用各自独立 - 属性统一用
gen_ai.*语义约定名,业务侧补session.id、user.id、retrieval.hit_count - 采样改成 tail sampling:错误和慢请求全留,正常流量采 5%
- prompt 默认只存 hash + 长度 + 前 200 字符,配一个
RECORD_CONTENT开关,排查时临时打开 - 检索 span 额外记
top_score/min_score,用来区分"没召回到"和"召回到但分数接近噪音"
第 5 点是意外收获。以前只知道"这题答得不好",现在能一眼看出来是召回为空、还是召回了一堆 0.3 分的噪音。
一些体会
日志和 trace 的分工要划清。 日志记录"发生了什么事件"(用户登录、配置变更),trace 记录"这次请求内部怎么走的"。把 prompt、token 这类信息塞进日志,最后会得到一堆无法关联的行。
span 粒度宁细勿粗。 粗的 span 只告诉你"慢",细的 span 告诉你"慢在哪一步"。多加几个 span 的成本,远低于事后靠猜排查的成本。
固定比例采样是 LLM 可观测性里最常见的错误。 它的前提是"错误均匀分布",而 LLM 应用恰恰相反——大部分请求顺利,少数请求以各种奇怪的方式失败,而你只想看那些少数。
content 存不存,本质不是技术问题而是数据治理问题。 决定要不要存之前,先回答:谁能看?留多久?用户要求删除时怎么删?这三个问题答不上来,先只存摘要。
最后一点:trace 的价值在于事后。真正上线时,至少配两条告警——错误率、P95 首 token 延迟。trace 负责告诉你"为什么",告警负责告诉你"现在有问题"。
- 点赞
- 收藏
- 关注作者
评论(0)