[!info] related notes

• 所属 MOC: Agent Runtime MOC, Observability Engineering MOC
• 上游概念: Run, Step
• 工具: Agent Trace Viewer, LangSmith
• 标准: OpenTelemetry
• 易混淆: Agent DecisionTrace

Trace

一句话定义

Trace 通过共享 trace ID 的 span 关联一次分布式操作中已观测的执行片段。在 Agent 中可记录模型调用、工具执行与相关状态事件，但不保证包含全部输入输出或每次状态转换；完整性取决于埋点、采样、导出与保留策略。业务 run 可以跨多个 trace，一条 trace 也不必只包含一个 run。

它解决什么问题

Agent 是非确定性的：同样的输入可能产生不同的执行路径。出了问题时你需要知道：

• Agent 为什么选择了这个工具而不是那个？
• 工具返回了什么结果？
• LLM 的 Prompt 里到底塞了什么内容？
• 哪一步花了最多时间？
• token 消耗在哪里？

这些是 trace 可以协助调查的问题；仅凭调用顺序不能证明模型内部的决策原因。授权与业务决策依据另见 DecisionTrace。

核心原理

Trace 的数据结构

Trace（单个 Run 的串行调用示例，字段按需采集）
├── Span 1: LLM Call
│   ├── input: system prompt + messages + tools
│   ├── output: tool_call / text
│   ├── tokens: {input: 1200, output: 350}
│   ├── latency_ms: 2300
│   └── model: gpt-4
│
├── Span 2: Tool Execution
│   ├── tool_name: search_knowledge
│   ├── arguments: {query: "..."}
│   ├── result: [...]
│   ├── latency_ms: 450
│   └── status: success
│
├── Span 3: LLM Call
│   ├── input: ... + tool_result
│   ├── output: final answer
│   ├── tokens: {input: 1800, output: 500}
│   └── latency_ms: 3100
│
└── Summary
    ├── total_tokens: 3850
    ├── total_latency_ms: 5850
    ├── tool_calls: 1
    └── steps: 2

此处耗时数字假设串行且忽略其他开销；真实端到端耗时应按根操作的起止时间计算，不能无条件相加子 span，尤其是并发或嵌套调用。输入输出可存受控引用，不必复制完整 payload。

Trace 与 OpenTelemetry

分布式追踪可采用 OpenTelemetry 模型；并非所有名为 Trace 的 Agent 记录器都符合它：

• Trace: 由共享 trace ID 的 span 关联起来的执行链路，实际观测可能缺失片段
• Span: 链路中的一个操作单元
• Span Context: 包含 trace ID、span ID、trace flags 与 trace state 等；跨服务由 propagator 序列化/提取，不是任意业务 run ID

Trace (trace_id: abc123，图中 ID 均为缩写，不是合法线上格式)
├── Span: Agent Run (span_id: 001)
│   ├── Span: LLM Call (span_id: 002)
│   ├── Span: Tool Execution (span_id: 003)
│   └── Span: LLM Call (span_id: 004)

Trace vs Log vs Metric

	Trace	Log	Metric
关注点	请求链路	离散事件	聚合数值
粒度	一次请求	一条记录	统计值
用途	调试、性能分析	错误排查	监控告警
例子	一次 Agent Run 的完整过程	”Tool X 调用失败"	"平均延迟 2.3s”

典型工程实现

使用 SDK 管理 span 生命周期

沿用 OpenTelemetry 中配置好的 tracer，包装实际异步操作。以下函数片段要求调用方传入异步工具函数及有 name 属性的工具调用对象：

async def traced_tool_call(tracer, execute_tool, tool_call):
    with tracer.start_as_current_span("tool_call") as span:
        span.set_attribute("app.tool_name", tool_call.name)
        return await execute_tool(tool_call)

上下文管理器在正常返回或异常退出时结束 span，并恢复之前的当前 span；Python SDK 默认会记录向外传播的 Exception 并设置错误状态；asyncio.CancelledError 等 BaseException 子类不应假定自动标为 ERROR，取消结果需按业务合同处理。不要用单个全局 current_span 模拟嵌套/并发上下文，也不要在调用已经完成后新建 span 来冒充原调用耗时。真实工具返回“失败对象”而没有抛异常时，需按业务合同显式记录结果。

Trace 查询

查询属于后端或查看器能力，不是 OTel Tracer API。选择的后端应能按 trace ID 或关联的 run ID 检索、筛选慢 span，并基于明确的时间窗口与分母聚合失败率；具体查询语言以该后端为准。

常见设计模式

1. 自动 Trace

运行时或 instrumentation 可自动记录其支持且已启用的调用；自定义工具和未覆盖边界仍需埋点，不能假设“全部自动记录”。

2. 采样 Trace

按流量、成本与排障目标设置采样；10% 只能是例子，不能保证罕见失败被保留。

3. 错误 Trace

优先保留错误可能需要 tail sampling 或缓冲设计；head sampling 时通常还不知道最终结果，已经丢弃的 span 不能事后自动恢复。

常见坑

1. 缺少必要证据版本：按权限保留输入引用、模型/提示/工具版本等；即便保存完整输入，非确定性和外部状态也可能使结果无法精确重放。
2. Trace 数据太大: 完整记录所有内容，存储成本高
3. 不做采样: 生产环境全量记录，性能影响大
4. Trace 和 Log 分离: 同一个请求的 Trace 和 Log 对不上
5. 不记录 token 消耗: 无法分析成本

和其他概念的关系

• vs Run: Run 是业务执行单元，trace 是观测关联；用明确映射关联，不能混用 identity
• vs Checkpoint: Checkpoint 用于恢复，Trace 用于回溯
• vs OpenTelemetry: OTel 是 Trace 的标准框架
• vs Trace Viewer: Viewer 是 Trace 的可视化工具

总结

Trace 提供已观测执行的诊断证据；它不是完整事件账本、恢复 checkpoint，也不能单独证明模型的决策原因。

参考资料

• OpenTelemetry Tracing
• LangSmith Tracing
• Langfuse Tracing