Agent Trace

Trace 首先回答因果问题

一次客服退款 Run 可能包含意图识别、订单检索、政策判断、人工审批、退款 Tool 和通知。HTTP 200 只能证明接口响应，模型说“退款成功”也不能证明资金状态已经改变。Trace 的根节点应保存目标、租户、会话、任务类型、工作流版本和最终业务状态；每个关键动作保存输入引用、决策原因、责任主体、回执和终态。

诊断时先问四件事：用户目标是什么；系统采取了哪些决策和行动；状态由谁在何时改变；失败发生在哪里、是否恢复、业务后置条件是什么。答案必须来自可关联的事件与权威系统回执，而不是把自然语言解释当作事实。

建立 Agent 语义的 Trace 模型

根 Trace 表示一个可独立审计的 Run 或 Workflow，不宜按每一轮聊天任意切断。同步父子关系用 Span 层级；异步、重放和跨 Agent 委派用 Link 保留因果；状态变化与流式里程碑用 Event，避免把瞬时事实伪装成有持续时间的操作。

Run/Workflow Trace

根节点至少关联 tenant_id、session_id、run_id、任务类型、工作流与配置版本，并在结束时写入 business.outcome。用户标识应使用受控的匿名或内部引用，不能直接成为跨租户可搜索属性。

Model、Tool、Guardrail、Handoff、Retrieval、Approval 与自定义业务 Span

Span 表示有开始、结束和责任主体的关键操作。Model Span 记录模型与 Usage；Tool Span 记录契约版本、幂等键和回执；Guardrail、Approval 记录策略结果和原因码；Retrieval 记录索引与过滤版本；业务 Span 记录“退款提交”这类最终可对账动作。不要为同一次 HTTP 或数据库调用再包一个同义 Span，否则延迟与错误会被重复归因。

流式里程碑、状态迁移、重试和取消

Event 适合 first_token、approval_requested、retry_scheduled、run_cancelled 等时间点。每个状态迁移应包含旧状态、新状态、原因码和触发者；重试还要关联 attempt 与前次错误，避免把三次失败展示成三个互不相关的动作。

异步队列、父子 Agent 和跨 Trace 因果链接

队列消费者可能在另一条 Trace 中执行，重放任务也可能没有自然父子关系。此时使用 Span Link 关联消息生产、原始 Run 和重放 Run，并在业务属性中保留消息 ID 与幂等键。强行继承父 Span 会制造错误时序，也会让长生命周期 Trace 永不结束。

用 OpenTelemetry 语义约定连接 Agent 与通用观测体系

OpenTelemetry GenAI 语义注册表已经定义 invoke_agent、invoke_workflow、execute_tool、retrieval 等操作名，但多项仍处于 Development。工程上应采用“标准字段负责互操作，业务字段负责结果解释”的双层模型，并记录语义约定和 Instrumentation 版本。

操作映射

模型生成、Agent/Workflow 调用、Tool 执行与检索使用相应 GenAI 操作；底层 HTTP、RPC、Messaging、Database 保留各自成熟语义。上层 Span 说明业务职责，下层 Span 说明传输与依赖，二者通过父子或 Link 连接，而不是复制相同错误与耗时。

Span、Event 与 Link 各自表达合适关系

标准属性与业务属性分层

Provider、模型、Operation、Usage、Tool 身份优先使用标准属性；任务结果、风险等级、政策原因、退款状态等进入受治理的内部命名空间。标准字段存在不代表应该默认采集内容，官方注册表对 Tool 参数与结果明确给出敏感信息警告。

语义约定仍会演进

升级先在影子管道双写，比较字段缺失率、基数、存储量、看板查询和告警结果。迁移记录应给出 Convention、SDK 与 Collector 版本、兼容窗口和旧字段下线条件。若后端不支持新结构，宁可保留稳定内部字段，也不要静默改变指标口径。

属性要支持检索但控制基数

可索引属性应能回答“哪个版本、租户、场景、风险等级或失败类别退化”，典型字段包括模型与 Provider、Prompt/Tool/Workflow 版本、Token、费用、TTFT、延迟、attempt、终态与原因码。动态长文本、完整用户输入和模型输出通常不应进入标签或高基数属性。

内容类数据可以保存为受控 Artifact，并在 Span 中只写引用、摘要哈希、大小和敏感级别。这样既能按低基数字段聚合，也能在有权限时查看证据。基数预算要按“字段 × 每日唯一值 × 保留期”估算，并对未知属性增长设置告警。

可观测性不能成为最大数据泄露面

Prompt、Tool 参数、文件、检索片段和模型输出必须先分类，再决定不采集、脱敏、摘要、哈希或保存 Artifact 引用。遥测管道与主业务一样需要租户隔离、最小权限、访问审计、加密和保留期；开发者为了调试临时打开全文采集，也必须有到期时间和审计记录。

Zero Data Retention 或数据驻留约束会改变 Exporter、后端和排障流程。应在数据进入 Collector 前完成必要脱敏，不能假设下游供应商会替系统承担合规责任。公开字段清单、数据流向和删除机制，是 Trace 上线门禁的一部分。

采样要保留关键失败和长尾

错误、高风险、未知结果、超预算和人工接管 Trace 应优先完整保留；正常流量按租户、任务、版本与风险分层随机采样。OpenTelemetry 采样文档说明，Tail Sampling 可以基于整条 Trace 的错误、延迟和属性决策，但处理器必须看到完整或大部分 Span，并承担状态与容量成本。

采样器自身也要可观测：晚到 Span、决策超时、内存溢出和 trace-ID 路由变化都会让“保留所有错误”失真。用于运营趋势的概率样本应保存采样概率以便估计总体；用于评测的数据则追求覆盖与区分度，不能把两种样本混为同一无偏总体。

从症状沿调用链定位失败层

先从业务结果和失败类别进入代表性 Trace，再沿最后一个可信状态反向检查。模型层看输出与 Tool 决策；Context/检索层看权限过滤、证据与版本；Tool 层看契约、回执与副作用；策略/审批层看原因码与绑定参数；状态层看提交、消费和重复执行。

Trace 数据需要可运营

看板按 Workflow、版本、任务、租户和风险切片，至少展示成功终态、未知结果、异常步骤数、循环、人工接管、成本与长尾延迟。告警命中后应能跳到代表性 Trace；线上失败经去敏、授权和可重放审查后，才成为 Golden Dataset 候选。

Trace Schema 要有 Owner、版本、兼容测试和成本预算。一次故障演练应证明值班者能从告警在限定时间内定位失败层、确认影响、执行恢复并保全证据；“数据已经写入后端”不等于可运营。