OpenTelemetry GenAI 语义约定：把模型、工具和 Agent 链路放进一条 Trace

OpenTelemetry GenAI 语义约定：把模型、工具和 Agent 链路放进一条 Trace

传统接口监控告诉你请求耗时 18 秒，却不解释时间花在检索、模型推理、工具调用还是重试。Agent 出错时，团队更需要看到一次用户任务如何跨越业务接口、模型、向量检索、MCP 工具和工作流。OpenTelemetry 的 GenAI 语义约定正在为这些操作定义共同的 Span、指标和事件名称，让 AI 链路可以进入现有可观测体系。

先承认规范仍在发展

官方 GenAI 文档目前将相关语义约定标为 Development。模型 Span、Agent Span、指标、异常、MCP 与供应商扩展仍可能变化，生产接入应固定语义约定和 SDK 版本，记录 schema URL，并通过适配层控制升级。不要把实验字段散落在所有业务代码里。

一次推理应该记录什么

模型调用 Span 至少需要操作名、供应商、请求模型、响应模型、结束原因、错误类型和耗时。Token 用量适合成为指标或受控属性，用于成本分析；温度、最大输出和服务档位等参数只有在确实影响排障时才记录。

Agent 链路不等于一串模型调用

Agent 还包含创建或调用 Agent、工作流执行、规划、检索、记忆操作和工具执行。父子 Span 应反映真实因果：用户任务调用协调 Agent，协调 Agent 生成计划，随后并行检索并执行工具，最后调用模型汇总。这样火焰图才能暴露循环、串行等待与慢工具。

工具名称可以记录，工具参数和结果却可能包含密钥、订单、个人信息与完整文档。官方约定也提示输入输出字段具有敏感性。默认关闭正文采集，只在受控调试环境按租户、采样规则和字段白名单开启，并执行脱敏、截断、加密与保留期管理。

指标不要带无限基数

模型、供应商、操作类型和错误类别适合做有限维度；user id、session id、Prompt、URL 与完整错误文本不应成为指标标签，否则时序数据库的基数和成本会迅速失控。高基数字段留在 Trace 或日志中，并通过 trace id 关联。

仪表盘关注成功率、分位时延、首块响应、Token、错误与单位成功任务成本；Agent 再增加工具成功率、循环步数和人工接管率。平均值无法揭示长尾。

将 DASP、MCP 和模型调用串起来

一个 DASP sid 可跨请求和设备，不适合直接当 trace id。每次用户意图建立独立 trace，并记录受控会话引用；MCP、模型和异步任务继承上下文，恢复任务用 link 关联此前 Trace。

AnyAIS 可提供统一模型 code、请求标识、用量和错误口径，业务端补充租户、功能、Prompt 版本和任务结果。两侧 trace id 对齐后，运营能从失败用户任务下钻到具体模型或工具，成本数据也能回到真实功能，而不是停留在供应商账单。

从一个高价值工作流开始

先选一条包含模型与工具的流程，画出 Span 树，定义必需属性和禁采字段，再验证成功、超时、限流、取消与重试。可用独立模型辅助检查异常分支，采集正确性仍由契约测试、脱敏检查和故障演练确认。

参考资料

• [OpenTelemetry GenAI 语义约定总览](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/README.md)
• [GenAI 模型操作 Span](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-spans.md)
• [GenAI Agent 与工具 Span](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md)

如果你已通过 AnyAIS 统一调用模型，可以从贯通业务 trace id、平台请求标识与任务结果开始，逐步建立可迁移的 GenAI 可观测口径。