Prometheus 原生直方图演进后怎样规划指标迁移

Prometheus 原生直方图稳定化之后，指标迁移应拆成三件事：显式启用原生抓取，在过渡期保住经典序列，再单独切换查询和远端消费链路。不要把升级服务器或保留一个旧特性开关，当作整条监控链路已经迁移完成。

官方地址：https://prometheus.io/。官方原生直方图规范说明，自 3.8.0 起该能力进入稳定状态，3.9 起旧的 --enable-feature=native-histograms 开关成为无实际作用的兼容项，抓取需显式设置。这里讨论这一演进对现有监控的影响，不把既有变化包装成刚发生的新公告。

稳定化改变的是启用方式，不是整条链路自动兼容

考虑一个迁移场景：订单服务的延迟仪表盘和告警都依赖经典直方图，应用团队准备启用原生直方图，而长期存储由另一个团队维护。最容易出现的误判是“Prometheus 已经支持，所以只要改采集端”。实际上，应用暴露、抓取配置、本地查询和远端接收是不同的兼容边界。

经典直方图把桶计数等信息拆成多条浮点序列，原生直方图则能在直方图样本中携带分布。原生形式提供了改变桶表示与查询方式的空间，但不是普通浮点序列的无感替代，也不能据此承诺每个部署都按固定比例节省存储。

对运行 Prometheus 3.x 的团队，实质动作是将启用意图落到 scrape_native_histograms 配置，而不是继续依赖历史启动参数。3.8 的旧开关只是在过渡期改变该配置的默认值；进入 3.9 后不能再指望它开启抓取。更旧版本则应按对应版本文档规划升级，不照抄新版本配置。

先保住旧告警依赖的经典序列

对同时暴露原生和经典数据的目标，仅开启原生抓取，可能让原来依赖 _bucket、_count、_sum 的查询失去后续数据。过渡阶段应明确是否继续接收经典部分。下面是一个独立试点任务的配置示例，目标地址仅为教学占位，不能未经调整并入生产配置：

scrape_configs:
  - job_name: orders-histogram-pilot
    # 显式接收目标暴露的原生直方图
    scrape_native_histograms: true
    # 迁移期保留目标同时暴露的经典部分，供旧规则使用
    always_scrape_classic_histograms: true
    static_configs:
      # 替换为已获授权且可达的实际指标端点
      - targets: ['orders-metrics.internal:9090']

这两个选项不能替应用创造不存在的数据。如果端点只暴露原生直方图，always_scrape_classic_histograms 不会凭空生成一套完整经典桶；若端点只暴露经典形式，打开原生抓取也不等于获得标准指数桶的原生观测。协议协商、客户端库能力以及暴露格式都应在试点范围内明确。

双格式保留也有成本：同一批观测对应两种存储表示，过渡期的资源消耗可能增加。建议先限定一个服务或采集任务，并在迁移表上记录哪些规则仍依赖经典序列、谁负责切换、何时可以停止保留。不要先删旧数据，再寻找遗漏的仪表盘。

把查询迁移当作独立变更

假设试点服务使用虚构指标名 order_dispatch_duration_seconds，目标是按 job 聚合最近 7 分钟的 p95。经典直方图的表达式依赖桶上界标签 le：

# 经典直方图：先计算每条桶序列的速率，再保留 le 聚合
histogram_quantile(
  0.95,
  sum by (job, le) (
    rate(order_dispatch_duration_seconds_bucket[7m])
  )
)

原生直方图对应的是基础指标名，不再用经典桶后缀和 le 分组：

# 原生直方图：聚合直方图样本的速率，不再按经典 le 标签分组
histogram_quantile(
  0.95,
  sum by (job) (
    rate(order_dispatch_duration_seconds[7m])
  )
)

这两段是未执行的示例，名称和窗口为本场景设计。不能仅全局删除字符串 _bucket：旧规则可能计算的是计数、总和、特定阈值下的占比或录制规则结果，而不只是分位数。迁移清单应逐条注明输入类型、单位、聚合标签、时间窗口和告警条件。

分位数还是根据桶进行估算。不同桶布局与插值方式可能让新旧曲线不完全重合；应根据业务容忍范围解释差异，而不是要求所有点逐位相等。跨实例聚合要先合并分布再求分位数，不能把各实例的 p95 直接平均成服务 p95。

双格式期间，新旧指标反映相同观测，不应将两者再相加当成两份流量。录制规则可以先使用独立的新名称，避免覆盖旧规则的含义。历史经典序列也不会因为改了抓取设置，就自动转换成覆盖全部保留期的原生历史。

将远端链路和回退条件写进迁移表

本地能显示原生数据，并不能说明长期存储已经收到相同数据。Prometheus 3.x 的相关远写配置还涉及 send_native_histograms；接收端也必须具备对应支持。不要仅以远写请求成功判断原生样本完整，接收端不认识新增字段时可能忽略它们。具体选项及协议应以部署版本和接收端官方文档为准。

对上面的订单服务，合理的停止条件不是“升级完成”，而是关键仪表盘和告警已有负责人确认，远端消费没有遗漏，且资源与估算差异能被解释。出现旧规则突然无数据、远端查询缺失或资源超出计划时，应暂停扩大范围，并回到保留的配置和规则。关闭原生抓取只有在目标仍暴露所需经典数据时，才能恢复预期的经典采集；中断窗口也不会自动补回。

本文提供迁移规划与配置示例，没有连接实际指标端点、运行查询或生成验证结果。上线时应在授权环境中为这些迁移条件准备证据，而不是把说明图当成已经通过的验收记录。

只升级 Prometheus，不改客户端库可以吗？

服务器支持不等于端点已经暴露原生数据。应先明确客户端或 exporter 的能力；经典转换为自定义桶原生直方图也是另一种选择，不要与标准指数桶的原生暴露混为一谈。

启用原生后，可以立刻停止经典采集吗？

只有在依赖经典序列的查询、告警和外部消费者都完成迁移，并具备可行回退条件后才考虑停止。短期双格式是兼容手段，不应成为没有期限的默认状态。

迁移后 p95 有变化就说明新指标错了吗？

不一定。先比较指标语义、单位、聚合范围与窗口，再判断桶布局和估算方法带来的差异。没有流量、缺少样本或漏采数据，也不能被解释成延迟改善。

官方参考：原生直方图规范与版本说明、抓取配置说明、PromQL 查询函数。部署前选择与实际版本一致的文档，不将 latest 的行为直接套用到旧版本。