Appearance
Agent Trace 如何标准化导出：OpenTelemetry 与 Export Pipeline
前置：如何量化运行质量：Cost、Latency、Task Success 与 Component Metrics
核心问题：内部 Trace 已经稳定后，怎样映射到 OTel GenAI 语义约定，同时避免标准版本变化反向污染 Domain？
Runtime 内部已经能记录 Run、Model Call、Tool Call 和状态事件，但“有 Trace”不等于“能直接把内部对象当 OTel Schema”。如果业务模型直接依赖某一版 GenAI attribute 名称，规范演进会反向污染 Runtime；如果 Exporter 同步阻塞主路径，观测后端故障又会变成用户任务故障。
因此需要两层边界：内部 TraceRecord 保持稳定，OTel mapping 负责标准化；Processor/Exporter 负责异步处理与传输。
OpenTelemetry GenAI Semantic Conventions
截至 2026-08-24，OpenTelemetry 已把 Generative AI semantic conventions 从主 semantic-conventions 仓库迁到独立的 semantic-conventions-genai 仓库；其中 GenAI agent/framework spans、plan、tool execution 等仍标记为 Development。因此这里把它当成“可对齐的外部语义约定”，而不是 Harness 内部稳定 Domain Schema。
映射层可以对齐 invoke_agent、invoke_workflow、plan、execute_tool、model/retrieval/token 等语义；但必须记录采用的 convention/schema version。规范升级时只替换 mapper/contract tests，不能迫使 RunState、ToolExecutionResult 或数据库表跟着改名。
一条 ToolCall 怎样被映射而不污染 Domain
内部 Runtime 可以只记录稳定对象：
text
TraceRecord(
run_id="r-42",
node_id="n-7",
operation="tool.execute",
tool_name="search_docs",
duration_ms=320,
status="SUCCEEDED"
)OTel mapper 再根据当前 convention version 把这些字段映射成 span name / attributes。以后 semantic convention 改字段名，改的是 mapper 和 exporter contract test；RunState、数据库和 ToolExecutor 都不需要跟着迁移。
这层隔离也方便同时输出多个后端：同一份内部 TraceRecord 可以映射为 OTLP span，也可以生成本地 JSON trace 供 Eval/Replay 使用。
Trace Exporter / Processor
Processor/Exporter 应异步、可批处理、失败不阻塞核心任务；长 worker 需要 flush/shutdown 语义。Processor 在 span/event 离开 Runtime 前做采样、redaction、属性归一和 batch；Exporter 负责写 OTLP/后端。导出失败不应阻塞核心 Run 到不可用，但关键 terminal/audit 事件要有更可靠策略。
二者不应阻塞 Agent 主路径或因观测后端故障让业务失败。
Failure Mode：把外部语义约定当内部 Domain Schema
如果数据库、状态机或业务逻辑直接依赖某版 OTel attribute/span 名称，规范升级会迫使 Runtime Domain 跟着变化。更稳妥的做法是保留内部 TraceRecord，在 exporter mapping 层记录 convention/version 并做 contract test。
如何验证
- 用两个 mapping 版本导出同一份内部 TraceRecord，内部对象不应变化。
- 模拟 collector 不可用，Run 仍应按业务规则完成，同时产生 exporter failure metric / alert。
- shutdown 时验证关键 batch 能按策略 flush；低优先级 trace 可以按明确策略丢弃，而不是阻塞主路径。
自测
- Domain 代码如果直接依赖某个 OTLP exporter，会带来什么耦合？Instrumentation 与 export pipeline 应如何分开？
- 同一 trace 需要跨进程传播 context。Queue message 至少要携带什么信息，Worker 才能继续父链路？