OpenTelemetry OBI 1.0稳定配置发布后迁移关注什么

OpenTelemetry eBPF Instrumentation（OBI）在 2026 年 10 月 30 日发布 1.0.0 后，迁移重点不只是把镜像标签换成新版本。真正需要关注的是稳定承诺落在了哪些配置和部署接口上，以及原有 Config v1、环境变量和 Collector 接收器配置能否保持原来的观测行为。比较稳妥的做法是：保留旧版本，先把配置迁到 Config v2，盘点文件之外的覆写，再用一个代表性实例做灰度对比。

官方地址：https://opentelemetry.io/docs/zero-code/obi/

OBI 1.0 稳定的不是所有遥测字段

OBI 1.0 的变化可以理解为“升级结果更可预期”。官方把 Config v2、生成的配置 schema、文档化的部署接口和支持环境列入兼容承诺，同时为遥测演进提供 schema registry、变更说明和迁移指引。这样做并不等于所有指标和属性从此永远不变：遵循稳定语义约定的遥测应保持契约；仍在演进中的语义可能随约定成熟而调整，已经稳定但实现错误的字段也可能被修正。

因此，监控面板、告警和下游处理器要区分两类风险：配置能否加载是一类，加载后产生的遥测名称、属性、数量和基数是否发生变化是另一类。不要因为 obi config validate 成功，就直接认为升级后的生产数据完全等价。

先把配置入口盘点完整，再运行迁移命令

迁移前应保存当前 Config v1、准确记录二进制版本或容器镜像 digest，并列出环境变量、命令行参数、Helm values、Kubernetes manifest 和 Secret 注入项。官方迁移命令读取的是你提供的文件，不会替你合并这些外部覆写；而且它会解析变量替换表达式，输出文件可能包含秘密值，临时目录应限制权限，不能直接提交到代码仓库。

# 使用私有临时目录保存迁移结果，避免把解析后的秘密写入仓库
umask 077
migration_dir="$(mktemp -d)"

# 将 Config v1 转成 Config v2；报告写到单独文件，便于处理失败字段
obi config migrate ./obi-v1.yaml \
  > "${migration_dir}/obi-v2.yaml" \
  2> "${migration_dir}/migration-report.txt"

# 退出码为 0 才继续，先验证生成文件的结构和支持字段
if [ "$?" -eq 0 ]; then
  obi config validate "${migration_dir}/obi-v2.yaml"
fi

生成的独立 OBI 配置通常会把发现规则放到 extensions.obi.capture.policy 和 capture.rules，协议和运行时采集放到 capture.instrumentation、capture.runtimes，网络与批处理控制放到 capture.network、capture.engine。如果是 Collector receiver，迁移时传入的是 receiver 组件体，不是整份 Collector 配置。

Config v1 能保留，但不应再把它当成演进入口

OBI 1.0 仍支持 Config v1 的向后兼容，这是给现有部署留出的缓冲，不是鼓励继续围绕旧字段添加能力。Config v2 使用 OpenTelemetry 声明式结构：独立 OBI 的通用设置位于根部，OBI 专属配置位于 extensions.obi；file_format: "1.0" 是声明式配置 schema，extensions.obi.version: "2.0" 是 OBI 配置 schema，两者都不是 OBI 发布版本号。

迁移失败时不要只改标题或缩进继续重试。官方文档列出了需要人工决策的典型字段，例如路径排除要改为工作负载规则，健康检查交给部署或 Collector，某些采样、日志关联、调试 exporter 和隐私参数需要重新设计。特别要保留规则顺序：迁移器可能写入内置排除项，并调整 include 选择器顺序来保留 Config v1 的优先级，未经灰度验证不要手工重排。

# Config v2 的最小结构示意；version 表示 OBI 配置 schema，不是发布版本
file_format: "1.0"
extensions:
  obi:
    version: "2.0"
    capture: {}
    enrich: {}

# 服务身份放在资源属性中，便于下游按服务维度聚合
resource:
  attributes:
    - name: service.name
      value: checkout

灰度阶段要比较遥测，而不只是看命令退出码

迁移成功后先选一个有代表性的实例或工作负载。对比 Config v1 与 Config v2 时，至少看工作负载包含和排除结果、trace 与 metric 的路由和属性、采样行为、exporter 连接与认证、遥测量和基数，以及 OBI 日志中的错误或背压。还要专门覆盖多个选择规则重叠的工作负载，因为这类边界最容易被规则顺序掩盖。

发布后最值得先做的三件事

• 把新部署模板的默认入口改为 Config v2，并把环境变量和命令行覆写列成显式清单。
• 为 dashboard、alert 和处理器记录依赖的遥测 schema，升级前先标出仍在演进的字段。
• 保留旧配置、旧镜像和回滚动作，先完成一个实例的 canary，再按工作负载扩大范围。

常见问题

OBI 1.0 是否要求当天完成 Config v1 迁移？

不要求。Config v1 仍有向后兼容，但它已经冻结。新配置和后续能力应以 Config v2 为目标，并在迁移窗口内完成灰度。

validate 成功后还需要灰度吗？

需要。validate 主要检查结构和字段支持情况，不会启动 OBI、连接 exporter、附着 eBPF 程序或检查内核能力，所以仍要比较真实工作负载和遥测。

环境变量会被 migrate 自动转换吗？

不会。迁移命令只处理输入文件；部署层的环境变量、命令行参数和 Secret 注入要单独盘点，并把需要保留的值映射到 Config v2 或 Collector。