OpenTelemetry GenAI 语义约定变化后如何整理追踪字段

如果你最近升级了 OpenTelemetry 语义约定，发现旧的 gen_ai.* 字段出现 deprecated，不要把所有字段机械地改名。更稳妥的做法是先按“调用边界、统计边界、内容事件”重新分层：模型和操作名放在 span/metric 的公共字段里，prompt、回复和工具参数按需作为结构化事件或受控内容记录，提供商差异再放到 provider-specific 扩展中。

官方资料入口：https://opentelemetry.io/；GenAI 语义约定仓库：https://github.com/open-telemetry/semantic-conventions-genai

先分清“字段变化”和“语义归属变化”

这次调整最容易误判的地方，是把“字段还叫 gen_ai.*”理解成“原来的定义仍然有效”。OpenTelemetry 的核心语义约定发布说明已经把原先位于 model/gen-ai/、model/openai/ 和 model/mcp/ 的 GenAI 属性、指标、事件和 span 标为 deprecated，并迁移到独立仓库。独立仓库当前仍标记为 Development，因此它既是新的事实来源，也是需要隔离变更的边界。

迁移时先在 instrumentation 的适配层写清三件事：使用哪一版语义约定、发送数据的 schema_url 是什么、旧字段只为兼容哪些消费者保留。不要在业务代码里散落“新字段名 + 旧字段名”的双写判断，否则下一次约定变化时很难收口。

把追踪字段按查询目标重新排一遍

一个 LLM 调用至少要区分“谁提供、做什么、请求了什么、实际消耗什么”。下面这张表可以直接作为字段整理清单：

旧的 gen_ai.system 不应继续承担提供商识别职责；当前资料把它指向 gen_ai.provider.name。同理，gen_ai.usage.prompt_tokens 和 gen_ai.usage.completion_tokens 应分别迁移到 input/output tokens。迁移前后不要只看字段是否有值，还要检查查询面板是否仍按同一维度聚合。

内容字段要从“属性堆积”改成“受控事件”

模型消息、系统指令、工具定义、工具参数和工具结果的体积都可能快速增长，而且可能包含用户输入、个人信息或内部提示词。当前约定要求消息遵循对应 JSON schema；记录在 event 上时应使用结构化形式，记录在 span 上时才考虑后端不支持结构化数据的兼容表示。

工程上可以采用三层开关：

1. 默认关闭全文内容。生产环境先采集模型、操作、token、结束原因和错误类型，让成本与链路问题可见。
2. 按采样或租户开启。排障时只对测试租户、短时间窗口或低比例请求记录消息，并先过滤密钥、身份证号、订单正文等字段。
3. 区分内容事件与调用 span。一个调用中可能出现多次消息或工具结果，事件更适合表达这些独立发生的内容；span 保留调用整体的时间边界。

不要把 prompt、completion 或 tool arguments 放进 metric label，也不要把大段 JSON 复制到每个 span 和 log。这样既会放大存储，也容易形成高基数查询和敏感信息扩散。

用三条样例请求做迁移后的复查

第一条是普通 chat：确认 span 能看到操作名、请求模型、响应模型、结束原因和 input/output token。第二条是带工具调用的 agent：确认工具调用有独立的发生记录，参数与结果能通过调用 ID 对上，但全文内容仍受采集开关控制。第三条是失败请求：确认 span 或对应指标带有低基数的 error.type，同时不把完整异常上下文塞进聚合标签。

复查时再对照 provider-specific 约定：如果请求经过 Azure、Bedrock 或其他兼容接口，不能只根据客户端库名称写 provider。gen_ai.provider.name 应反映 instrumentation 已知的实际提供商，并与对应扩展字段保持一致。最后把这三条样例导出到测试后端，分别验证 trace 关联、token 聚合、错误筛选和内容脱敏。

常见问题

旧字段还能继续发送吗？

可以作为短期兼容策略保留，但新埋点不应继续以旧定义为主。应明确兼容期限，并让新消费者读取独立 GenAI 语义约定。

为什么不把完整 prompt 都放进 span？

因为它可能很大且含敏感信息。优先使用 opt-in、采样、截断和脱敏；只在确有排障价值时记录内容。

schema_url 一定要记录吗？

迁移期间建议记录。它能让下游知道字段来自哪套语义约定，避免同名字段在不同版本间被误解。

模型名能代替 provider.name 吗？

不能。多个服务可能通过同一种 API 代理不同模型，模型名、请求模型和实际提供商是三个不同判断。

整理完成后的标准不是“字段数量更多”，而是公共调用字段可检索、内容数据可控、provider 扩展有边界、schema 版本能追踪。把这些判断集中在 instrumentation adapter 和回归样例里，后续约定继续变化时，业务代码就不必跟着反复改动。