Kubernetes v1.37 原生直方图 Beta 后 Prometheus 兼容点怎么查

Kubernetes v1.37 已把原生直方图支持推进到 Beta，并默认打开 NativeHistograms feature gate，但这不等于 Prometheus 自动开始存储原生直方图。兼容性要从 Kubernetes 组件暴露、Prometheus 抓取配置、查询与转发链路三层分别确认。

官方地址：https://kubernetes.io/docs/reference/instrumentation/native-histograms/

Prometheus 参考：https://prometheus.io/docs/specs/native_histograms/

迁移期最稳妥的做法是：Prometheus 3.x 对目标 job 开启 scrape_native_histograms，同时保留 always_scrape_classic_histograms；只有确认面板、告警、remote_write 和联邦链路都能处理后，才考虑减少经典格式。

先确认 Kubernetes 端确实具备双格式暴露

v1.37 的 Beta 实现建立在 Kubernetes 组件指标子系统上。默认开启 feature gate 后，支持的控制面和节点组件会在抓取协议允许时暴露经典与原生格式。这里有两个容易混淆的点：第一，组件之间不是一个总开关；第二，只有请求的协议支持原生直方图时，Prometheus 才有机会拿到对应数据。

因此升级后先记录实际抓取对象：kube-apiserver、kube-scheduler、kubelet 等分别看，不要只根据集群版本判断所有目标都已切换。若某个组件显式关闭了 NativeHistograms，它仍可能只提供经典直方图。

Prometheus 端要查三个配置点

Prometheus 2.40 起具备实验性原生直方图支持，3.0 到 3.7 已稳定但仍建议按 job 控制；3.8 起稳定配置继续以 scrape_native_histograms 为主，3.9 及以后不要再依赖已移除的全局旧开关。迁移期可以先这样配置一个 Kubernetes job：

scrape_configs:
  - job_name: 'kubernetes-apiservers'
    # 让 Prometheus 摄取目标暴露的原生直方图样本。
    scrape_native_histograms: true
    # 迁移期间保留经典桶，给旧面板和告警留回退路径。
    always_scrape_classic_histograms: true

如果配置过 scrape_protocols，还要确认列表里有 PrometheusProto。原生直方图需要 Protobuf 暴露格式；自定义协议优先级时漏掉它，最常见的结果就是 Kubernetes 端“已经支持”，Prometheus 端却只收到经典样本。

兼容性重点不在“能不能抓”，而在“怎么查”

经典直方图通常拆成带 le 标签的 _bucket、_sum 和 _count 序列；原生直方图则以一个结构化样本保存动态桶。原有基于 rate(metric_bucket[5m]) 的面板不能简单假设会自动得到同样的输入，查询要按 Prometheus 原生直方图函数和样本类型重新核对。

更重要的是，经典和原生直方图不能直接互相聚合。某个 job 在某天从经典切到原生后，包含切换点的范围向量可能只有一部分样本；跨时间对比时不要把“曲线断了”误判成业务延迟突然归零。若必须维持连续看板，先保留经典格式，或把切换时间作为查询和告警的明确边界。

remote_write、联邦和回退路径要单独核对

Prometheus 的 remote_write 需要显式设置 send_native_histograms: true 才会发送原生直方图；接收端不支持时会忽略新增字段，所以“发送成功”不代表下游保存了原生样本。联邦抓取也要在下游 Prometheus job 上开启 scrape_native_histograms，并优先使用 Protobuf。

上线前建议按“一个组件、一个 job、一个看板”做灰度：先确认抓取目标、查询结果和规则评估，再观察远程写入接收端。如果旧版本 Prometheus 或第三方接收端无法处理，就保留经典格式；回退时优先关闭 Prometheus 端的原生摄取配置，不要为了追求新样本而改指标名。

常见问题

Kubernetes v1.37 升级后一定要改 Prometheus 吗？

不一定。旧 Prometheus 可以继续抓经典格式；如果要摄取原生直方图，才需要按版本增加相应配置。

为什么 feature gate 开了却看不到原生样本？

先查抓取协议和 Prometheus job。自定义 scrape_protocols 时缺少 PrometheusProto，或 job 没开 scrape_native_histograms，都会导致只看到经典样本。

可以马上关闭经典直方图吗？

不建议直接切。先确认旧面板、告警、remote_write、联邦和跨时间范围查询，再按 job 灰度关闭。

判断这次升级是否兼容，核心不是看版本号，而是沿着“组件暴露—协议协商—Prometheus 摄取—查询和下游”逐层核对。只要保留经典回退，原生直方图就可以先作为可控的迁移增量。