OpenTelemetry LLM 可观察性：在绿色之前固定模式

仅当遥测具有声明的含义时，OpenTelemetry LLM 可观察性才有用。在将 GenAI 跟踪视为操作证据之前，固定语义约定修订版，验证每个操作所需的字段，拒绝未经批准的内容捕获，证明预期操作存在，然后分别评估新鲜度、工作状态和外部结果。 该命令将于 2026 年 7 月生效。OpenTelemetry 网站现在将 GenAI 约定指向 专用存储库。在本文检查的源版本中， 434c91dcc34ed038e3048c07720ddfed2c6bddfc ，存储库的 README 仍将其架构 URL 列为 TODO，并且生成的客户端跨度文档被标记为 开发 。 这并不是避免 OpenTelemetry 的理由。这是明确兼容性的一个原因。包含 GenAI 跨度的仪表板仍然可以组合旧的生产者、当前的收集器和为第三个属性形状编写的查询。安全的默认设置是收集器配置旁边的一个小的、版本化的接受配置文件。 固定您实际操作的合同 OpenTelemetry 的 GenAI 存储库涵盖了 LLM 客户端、代理、工具执行、评估、内存、检索和 MCP。它的文档部分是从 YAML 模型生成的，这很有价值，因为源代码是可检查和可测试的。这也意味着“我们使用 OTel”过于模糊，无法成为兼容性声明。 每次仪器部署时记录四个身份： 身份 例子 为什么这很重要 约定来源 存储库加上提交 SHA 定义您查看的属性和操作合同 仪器仪表包 包名和版本 识别发出跨度的内容 收集器管道 配置摘要和部署 ID 识别转换、过滤器和导出器 查询合约 仪表板或警报版本 确定判决需要哪些字段 不要从碰巧到达的任何字段中推断约定修订。这将无声的漂移变成了明显的兼容性。如果生产商无法声明其修订，则将该批次分类为 schema drift 直到您测试并注册该生产者形状。 当框架本机和外部工具共存时，这一点尤其重要。开放遥测 代理可观察性指导 描述了内置仪器的维护权衡，并警告外部封装可能与其发生冲突。否则，同一模型调用可能会被观察两次，或者在部分升级后，一条路由可以保留在旧的约定上。 实际规则很简单：每个操作路径有一个预期的遥测生成器，每个推出队列有一个声明的约定修订，以及在队列升级之前必须通过的金丝雀跟踪。 在完整架构之前验证小型操作配置文件 可以从存储库模型生成完整的语义约定验证器。一个可操作的门应该从较小的开始。仅强制执行影响您当前决策的字段，然后在使用更多操作时扩展配置文件。 在固定修订版中， 推理跨度表 标记： gen ai.operation.name 根据需要； gen ai.provider.name 根据需要； error.type 当操作以错误结束时有条件地要求； gen ai.request.model 有条件地要求（如有）； 输入消息、输出消息、系统指令和工具定义作为选择加入。 这些要求级别不应被简化为“现场存在或缺席”。误差范围无 error.type 失去了公约所期望的一类证据。丢失的请求模型在不可用时可能是合法的。除非有明确的政策允许收集，否则提示和响应内容应保留。 伴随审计实现了这个狭窄的配置文件： 内容检查仅查看属性 键 。它不读取或存储提示文本、响应文本、系统指令或工具参数。这足以捕获意外的选择加入捕获，而无需将验证器变成另一个敏感数据接收器。 这里有一个故意的限制：这个配置文件不是整个 OpenTelemetry 规范。它测试一份用于运营判决的可审查合同。当上游源发生更改时，更新固定版本，比较生成的定义，调整固定装置，并在升级生产者之前重新运行它。 在解释干净的跟踪之前审核覆盖率 一致的跨度仍然可能是不完整的证据。如果应用程序期望 invoke agent , chat ， 和 execute tool ，但跟踪仅包含前两个，正确的结论是 coverage gap ，不健康。 从工作流拓扑而不是从观察到的跨度构建预期的操作： 这避免了遥测定义其自身完整性的循环测试。预期集可以来自发布清单、注册的工具路由或工作流定义。它应该足够小以方便维护，并且足够具体以暴露缺失的检测路径。 自动重试需要小心。当前的客户端跨度散文表示，一个逻辑跨度应涵盖操作持续时间，包括自动重试。您的应用程序还可能保留尝试级传输跨度。不要将这两层视为重复的代理工作。决定覆盖率是否在逻辑操作、尝试或两者中表达，然后使关系明确。 同样，提供者名称不一定是最终模型所有者。该惯例指出，仪器可能知道代理或托管平台，而不是透明的上游提供商。对待 gen ai.provider.name 作为其记录范围内的格式鉴别器和路由事实，而不是作为计费或模型来源预言机。 将架构、运行状况和结果作为单独的判断 一旦模式和覆盖范围通过，跟踪就有资格为健康决策提供信息。这不是其本身的决定。 使用显式优先级： 1. 架构身份 — 生产者是否与固定版本匹配？ 2. 架构有效性 — 必填字段和条件字段是否有效？ 3. 内容政策 — 此路由是否允许选择加入字段？ 4. 覆盖率 — 是否代表了所有预期的操作？ 5. 新鲜度 — 证据对于工作流程来说是否足够新？ 6. 工作状态 — 代理正在工作、等待、卡住、不确定还是已完成？ 7. 结果 — 所承诺的结果是否存在于目的地？ 本文的十箱固定装置故意使这些层变得不方便。它包括： 未固定的制作人和传统制作人； 缺少推理范围 gen ai.provider.name ; 缺少错误跨度 error.type ; 未经许可选择加入内容密钥； 工作流程缺少预期的工具跨度； 没有结果收据的完整跟踪； 经过验证但陈旧的痕迹； 合法的人类批准等待； 一个新的、已涵盖的、经过结果验证的案例。 使用以下命令运行工件： 执行结果正好分类了十种情况： 这 complete no receipt 案例是关键边界。它的生产者版本匹配。它的范围包含配置文件所需的字段。存在预期的代理和模型操作。遥测数据是新鲜的。它仍然返回 unverified 因为没有目的地收据证明票证、文件、部署或其他承诺的结果存在。 这 waiting for approval case 保留不同的边界。最近，一致性跨度停止于指定的人类批准，并有所有者和截止日期。那不是一个摊子。如同代理失败一样对操作员进行寻呼会破坏有用的状态信息。 将审核转变为发布和事件控制 分三个时刻运行此测试。 在工具升级之前 ，捕获当前版本、软件包版本、收集器摘要和预期操作。根据建议的堆栈重播固定夹具。晋升前必须对改判作出解释。 在推出期间 ，通过每个注册的模型、代理和工具路径发出无内容的金丝雀。检查每个金丝雀是否到达一次，携带预期的生产者身份，通过操作配置文件，并在新鲜度窗口内保持可搜索。 在事件期间 ，保留四个层，而不是将它们折叠成“可观察性被破坏”。模式漂移需要生产者和查询协调。覆盖范围差距需要仪器维修。过时的遥测数据需要收集者或出口商进行诊断。 waiting 呼叫指定的所有者。 unverified 要求进行目的地检查，而不是另一个模型重试。 不要因为遥测字段发生更改而自动修复代理。惯例漂移可以使证据变得不确定，但不会使基础工作变得不健康。冻结主动恢复，识别失败的证据层，并使用恢复信心的最小可逆测试。 架构配置文件还需要一个所有者。永远固定提交并不安全；最终会陷入停滞。分配审查节奏，观察 GenAI 存储库，并在移动引脚时需要夹具差异。如果 OpenTelemetry 稍后发布稳定的 GenAI 架构 URL，请在生产者和查询支持时采用它，但保持覆盖率、新鲜度、等待和结果检查独立。 Sidewisp 目前处于私密预览阶段。 它的公众体验是抢先体验网站和互动演示；当前网站存储库中未提供生产代理运行状况收集、主机适配器和恢复。产品方向是围绕现有运行时的健康层，而不是 OpenTelemetry 收集器、跟踪后端或自主修复程序。 如果修订固定的证据和单独的结果验证与您需要捕获的失败相匹配，您可以 加入 Sidewisp 私人预览 并描述您操作的代理运行时和遥测路径。