[!info] related notes

• 所属 MOC: Observability Engineering MOC
• 相关: Trace, LangSmith

Agent Trace Viewer

一句话定义

Agent Trace Viewer 是展示已采集执行记录的一类工具，不是某个唯一产品。它帮助关联模型调用、工具和状态事件；采样、导出失败或未埋点会留下空白，不能假定画面就是完整执行历史。业务授权依据还需关联 DecisionTrace。

核心原理

Trace 可视化

下面是四个串行 span 的示意节选，不是实际测量：忽略其他开销时，耗时合计 7.05 秒，已列模型 token 合计 3130。真实 run 若有并行或嵌套 span，父级墙钟时间不能简单累加子 span。

Agent Run excerpt (run_001) - 7.05s - 3130 tokens
├── Step 1: LLM Call (2.3s - 1200 in / 50 out)
│   Input: system_prompt + user_message
│   Output: tool_call(search_knowledge)
│
├── Step 2: Tool Execution (0.45s)
│   Tool: search_knowledge
│   Args: {"query": "膝关节康复"}
│   Result: 3 chunks found
│
├── Step 3: LLM Call (3.1s - 1800 in / 80 out)
│   Input: + tool_result
│   Output: tool_call(create_chart)
│
└── Step 4: Tool Execution (1.2s)
    Tool: create_chart
    Result: chart created

平台工具

平台	特点
LangSmith	LangChain 生态，功能全面
Langfuse	开源，可自部署
Helicone	专注 LLM 监控

常见坑

1. 缺少执行证据: 难以定位和重放；Trace 还需配合输入、配置和依赖快照，并非仅有 Trace 就能复现
2. Trace 数据太大: 完整记录占用大量存储
3. 记录策略不匹配: 全量 payload 可能增加开销和敏感数据暴露；采样又可能漏掉异常，关键业务审计需另有完整性保证

参考资料

• Trace
• LangSmith
• Langfuse