🪣 直方图水桶与 topk：分位数怎么算、毛线团怎么治

💡 一句话理解

系统不记录每个请求的耗时（太贵），只维护一叠累积水桶：「≤10ms 的有多少个、≤50ms 的有多少个、≤1s 的有多少个……」每只桶是一个 Counter，标签 le（less-or-equal）就是桶的天花板。histogram_quantile 拿着这叠桶回答「第 950 名排在哪」——在相邻两只桶之间插值估出 P95。

代价是 P95 只是估算值（桶越粗越不准）；收益是十几个计数器就能算任意分位数。而当你把几十个接口的分位数曲线全部画出来，图会糊成毛线团——topk(10, …) 就是急救剪：只画最慢的前 10 条（c19 口径），排行榜立刻清爽。另外记住第一大坑：算分位数时 by (le) 万万不能丢，丢了桶就被加成一条线，分位数直接失明。

🧩 费曼拆解 讲给完全没接触过的小白

学校发成绩单从不公布每个人的分数，只公布分数段人数表：「60 分以下 5 人、80 分以下 38 人、100 分以下 40 人」。注意这张表不用存 40 个人的分数，只存 3 个计数——却足以回答「前 95% 的分界线大概在哪」：第 38 名在 80 分档里，第 36~38 名之间的分界线一插值就估出来了。直方图（Histogram）就是这张分数段人数表，每档是一只桶，桶里是累计人数。

为什么监控要这么省？因为「把每个请求的耗时都存下来」代价巨大——一秒钟几千个请求，存一周就是天文数字。分桶只要十几只计数器，就能随时算 P50/P95/P99 任意分位数。代价你现在已经知道：桶之间的细节丢了，P95 是插值估出来的，桶越粗越只能看大概。四两的字节分布面板（m123）干脆 p50/p95 一起看，就是为了对冲估算误差。

实操中有两个必杀技。第一是公式骨架：histogram_quantile(0.95, sum(rate(…_bucket[5m])) by (le, 维度))——先 rate（桶是 Counter）、再 sum by le（保留天花板标签）、最后插值；le 忘了 by 就全毁。第二是 topk：几十个 handler 各来几条线，图糊得没法看——topk(10, …) 每个时刻只留最慢的前 10 名，c19「P99 Top 10 慢接口」就是 topk 和 histogram_quantile 的合体技。

🧠 必知必会 看懂本课全部面板的地基

Histogram = 一叠累积桶

延迟、字节数这类「分布值」不存单值，存一叠桶；每只桶是一个 Counter：耗时/字节数 ≤ le 的累计个数。后缀 _bucket 就是它的身份证。

# 一只桶的样子：le 是天花板，值是累计个数
siliang_llm_call_duration_seconds_bucket{le="0.5"}
# 含义：耗时 ≤ 0.5 秒的调用累计发生了多少个

桶是累积的（cumulative）

le 大的桶包含 le 小的：≤1s 的 990 个里已经包含 ≤50ms 的 950 个。最后一档永远是 le="+Inf"（全部样本）。

# 累积关系：只增不减的套娃
le="0.05" → 950
le="1"    → 990   # 包含上面那 950 个
le="+Inf" → 1000  # 全部

标准公式骨架（背下来）

histogram_quantile(分位, sum(rate(…_bucket[窗口])) by (le, 维度))——rate 因为桶是 Counter；sum by (le, …) 因为要跨 worker 汇总但必须保留 le；最后插值。

# c15 口径：按 model 拆的 LLM 延迟分位数（单位：秒）
histogram_quantile(0.95, sum(rate(siliang_llm_call_duration_seconds_bucket[5m]))
  by (le, model))

忘了 by (le) = 第一大坑

没有 by (le)，一叠桶被 sum 加成一条线，histogram_quantile 拿不到桶就无法插值，输出的数字毫无意义。看延迟图出现「鬼数字」，先查 le。

# 错: histogram_quantile(0.95, sum(rate(…_bucket[5m])))          # → 鬼数字
# 对: histogram_quantile(0.95, sum(rate(…_bucket[5m])) by (le, handler))

桶必须先 rate 再插值

桶是「累计个数」的 Counter，直接拿开机以来的累计值算分位数，得到的是「历史总平均的估算」，不是「现在的状态」。先 rate 让它变成「窗口内每秒进桶速度」。

# 错: histogram_quantile(0.95, sum(…_bucket) by (le))   # → 开机以来
# 对: histogram_quantile(0.95, sum(rate(…_bucket[5m])) by (le))

分位数是插值估算

P95 落在哪两只桶之间是估出来的，桶越粗越不准。四两字节分布面板用 p50/p95 对照（m123）就是为了看「分布形状」而不迷信单点。

# m123 口径：xAI 生图响应字节 p50/p95 对照
histogram_quantile(0.95, sum(rate(siliang_xai_image_response_bytes_bucket[5m])))
histogram_quantile(0.50, sum(rate(siliang_xai_image_response_bytes_bucket[5m])))

topk 治毛线团

topk(N, 表达式) 每个时刻只保留值最大的前 N 条序列。放在最外层就是排行榜：c19 取最慢 10、b4 取最慢 5。

# c19 完整口径：全站最慢 10 个接口的 P99
topk(10, histogram_quantile(0.99,
  sum(rate(siliang_http_request_duration_seconds_bucket[5m])) by (le, handler)))

别忘了 job 过滤

桶指标同样受 server job 双计影响——漏了过滤，每只桶的个数翻倍，分位数跟着失真。所有 _bucket 查询都要带 job。

# 标准姿势：job 过滤放花括号里
sum(rate(siliang_http_request_duration_seconds_bucket{job="siliang_backend_worker"}[5m])) by (le, handler)

🔗 在四两监控里哪里用到 理论落回你的 89 张图

① HTTP P99 延迟（Top 10 慢接口）（c19）——topk 与 histogram_quantile 的合体样板，你的性能优化待办清单：🟢 HTTP P99 延迟（Top 10 慢接口）↗

② LLM 调用延迟 P50/P95/P99（按 model）（c15）——by (le, model) 的教科书：gpt-5 长输出 60s+ 属正常：🟡 LLM 调用延迟 P50/P95/P99 ↗

③ WS 连接持续时长 P50/P95/P99（c23）——by (le) 全站一条线，P99 异常长 = 僵尸连接线索：🔵 WS 连接持续时长 ↗

④ biz HTTP 延迟 P95（Top 5）（b4）——topk(5, …) 聚焦版；要 P99 就把 0.95 改成 0.99：🟢 HTTP 延迟 P95（Top 5 慢接口）↗

⑤ 文件/媒体字节分布 p95（m109）——直方图不只量时间：ZIP 产物/视频转存/TTS 音频的「典型体重」也是桶，解释 RSS 为什么冲高：📏 文件/媒体处理字节分布 p95 ↗

🏭 生产实战 real world

# 全站最慢 10 个接口（P99，单位：秒，c19 口径）
topk(10, histogram_quantile(0.99,
  sum(rate(siliang_http_request_duration_seconds_bucket{job="siliang_backend_worker"}[5m]))
    by (le, handler)))

# 判读：榜首长期霸榜 = 最优先优化；名次变化 = 优化有效/退化

# 固定 handler，三条分位数一起看（把 P95 榜首的 handler 填进来）
histogram_quantile(0.50, sum(rate(siliang_http_request_duration_seconds_bucket{handler="/me"}[5m])) by (le))
histogram_quantile(0.95, sum(rate(siliang_http_request_duration_seconds_bucket{handler="/me"}[5m])) by (le))
histogram_quantile(0.99, sum(rate(siliang_http_request_duration_seconds_bucket{handler="/me"}[5m])) by (le))

# 判读：三线贴得近 = 均匀慢（容量问题）；P99 独秀 = 长尾（锁/缓存/大参数）

# 按 model 拆的 P95（单位：秒）
histogram_quantile(0.95,
  sum(rate(siliang_llm_call_duration_seconds_bucket{job="siliang_backend_worker"}[5m]))
    by (le, model))

# 判读：gpt-5 长输出 60s+ 属正常；P50 整体抬升才是 provider 变慢/限流

# ZIP 产物的典型体重 P95（m109 口径之一）
histogram_quantile(0.95,
  sum(rate(siliang_file_batch_archive_bytes_bucket{job="siliang_backend_worker"}[5m]))
    by (le))

# 用法：RSS 冲高时刻 × 字节分布对时间戳 = 找到搬运工；
# 处理 200MB 视频时内存必先涨 200MB+

# 巡检大屏：只看前 3，一眼扫完
topk(3, histogram_quantile(0.99, sum(rate(siliang_http_request_duration_seconds_bucket[5m])) by (le, handler)))

# 排查：前 10（c19 口径）；全量导出给脚本分析：去掉 topk
# 注意：topk 每个时刻独立选人，线条中途换 handler 属正常，看图例认名字

⚠️ 常见坑 pitfalls

# 错: histogram_quantile(0.95, sum(rate(…_bucket[5m])))            # → 鬼数字
# 对: histogram_quantile(0.95, sum(rate(…_bucket[5m])) by (le, handler))

# 错: histogram_quantile(0.95, sum(…_bucket) by (le))    # → 开机以来
# 对: histogram_quantile(0.95, sum(rate(…_bucket[5m])) by (le))

# 错: avg by (le) (rate(…_bucket[5m]))        # → 人数缩水
# 对: sum by (le) (rate(…_bucket[5m]))        # → 人数合并

# 错: (P95_A + P95_B) / 2                              # → 谁都不是
# 对: histogram_quantile(0.95, sum(rate(…_bucket[5m])) by (le))  # → 全站

# 错: 认死一条线的颜色当「同一个接口」    # → 名字会换
# 对: 看图例名；固定对象用 {handler="/me"} 过滤

# 错: histogram_quantile(95, …)           # → 不是合法分位
# 对: histogram_quantile(0.95, …)         # → P95

# 错: P95 不动 = 面板坏了？              # → 桶粗，精度如此
# 对: p50/p95 双线看趋势（m123 口径），粗桶看形状足够

🎓 费曼自测 合上书，能讲出来才算懂

🔗 相关课程