观测性基线：日志、Tracing 与 Token 成本看板（Agent 必备）

观测性是 Agent 的“第二条生命线”

第一条生命线是可靠性（幂等、限流、超时、熔断），第二条生命线是观测性。

没有观测性，你会陷入：

• 失败只能靠“再跑一次”
• 成本上涨只能“先降温度/换模型”
• 延迟变慢只能“加机器”

而正确的观测性应该让你能回答：

• 失败发生在：规划？检索？工具？校验？
• 失败类型是：超时？429？参数错？权限？
• 成本花在：哪个模型？哪个工具？哪种任务？

一、统一事件日志：把执行过程变成可查询的数据

1）日志对象：Run + Event

建议把一次任务定义为一个 run，run 内追加事件（event）。

事件至少覆盖：

• STEP_STATUS
• TOOL_CALL
• TOOL_RESULT
• RETRY_DECISION
• OUTPUT_VALIDATION
• DONE/FAILED

2）最小字段规范

每条事件建议包含：

• tenantId/userId/threadId/runId
• eventId/seq/ts
• eventType
• durationMs
• errorType（如有）
• cost（token/费用，如有）

重要：工具参数要脱敏。不要把密钥、手机号、邮箱明文进日志。

二、Tracing：把端到端时间切开，才能优化 p95

1）一个 run 应该有一条 trace

trace/span 最小分段：

• llm.generate
• rag.retrieve
• tool.call.<toolName>
• output.validate

你最终要得到类似这样的时间占比：

• 端到端 12s，其中模型 6s，检索 1s，工具 4s，其他 1s

没有这些分段，你无法判断“该优化哪里”。

2）把重试也纳入 span

重试是 Agent 成本与延迟的主要来源之一。

建议为每次重试建 span，并打标签：

• retry.count
• retry.reason（timeout/429/5xx）
• backoffMs

这样你才能发现“某工具重试风暴”。

三、成本看板：把 token 变成可治理指标

1）为什么 token 看板必须能切维度

一个总 token 数没有意义。你需要按维度切：

• tenant/user
• 任务类型
• 模型
• 工具
• prompt 版本

否则你找不到成本飙升来自哪。

2）最小成本分解

建议至少拆成：

• llm_input_tokens
• llm_output_tokens
• llm_cost
• tool_cost（若工具计费）
• storage_cost（可选）

并把它们与质量指标关联：

• 成功率
• 输出校验失败率
• 用户重试率

看板的目标是找到：

• 花钱但失败（最优先修）
• 花钱但收益小（可降级）
• 不花钱但失败（通常是流程/校验/数据问题）

四、最小可用指标集（建议先把这组做对）

1）质量与稳定性

• 成功率（按任务类型）
• 失败原因分布（timeout/429/schema/permission/validation）
• 幂等冲突数（重复写入风险信号）

2）性能

• 端到端 p50/p95/p99
• 首字延迟（前端可感知）
• 工具调用耗时分布（按 toolName）

3）成本

• 平均 token（按模型/任务类型）
• 工具调用次数（按任务类型）
• 重试次数分布（p95/p99）

这些指标能覆盖你最常见的生产问题。

五、用观测性驱动迭代：一个可执行的闭环

建议每周做一次“失败复盘看板”：

1. Top 3 失败原因
2. Top 3 成本最高任务类型
3. Top 3 最慢工具

对每项输出：

• 现象（指标）
• 根因（事件日志 + trace）
• 改动（prompt/schema/tool/策略）
• 验证（对比改动前后）

这样迭代就会从“感觉”变成“证据”。

六、上线 Checklist（可观测性基线）

• 事件日志：run + event，可查询可聚合
• Trace：每个 run 一条 trace，模型/检索/工具分段
• 错误分类：timeout/429/permission/schema/validation
• 成本采集：input/output token + 费用维度
• 指标看板：成功率、p95、失败分布、token、重试分布
• 脱敏：日志不包含密钥/PII 明文

常见问题

我需要把每个 token 的流式 delta 也打点吗？

不建议。delta 级别太细，会产生海量日志。通常只需要：首字时间、完成时间、关键里程碑事件与错误/重试事件。

怎样把“用户体验”与“后端 trace”关联？

用同一个 runId/traceId 贯穿前后端。前端埋点携带 runId，后端 trace/span 也携带 runId，你就能从“某次用户卡住”回溯到具体的 tool call。

想看更多工程化文章见 /articles，也可以在 /apps/new 体验 Agent 能力。