Appearance
如何看见 Agent 在做什么：Logs、Metrics 与 Trace
前置：完整可运行的 API / Queue / Worker / Tool 链路；Execution Identity
核心问题：一次 Agent 失败时，Logs、Metrics、Trace 各自回答什么问题，怎样用同一个 Run identity 把它们串起来？
429 激增先由 metric 告警，再从 trace 找到具体 model/tool span，最后查看该 span 关联日志定位响应细节。一次 Run 下包含三个 model spans 和两个并行 tool spans，最终 eval result 通过 run_id 回挂到同一 trace。
Mental Model
text
Runtime events → logs/metrics/traces → normalized telemetry → test/eval → regression/ablation decisionObservability 回答“发生了什么”，Testing 回答“程序是否满足确定性契约”，Evaluation 回答“非确定性 Agent 做得够不够好”；三者数据可关联但不可混用。
Logs / Metrics / Traces
三者解决不同的问题：
text
Logs → 某个离散事件具体发生了什么
Metrics → 一段时间整体是否变慢、变贵、变差
Trace → 这一次 Run 为什么走成这样例如用户说“这个 Run 卡了 40 秒”：Metrics 可以先发现 tool_latency_p95 上升；Trace 再定位到某个 search_repo span；Logs 最后查看该 Tool 的 timeout/error 细节。
所以不是“日志记全一点就够了”。Agent 特别需要 Trace，因为一次 Run 会跨 Model、Retriever、Tool、Queue、Worker，只有因果链才能解释时间和决策花在哪里。
Agent Trace Model
Agent Trace Model 定义一次 Agent Run 如何被表示为可关联的 span/event 树：Run/Turn/Model/Tool/Retrieval/Handoff 等 operation 各有明确父子关系、时间和状态。它是 Agent 领域的 trace schema。
🔍 源码对照：Turn Observation 同时产出生命周期事件和性能事件
完整源码与通用分析见 09-01 Run Lifecycle / State Machine。这里不重复代码；这里关注 trace：Tool lifecycle event 是 execution trace 的事实源；性能事件与状态事件应通过稳定 operation identity 关联。
源码说明
turn-observation.ts 明确产生 turn/tool lifecycle event，并携带 trace/span 信息；仓库又单独有 usage、trace host、action audit、telemetry。这个拆分非常适合说明 Logs、Metrics、Trace、Audit 虽然都“记录东西”，但服务不同查询：调试顺序、容量/成本、因果关联、合规事实不能混成一个大 JSON log。
工程边界
案例的 event name/span schema 不是 OpenTelemetry GenAI 标准；Shadow Harness 先定义 domain events，再由 exporter 映射到当前 OTel semantic conventions。
Shadow Harness 对照
- Run/Turn/ModelCall/ToolCall/Attempt 使用稳定 correlation ids。
- Trace instrumentation failure 的降级策略必须明确，不能无意改变主 Runtime 状态。
验证
给一个 3-Turn Run 查询“哪次 Tool timeout 导致哪次模型 retry，并增加了多少 latency/token”，应只靠 trace/metrics 重建，不查应用 debug 文本。
Run / Turn / Model / Tool / Handoff Spans
Run / Turn / Model / Tool / Handoff Spans 是 Trace Model 中的具体 operation spans：分别覆盖端到端 Run、单轮推理、模型调用、工具执行和控制权转移；每类 span 应记录与自身职责相关的 attributes/status。
Span 粒度要对应可独立耗时、失败和归因的动作；parent-child/links 应表达真实因果。Handoff 改变 Agent owner，应显式记录 from/to。
最小实现 / 数据结构
python
with tracer.start_as_current_span("tool.execute") as span:
span.set_attribute("tool.name", tool.name)
result = await tool.execute(args)
metrics.tool_latency.record(timer.elapsed)
return result在 Shadow Harness 中怎么落地
统一 trace id/run_id/node id/tool_call_id；支持 OTEL 兼容 export；Fake/Scripted Model 测 Runtime，真实 provider 留给 integration/eval。
Failure Modes
把日志堆积当成完整 Trace
症状： 只有离散 log，没有 parent/child span、run/tool correlation 与 duration/status。
为什么危险： 跨模型/Tool/Retrieval 因果关系无法还原。
处理： 建立 Run/Turn/Model/Tool/Retrieval span 层级，日志作为 span event。
如何验证
| Case | 断言 |
|---|---|
| 把日志堆积当成完整 Trace | 多 Tool 并发 Run 的每个操作都能沿 trace tree 回到同一 run_id。 |
关联源码
自测
- 一次 Run 失败时，Log、Metric、Trace 分别最适合回答“发生了什么”“总体是否异常”“跨组件链路在哪断了”的哪一个问题？
- 如果 model/tool/worker 日志没有共享 run_id，为什么即使日志很多也很难复盘一次完整执行？