OpenTelemetry 指标平台迁移中的采集边界

OpenTelemetry 指标平台迁移最稳妥的边界，是把“采集契约”与“存储查询平台”分开：应用继续输出稳定的 OTLP 指标，Collector 保持接收、资源补全和必要处理，只在出口阶段并行发送到旧平台与新平台。先迁移数据入口，再迁移看板和告警，最后才停旧出口。

不要在一次迁移中同时改埋点名称、属性、聚合方式、采集拓扑和指标后端。变化面越多，越难判断差异来自采集语义还是平台转换。

官方地址：https://opentelemetry.io/

OpenTelemetry Collector 的定位是厂商中立地接收、处理和导出遥测数据。对指标平台迁移来说，这个中间层的价值不是“自动兼容所有差异”，而是提供一个清楚、可观察、可回退的边界。

用户任务：更换查询后端，不重写全部采集

迁移真正影响的用户不只有平台工程师。应用开发者关心埋点是否要改，值班人员关心告警是否连续，业务负责人关心看板口径是否变化，成本团队则关心时间序列基数与保留策略。

因此，第一步不是写新 exporter，而是把任务拆成两个区域：

• 采集区域：应用 SDK、自动插桩、Agent、Prometheus 抓取、资源属性和 Collector receiver。
• 消费区域：后端 exporter、查询语言、看板、告警、保留周期和权限模型。

能冻结的采集区域越多，平台差异就越容易在 Collector 出口和查询资产中被定位。如果迁移目标要求不同指标名称或标签，可以把转换集中在一条明确的迁移管线里，而不是分散进每个应用。

交互拆解：冻结指标流的身份与语义

OTel Metrics Data Model 中，一条指标流不只由名称决定。Resource 属性、Instrumentation Scope、指标名、数据点类型、单位，以及聚合时序和单调性等内在属性都会影响解释。迁移前应把这些字段整理成一份“指标契约清单”。

这一步相当于先定义“用户看到什么”，再决定组件如何实现。不要只比较两边是否都有同名曲线；同名但单位、时序或属性集合不同，仍然是不同指标语义。

组件实现：在 Collector 出口建立双写窗口

Collector 的指标管线由 receiver、processor 和 exporter 组成，并通过 service.pipelines 启用。迁移窗口可以复用同一条接收与处理链路，同时配置旧、新两个 exporter。这样两边看到的是同一批经过相同处理规则的数据。

receivers:
  otlp:
    protocols:
      grpc:
        # 应用继续发送到稳定的 OTLP 接收地址。
        endpoint: 0.0.0.0:4317

processors:
  memory_limiter:
    # 先保护 Collector，避免后端故障拖垮采集进程。
    check_interval: 1s
    limit_mib: 512
  batch:
    # 两个出口复用同一批处理边界。
    send_batch_size: 1024

exporters:
  otlphttp/old:
    # 地址通过环境变量注入，不在配置中保存凭据。
    endpoint: ${env:OLD_METRICS_ENDPOINT}
  otlphttp/new:
    # 新平台先并行接收，暂不替换旧平台。
    endpoint: ${env:NEW_METRICS_ENDPOINT}

service:
  pipelines:
    metrics/migration:
      # 只有写入 pipeline 的组件才会真正启用。
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlphttp/old, otlphttp/new]

这只是结构示例。实际发行版是否包含所需 exporter、认证扩展和转换组件，应以该发行版的 component 列表和后端官方说明为准。凭据应由环境变量或专用密钥机制注入，不应写进文章、镜像或仓库。

可发现性：让看板和告警知道字段从哪里来

采集双写后，下一步是把查询资产逐项迁移。建议为每个核心看板维护旧查询、新查询、指标契约项、预期聚合窗口和负责人。这样出现差异时，可以追到具体字段，而不是只说“新平台曲线不一样”。

转换规则也要可发现。若 Collector 使用 processor 删除高基数属性、重命名指标或补充 Resource 属性，应把规则放在独立配置段，并记录它服务于哪个后端。能在采集侧保持通用的字段，不应为了某个平台的查询习惯提前改名。

对值班人员而言，迁移界面应提供三类状态：哪些告警仍以旧平台为准、哪些已进入双跑、哪些已经切到新平台。静默切换会让“没有报警”同时可能表示系统健康、规则未迁移或采集失败。

性能检查：用 Collector 内部遥测看数据有没有走完

Collector 自身会暴露内部指标。迁移期间，至少观察 receiver 接收/拒绝的 metric points、processor 的输入输出、exporter 发送失败、队列大小与容量。它们不能证明两边查询语义完全一致，但可以回答数据是否进入 Collector、是否被处理、是否成功送出。

• 入口：accepted 与 refused metric points 用来判断接收压力和拒绝情况。
• 处理：processor 输入输出差异要能对应过滤或聚合规则。
• 出口：发送失败不一定立即等于数据丢失，因为还可能有重试，但持续失败必须处理。
• 队列：同时观察 queue size 与 capacity，避免只看某一个瞬时值。
• 用户结果：核心看板、告警和周期报表仍需业务口径对照。

不要为所有团队设一个通用的“允许误差百分比”。Counter、Gauge、Histogram、不同抓取间隔和查询聚合本就会产生不同对照方式，验收阈值应来自具体指标用途。

边界状态：时序、单写者与回退

指标迁移最危险的边界通常不是 exporter 地址，而是时序和身份。Delta 与 Cumulative 表达不同的时间范围；如果后端或 exporter 发生转换，需要明确状态放在哪里、重启后如何处理。多层 Collector 还要避免同一指标流出现多个写者，确保资源身份全局唯一，否则可能产生跳变、缺口或乱序。

回退也要在切流前设计。旧 exporter 应保留到新平台完成数据连续性、看板和告警验收；停止旧出口后仍应保留配置和最后验收记录。若新平台故障，恢复旧出口不应要求应用重新部署。

1. 冻结指标契约和 Collector 接收入口。
2. 新增新平台 exporter，进入双写。
3. 核对 Collector 内部遥测，排除接收与发送故障。
4. 迁移核心看板和告警，逐项记录口径差异。
5. 缩短旧平台依赖范围，观察完整业务周期。
6. 停旧出口，但保留可恢复配置与迁移记录。

常见问题

用了 OTLP，就能保证两个指标平台完全一致吗？

不能。OTLP 提供清晰的数据模型和传输边界，但后端仍可能在命名、单位、Histogram、时序、资源映射和查询函数上存在差异。

迁移时应该先改应用 SDK 还是先改 Collector？

如果现有 SDK 已能稳定输出所需指标，通常先在 Collector 出口增加新平台更容易控制变量。只有现有采集契约本身有缺陷时，才把 SDK 改造作为单独阶段。

双写多久才能停旧平台？

没有统一天数。至少应覆盖关键告警、日常峰谷、周期报表和故障演练所需的完整观察窗口，并确认回退路径可用。

Collector 的发送失败是否等于数据已经丢失？

不一定，发送队列和重试机制可能仍在工作。需要结合发送失败、入队失败、队列容量、持续时间和后端状态一起判断。