直方图查询 · histogram_quantile 的真相

histogram_quantile 的核心假设：桶内的数据是均匀分布的。

桶:     le=0.1   le=0.5   le=1.0
计数:      240      980     1000
                    ↑ P99 落在这个桶里(0.1 ~ 0.5 之间)

真实分布可能是:
  情况 A:  ▁▁▁▁▁▁▁█   ← 全挤在 0.5 附近 → 真实 P99 ≈ 0.49
  情况 B:  █▁▁▁▁▁▁▁   ← 全挤在 0.1 附近 → 真实 P99 ≈ 0.11
但 histogram_quantile 假设:  ▄▄▄▄▄▄▄▄  ← 均匀!→ 给出 P99 ≈ 0.3

两种真实情况，它给出同一个答案——而且都是错的。

这就是为什么桶必须在 SLO 阈值附近加密：桶越密，每个桶越窄，“桶内均匀”这个假设的误差上界就越小。桶宽就是你的误差棒。

实战推论： 如果你的 SLO 是 P99 < 300ms，而桶只有 [0.25, 0.5]，那么 histogram_quantile 返回的 310ms 完全可能实际是 260ms 或 490ms——你根本无法判断 SLO 有没有破。第 2 部分反复强调这一点，现在你看到了源码层面的原因。

如果分位数落在最高的那个桶（即 +Inf 桶）里，返回的是第二高桶的上界**。**

桶:  le=1   le=5   le=+Inf
计数:  900    980    1000
                     ↑ P99 落在这里(5 ~ ∞)

返回:  5      ← 第二高桶的上界,不是 ∞、也不是别的

为什么这么设计？ 因为 +Inf 桶的上界是无穷大，插值无从谈起（你没法在 5 和 ∞ 之间做线性插值）。所以只能保守地返回已知的最大有限边界。

这个规则的实战后果极其重要：

如果你的 P99 长期“卡”在某个数字上不动（正好等于你倒数第二个桶的边界），那不是巧合——是你的桶不够高，真实的 P99 已经溢出到 +Inf 桶里了。 你看到的 “P99 = 5s” 实际可能是 8s、30s 或者更糟——你的 P99 被截断了，而且它看起来还挺“稳定”。

这是个危险的静默失败：图上一条平稳的线，你以为系统很稳，其实是指标失去了分辨能力。检查方法：看看你的 P99 是不是正好等于某个桶边界，如果是，加更高的桶。

“最高桶不是 +Inf 就返回 NaN”这条值得注意——它意味着你的 histogram 必须有 +Inf 桶，否则 histogram_quantile 完全不工作。好消息是客户端库会自动加，你一般不用操心；但如果你手工构造直方图指标（比如用 recording rule 或从别的系统转换），别忘了它。

“0 个观测返回 NaN”也很实际：一个刚启动、还没有任何请求的服务，它的 P99 是 NaN。如果你的告警是 histogram_quantile(...) > 0.3，NaN > 0.3 是 false，所以不会误报——这是好事。但反过来，如果你写 histogram_quantile(...) < 0.3 来判断“健康”，NaN < 0.3 也是 false，你会误以为它不健康。写告警时要考虑 NaN。

标准姿势：histogram_quantile(0.99, sum by (le) (rate(..._bucket[5m])))

# ✅ 全局 P99(跨所有实例)
histogram_quantile(0.99,
  sum by (le) (rate(http_request_duration_seconds_bucket[5m]))
)

# ✅ 按 service 分的 P99(le 必须在 by 里!)
histogram_quantile(0.99,
  sum by (le, service) (rate(http_request_duration_seconds_bucket[5m]))
)

# ✅ 只看成功请求的 P99(第 2 部分的教训)
histogram_quantile(0.99,
  sum by (le) (rate(http_request_duration_seconds_bucket{status=~"2.."}[5m]))
)

三条铁律：

1. le 必须出现在 by 里 —— 忘了它，桶就被聚合没了，histogram_quantile 拿不到分桶信息，结果是垃圾。这是最常见的错误。
2. 先 rate() 再 sum —— 和 counter 一样的道理：_bucket 也是 counter，必须先 rate() 才能正确处理重置。
3. 顺序是 histogram_quantile(q, sum(rate(...))) —— 从里到外：rate → sum by le → quantile。记住这个洋葱结构。

# ❌ 经典错误:le 丢了
histogram_quantile(0.99, sum by (service) (rate(..._bucket[5m])))
#                              ↑ 少了 le!结果无意义

# ❌ 经典错误:顺序反了
sum by (le) (histogram_quantile(0.99, rate(..._bucket[5m])))
#            ↑ 先算每个实例的分位数再 sum = 毫无意义(第 1 部分讲过)

上一部分提过的 native histograms 基本终结了本章的大部分纠结：

• 桶自动指数生成、又密又广 → 桶内均匀假设的误差极小，不用你在 SLO 阈值附近手工加密。
• 不会“溢出到 +Inf 桶” → P99 不会被静默截断。
• le 不再是标签 → 不会忘记 by (le)，也不吃基数。

查询上，histogram_quantile 对 native histogram 直接可用（语法一样，不用写 _bucket）：

histogram_quantile(0.99, sum(rate(http_request_duration_seconds[5m])))
#                                  ↑ 没有 _bucket 后缀,没有 by (le)

新项目直接上 native histograms——它把本章讲的坑消掉了一大半。