Go runtime/metrics 怎样用直方图桶估算百分位

使用 Go 的 runtime/metrics 读取直方图后，不能把 Buckets 直接当成样本值列表。它是一组递增边界，Counts 才是每个区间的计数；两者配对后，按累计计数找到目标桶，就能得到中位数或 P95 这类“桶级近似值”。这个结果不是原始样本上的精确百分位，精度上限由桶宽决定。

官方文档地址：https://pkg.go.dev/runtime/metrics

最稳妥的做法是先检查 Value.Kind()，再确认 len(Counts)+1 == len(Buckets)，最后用“目标百分位 × 总计数”定位第一个累计计数达到目标的桶。

先看懂 Buckets 和 Counts 的对应关系

Float64Histogram 表示一个浮点分布。假设 Buckets 有 5 个边界，那么有效计数桶是 4 个：第 0 个桶覆盖 [Buckets[0], Buckets[1])，第 1 个桶覆盖 [Buckets[1], Buckets[2])，以此类推。也就是说，Counts[i] 表示第 i 个区间的权重，而不是 Buckets[i] 这个点出现了多少次。

直方图还带有指标单位。例如内存分配大小的桶边界以字节解释，计数则表示落入区间的样本数。读取指标时不要假定某个字符串永远存在，先从 metrics.All() 找到支持的描述，再按名称构造样本。

读取直方图时先检查 Kind 和切片长度

下面的示例选择一个按分配大小统计的运行时直方图，并把百分位计算封装为可复用函数。示例只展示 API 的数据关系与计算方法，不依赖某次机器上的真实输出。

package main

import (
    "errors"
    "fmt"
    "math"
    "runtime/metrics"
)

// quantileBucket 返回目标百分位所在桶的下界，结果是桶级近似值。
func quantileBucket(h *metrics.Float64Histogram, q float64) (float64, error) {
    // 直方图必须有边界；N 个计数桶需要 N+1 个边界。
    if h == nil || len(h.Buckets) == 0 || len(h.Counts)+1 != len(h.Buckets) {
        return 0, errors.New("invalid histogram shape")
    }
    // 百分位只接受闭区间 [0, 1]，避免把目标计数算到范围外。
    if q  1 {
        return 0, errors.New("quantile must be between 0 and 1")
    }

    var total uint64
    for _, count := range h.Counts {
        // Counts 是各桶权重，先求出本次直方图的总样本数。
        total += count
    }
    if total == 0 {
        return 0, errors.New("histogram has no samples")
    }

    // 向上取整，让 P95 至少命中第一个满足目标的样本位置。
    target := uint64(math.Ceil(float64(total) * q))
    if target == 0 {
        target = 1
    }
    var cumulative uint64
    for i, count := range h.Counts {
        // 累计计数第一次达到目标时，当前边界就是近似分位点。
        cumulative += count
        if cumulative >= target {
            return h.Buckets[i], nil
        }
    }
    return 0, errors.New("quantile is outside histogram")
}

func main() {
    // 选择一个直方图指标；生产代码应先结合 metrics.All 检查支持情况。
    const name = "/gc/heap/allocs-by-size:bytes"
    samples := []metrics.Sample{{Name: name}}
    metrics.Read(samples)
    if samples[0].Value.Kind() != metrics.KindFloat64Histogram {
        // KindBad 或其他类型都不能调用 Float64Histogram。
        panic(fmt.Sprintf("%s is not a histogram", name))
    }
    p95, err := quantileBucket(samples[0].Value.Float64Histogram(), 0.95)
    if err != nil {
        panic(err)
    }
    fmt.Printf("p95 bucket lower bound: %f\\n", p95)
}

按累计计数定位中位数和 P95

算法的核心只有一条线：先把 Counts 累加成总数，再把目标百分位转换成目标计数，最后找到第一个累计值不小于目标的桶。例如总数为 100，P95 的目标位置是 95；如果前 4 个桶累计只有 91，而第 5 个桶累计到 98，那么返回第 5 个桶的下界。

返回桶下界是一个保守且容易解释的选择：它说明至少已经进入这个区间，但不能说明真实分位点就在下界上。如果需要更细的估算，可以在命中桶内部按比例插值，不过那依赖桶内分布假设，不能把插值结果包装成精确值。

累计直方图不能直接当成单次窗口分布

部分运行时分布指标的 Description.Cumulative 为真，桶计数会随时间单调增加。此时一次读取得到的是从进程开始以来的累计分布；如果你要观察某个时间窗口，应保存两次采样，并对相同边界下的每个桶计数做差，再在差值直方图上计算百分位。

同时要注意 metrics.Read 可能复用底层直方图存储。不要在下一次读取仍在进行时并发访问同一个 Float64Histogram；如果要跨 goroutine 或跨采样周期保存结果，应复制 Buckets 和 Counts。官方文档还建议通过 metrics.All() 发现支持的指标，避免把某个运行时实现中的名称硬编码成跨版本保证。

相关问题

为什么不能直接用 Buckets[len(Buckets)/2] 当中位数？

因为桶边界只描述区间，样本数量可能集中在任意桶里。中位数必须结合 Counts 的累计权重定位。

目标百分位为 0 时应该返回什么？

工程上通常把它归一到第一个非空桶，示例把目标计数至少设为 1；若要表达严格的最小值，需要原始样本或更细的采样结构。

为什么同一个指标的百分位会随时间变化？

累计分布会持续吸收新样本。若关心最近窗口，先对两次采样的桶计数做差，再计算窗口内的近似百分位。