OpenTelemetry hostmetrics 进程指标进入候选稳定阶段说明了什么

OpenTelemetry 官方博客在 2026 年 10 月介绍了一个重要的可观测性演进：Collector Contrib v0.160.0 为 hostmetrics receiver 的 process scraper 增加了首批 Release Candidate（RC）进程指标。RC 不是“已经稳定”的同义词，而是让社区在稳定 v1 之前试用、暴露兼容问题的阶段。

官方资料入口：https://opentelemetry.io/blog/2026/hostmetrics-process-scraper-rc/

这次变化的核心不只是多了几个指标，而是 OpenTelemetry 找到了一条兼容迁移路径：旧语义和新语义可以并存，通过 feature gate 控制切换，避免用户升级后配置和后端查询同时失效。

这次公告到底改变了什么

hostmetrics 的 process scraper 原来已经提供进程 CPU、线程、文件描述符等指标，但这些指标的名称、单位或属性需要逐步对齐 OpenTelemetry 语义约定。官方资料给出的 v0.160.0 方案，是让 RC 指标先以版本化形式出现，同时保留 legacy 指标的迁移空间。

这里有三个容易混淆的判断：

• RC 不等于稳定 v1：它表示定义已经足够清晰，可以请用户试用并反馈破坏性影响。
• 版本化键不一定是最终指标名：配置元数据里的 @v1 用于区分迁移目标，发往后端的指标名仍按生成规则处理。
• 升级 Collector 不等于自动切换：v0.160.0 中相关 feature gate 仍处于关闭状态，使用新输出需要明确打开。

为什么不能直接修改原来的指标

进程指标看起来只是名称调整，实际会同时影响指标类型、单位和属性。例如同名指标可能从 Gauge 变成 UpDownCounter，也可能保留名称但把属性从 state 改成 cpu.mode。这些变化会影响告警表达式、仪表盘查询、远程写入的时间序列以及下游聚合。

如果直接覆盖旧定义，旧配置还能启动，但查询结果可能已经不再对应原来的含义。更麻烦的是，Collector 的配置元数据由 mdatagen 生成代码；同一份定义里不能简单地放两份名字相同、类型或属性不同的指标。

因此官方选择了“版本化指标 + feature gate”的组合：先让旧指标继续工作，再让新语义以独立目标进入系统，最后在社区确认兼容性后推进稳定化。

mdatagen 怎样承载双轨迁移

这次设计在 metadata.yaml 中使用带版本后缀的键，并增加 migration 描述。下面是按官方结构改写的最小示意，字段名用于解释迁移关系，不能直接当作完整生产配置。

metrics:
  # 旧指标继续保留，避免升级时立刻改变已有查询。
  process.cpu.utilization:
    enabled: false
    stability: development
    gauge:
      value_type: double
    attributes: [state]
    migration:
      # 指向新的版本化指标定义。
      to: process.cpu.utilization@v1
      through_gates:
        # 打开后停止输出旧语义。
        disable_old: scraper.process.DontEmitV0SystemConventions
        # 打开后启用 RC 语义。
        enable_new: scraper.process.EmitV1SystemConventions

  # @v1 只是元数据中的迁移键，便于生成器区分两个定义。
  process.cpu.utilization@v1:
    enabled: false
    stability: beta
    gauge:
      value_type: double
    attributes: [cpu.mode]

这里最值得关注的是 through_gates，它把迁移决策显式化：一个 gate 负责停止旧输出，另一个 gate 负责开启新输出。这样，组件维护者不需要把“旧定义和新定义同时输出时怎么办”的全部逻辑散落到每个 scraper 中，生成代码可以统一处理。

哪些进程指标发生了语义变化

官方示例列出了多组旧指标和 RC 指标的对应关系。不要只看名字是否变化，还要看单位与属性，因为下游查询最容易在这两个地方悄悄失真。

这些变化不能被简单概括为“改名”。例如同名但属性变化的指标，在双轨发布期间可能需要合并属性；同名但类型变化的指标，则可能优先采用 RC 类型并记录提醒。应用团队应把它视为一次指标契约迁移。

采用前应该怎样判断风险

这次 RC 的价值在于可以提前发现真实环境里的兼容问题，但它也不适合被当成无条件的生产开关。可以按下面的顺序做决策：

1. 先盘点依赖：列出使用 process scraper 的 Collector 配置、仪表盘、告警和录入规则，重点找出依赖旧属性名、旧单位或旧指标名的查询。
2. 再做旁路试用：在非生产或低风险环境使用与 v0.160.0 对应的 RC feature gate，观察新旧语义对采集量和后端标签的影响。
3. 核对双轨行为：如果同时打开旧、新路径，确认后端不会因为同名序列产生重复写入、类型冲突或不可聚合的结果。
4. 最后安排迁移：把仪表盘、告警和数据处理规则按新属性逐步改写，并保留关闭 gate 的回退方案。

# 仅示意 feature gate 的位置，具体二进制名称按发行包调整。
# 在试验环境打开 RC 进程语义，不代表生产环境已经切换。
./otelcontribcol \
  --config=collector.yaml \
  --feature-gates=scraper.process.EmitV1SystemConventions

如果现有系统对 process 指标没有告警和长期报表依赖，试用成本通常较低；如果指标已经成为容量预测、SLO 或自动扩缩容输入，就应该先做契约盘点，再决定是否进入 RC。

这次进展对工程团队意味着什么

从项目演进角度看，hostmetrics 的 RC 不是一个孤立的新指标列表，而是 OpenTelemetry 在处理语义变化时给出的工程方法：通过版本键、迁移字段、生成器和 feature gate，把“立刻破坏旧用户”和“永远无法升级”之间的矛盾拆开。

对使用者来说，最实用的结论有三条：

• 把 RC 当作迁移预览窗口，优先用来找出查询、告警和标签依赖。
• 不要只检查 Collector 是否成功启动，必须检查指标单位、属性和后端时间序列含义。
• 在官方宣布稳定前，保留旧 gate 的回退路径，不要把 RC 语义当成永久兼容承诺。

相关问题

RC 进程指标是不是已经可以直接替代旧指标？

不能这样理解。RC 表示进入候选稳定阶段，适合试用和反馈；是否替代旧指标，还要看版本说明、兼容变化和你的下游查询是否完成迁移。

为什么 feature gate 要拆成关闭旧指标和开启新指标两个开关？

因为迁移需要控制顺序。两个开关可以让团队先观察新语义，再决定何时停止旧输出，避免一次升级同时改变采集和消费两端。

只改 Collector 版本，仪表盘会自动适配吗？

不会。仪表盘和告警依赖的是指标名、属性、单位及类型，Collector 升级不会替你修改这些查询契约。

总结：OpenTelemetry hostmetrics 进程指标进入 RC，真正重要的是迁移机制趋于清晰。把它当作一次可观测性契约演练，先确认旧查询依赖，再在低风险环境打开 gate，最后按官方稳定进度完成切换，才是更稳妥的采用方式。