跳到主要内容

Trace与Span

1. 定义与边界​

Trace（链路追踪）表示一次 Agent 任务的完整执行过程。Span（跟踪片段）表示其中一个可观测步骤，例如一次模型调用、一次工具调用、一次检索、一次护栏检查。Trace 与 Span 解决的是跨组件定位问题，不是替代业务日志。

2. 为什么重要​

生产问题常常跨系统：用户请求进入网关，Agent 调模型，模型选择工具，工具查数据库，数据库超时，Agent 重试并给出错误回答。没有 trace/span，团队很难知道慢在哪里、错在哪里、谁触发了动作。

3. 核心机制​

Span 应包含：

  • parent_span_id：还原调用树。
  • start/end time：计算耗时和瓶颈。
  • attributes：模型、工具、任务类型、风险等级。
  • events：重试、异常、流式输出、人工确认。
  • status：ok、error、cancelled、denied。

4. 工程实现​

{
  "trace_id": "tr_refund_001",
  "span_id": "sp_tool_002",
  "parent_span_id": "sp_agent_loop_001",
  "name": "tool.refund_payment",
  "kind": "client",
  "start_time": "2026-05-09T10:00:01Z",
  "end_time": "2026-05-09T10:00:03Z",
  "attributes": {
    "agent.version": "3.1.0",
    "gen_ai.operation.name": "tool_call",
    "tool.name": "refund_payment",
    "tool.risk": "payment"
  },
  "status": {"code": "ERROR", "message": "policy_denied"}
}

5. 生产实践​

  • trace_id 要通过 HTTP header、消息队列 metadata、工具调用上下文传递。
  • Span 命名要稳定，例如 model.plan、retrieval.search、tool.get_order。
  • 不要把高基数字段无限塞入 attributes，例如完整 prompt、完整文档内容。
  • 采样策略要区分普通任务和高风险任务；错误和安全事件应优先保留。

6. 常见反模式​

  • 每个组件各自生成 id，无法串起来。
  • 所有步骤都记录成同一种 span，无法区分模型、检索、工具。
  • 只采样成功请求，导致事故分析缺证据。
  • Trace 中包含未脱敏原文，扩大数据泄漏面。

7. 评测方法​

指标用途
Trace Completeness关键 span 是否完整
Parent-child Validity调用树是否可还原
Error Span Coverage错误是否带状态、错误码和原因
Cross-service Propagation跨服务 trace_id 是否连续

8. 安全与治理​

Trace 是审计材料，也是敏感数据集合。要限制查看权限，按环境隔离，设置保留周期，并对高风险工具参数做摘要或脱敏。

9. 权威资料​

15. 主控验收清单​

  • 是否有统一 root span：agent.run。
  • 是否每次模型调用都有 model.call span。
  • 是否每次工具调用都有 tool.call span。
  • 是否审批和策略检查有独立 span。
  • 是否跨 API、worker、工具服务传播 trace context。
  • 是否失败 span 带 error code 和可读 reason。
  • 是否记录 prompt、model、tool、policy 版本。
  • 是否能从 trace 生成回放证据包。
  • 是否对高危和失败 trace 全量保留。
  • 是否对普通成功 trace 做合理采样。
  • 是否避免保存完整工具参数和隐私输入。
  • 是否有 trace export drop 告警。
  • 是否能按租户和环境控制访问。
  • 是否把 trace 字段完整率接入仪表盘。
  • 是否在 SDK 升级后复查 GenAI 语义字段变化。
  • 是否兼容 OpenTelemetry 语义约定仍处于发展中的字段调整。
  • 是否定义供应商字段到内部字段的映射表。
  • 是否记录 span 采样决策，便于解释缺失数据。
  • 是否对长任务跨 worker 续接 trace。
  • 是否在回放时能复用原 trace 的关键上下文。
  • 是否对审批等待时间使用独立 span，避免误算模型延迟。
  • 是否把 queue wait time 和 execution time 分开。
  • 是否能追踪异步 webhook 回调。
  • 是否为安全审计保留关键 trace 的不可变副本。
  • 是否定期用合成任务验证 trace 完整性。

10. 二次精修：Agent Trace 结构​

Trace 要还原一次 Agent run 的控制流。OpenTelemetry GenAI 语义约定截至 2026-05-09 仍标记为 Development，生产落地时应保留自定义字段的兼容层。

{
  "name": "agent.tool_call",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7",
  "parent_span_id": "b7ad6b7169203331",
  "attributes": {
    "gen_ai.system": "openai",
    "gen_ai.request.model": "gpt-5",
    "agent.id": "refund_agent",
    "agent.version": "1.8.2",
    "tool.name": "search_order",
    "tool.args_hash": "sha256:abc",
    "policy.decision": "allow",
    "cost.usd": 0.04
  },
  "status": {"code": "OK"}
}

11. Span 命名与属性表​

SpanParent必须属性
agent.runAPI requestrun_id、agent_version、session_id
model.callagent.runmodel、tokens、latency、prompt_version
tool.callagent.runtool.name、args_hash、status、duration
policy.checkagent.runpolicy.version、decision、risk_level
state.updateagent.runstate.version、status_from、status_to
approval.waitagent.runapproval_id、approver_role、result

12. Trace 质量指标​

指标目标
Trace Completeness关键 span 覆盖率高于 99%
Span Error Coverage失败 span 必须有 error code
Context Propagation跨服务 trace_id 连续
Sensitive Attribute Leak目标为 0
Cost Attribution Coverage模型和工具成本可归因
Replay Readinesstrace 足以生成回放证据包

13. 运维与安全​

  • trace 采样要基于风险：失败、高成本、安全事件、高危工具全量保留。
  • 跨服务调用必须传播 W3C Trace Context，避免工具链路断裂。
  • trace 属性里保存 hash、引用和枚举，不保存完整敏感 payload。
  • trace 后端访问需要按租户、环境、角色分级。
  • 观测 SDK 故障时不能影响主链路；导出失败要计数告警。

14. 补充权威资料​