Kubernetes v1.37 原生直方图进入 Beta 后如何核对监控兼容性

如果 Kubernetes v1.37 升级后监控团队担心“原生直方图会不会让旧面板失效”，先记住结论：NativeHistograms 在 v1.37 已进入 Beta 并默认开启，但 Kubernetes 会继续提供经典直方图；真正决定是否采到原生格式的是 Prometheus 版本和 scrape 配置。迁移期不要直接关闭经典数据，先让两种格式并存。

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

这次 Beta 变化到底改变了什么

经典 Prometheus 直方图预先写死多个 le 桶，每个桶都会形成时间序列。原生直方图改用动态指数桶，把分布信息放进一条更紧凑的直方图序列，适合观察 API 延迟这类长尾数据。Kubernetes 官方说明它在 v1.37 进入 Beta，且 NativeHistograms 默认开启；这一变化发生在组件指标子系统，不等于你的 Prometheus 已经开始存储原生数据。

支持的组件包括 kube-apiserver、kube-controller-manager、kube-scheduler、kubelet 和 kube-proxy。如果某个组件显式关闭了 feature gate，它仍只暴露经典格式。

先看 Prometheus 版本，再决定配置写法

兼容性核对的第一项不是改 Kubernetes 参数，而是确认 Prometheus。官方文档给出的边界可以压缩成下面这张表：

Prometheus 3.x 的迁移配置可以先这样写。注释保留在配置块里，便于和变更单一起评审：

scrape_configs:
  - job_name: kubernetes-apiservers
    # 允许 Prometheus 请求并存储原生直方图
    scrape_native_histograms: true
    # 迁移期间保留 _bucket、_count、_sum，保护旧面板和告警
    always_scrape_classic_histograms: true
    static_configs:
      - targets: ["kube-apiserver.monitoring.svc:443"]

如果自定义了 scrape_protocols，还要确认其中包含 PrometheusProto。原生直方图依赖 Protobuf 协议；直接用普通文本方式访问 /metrics，看到经典桶并不能证明原生数据没有暴露。

用三层证据核对采集是否真的兼容

1. 组件层：在 Prometheus 中查询 kubernetes_feature_enabled{name="NativeHistograms"}，返回 1 只能说明该组件的 feature gate 已启用。
2. 协议层：对测试环境的指标端点请求 Prometheus Protobuf，检查直方图消息是否同时出现 classic bucket 与 schema/positive_span 字段。示例只作操作示意，不要把令牌写进脚本：

# 仅在已完成认证的测试环境检查 Protobuf 内容协商
curl -H 'Accept: application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=delimited' \
  https:///metrics
# 返回内容应交给 Prometheus 解码器或抓取链路检查，不要把二进制响应当文本阅读

3. 查询层：在保留经典数据的前提下，对同一时间窗口分别运行两类 P99 查询：

# 经典直方图：必须保留 le 桶标签
histogram_quantile(0.99, sum by (le) (rate(apiserver_request_duration_seconds_bucket[5m])))

# 原生直方图：直接对指标序列聚合，不再写 _bucket 和 le
histogram_quantile(0.99, sum(rate(apiserver_request_duration_seconds[5m])))

两条查询的数值不必逐点完全相同，但都应有数据且趋势可解释。若打开原生抓取后旧面板突然空白，优先检查 always_scrape_classic_histograms 是否仍为 true，不要先修改 Grafana 表达式。

面板迁移不要一步切断经典数据

建议把迁移拆成四个小动作：先在一个 scrape job 灰度打开两种格式；再把 P99 等查询从 ..._bucket 改为原生直方图写法；随后在预发布环境检查 Grafana 面板和告警；最后确认没有旧查询依赖，再将 always_scrape_classic_histograms 设为 false，换取更低的存储开销。

回滚也分两层。最快三秒级的动作是在 Prometheus job 上设 scrape_native_histograms: false，不需要重启 Kubernetes；如果组件本身不希望暴露原生格式，再将对应组件的 --feature-gates=NativeHistograms=false 改回去并重启。Beta 的价值是可渐进采用，不是要求所有仪表盘同一天完成改写。

常见问题

升级 Kubernetes v1.37 后必须立刻改所有 PromQL 吗？

不必。组件默认双格式暴露，先保留经典抓取即可；等原生查询在预发布验证通过，再按面板和告警逐项迁移。

为什么直接访问 /metrics 只看到了 _bucket？

普通文本协议只展示经典桶。Prometheus 在启用原生抓取时会通过内容协商请求 Protobuf，直接检查时必须带对应的 Accept 头。

Prometheus 低于 2.40 能否只升级 Kubernetes？

不能获得原生直方图存储能力。Kubernetes 仍可暴露经典格式，但采集端需要升级到 2.40 或更高版本，3.x 更适合按 job 渐进迁移。

上线前结论：把“feature gate 已开启”“Prometheus 能请求 PrometheusProto”“旧查询仍有数据”“原生查询已在预发布验证”当作四个独立勾选项。四项都通过后，再考虑关闭经典抓取；任何一项不清楚，都先保持双格式。