Go runtime/metrics 读取直方图时如何配对 buckets 与 counts

我第一次把 Go 运行时直方图接到诊断输出时，最容易误读的不是 API，而是两个切片的含义：Buckets 存的是边界，Counts 存的是区间里的样本权重。两者不是同长度的一一映射。正确关系是：len(Counts) == len(Buckets)-1，第 i 个计数对应区间 [Buckets[i], Buckets[i+1])。

官方文档：https://pkg.go.dev/runtime/metrics#Value.Float64Histogram

读取 Go runtime/metrics 直方图时，先检查 Value.Kind()，再把相邻两个 bucket 边界配成一个区间；不要用同一个下标把 bucket 和 count 直接当成两列独立数据。

我为什么会把 buckets 和 counts 看错

runtime/metrics 的普通数值可以直接读成 uint64 或 float64，直方图则返回一个 *metrics.Float64Histogram。它表达的是一组浮点观测值的分布，边界切片描述分桶，计数切片描述每个分桶里的权重。

容易踩坑的写法是把 Buckets[i] 和 Counts[i] 打印成“边界—数量”一行，然后误以为最后一个边界也有一个同下标计数。实际上边界比区间多一个：两个边界才能围出一个区间。

先检查 Kind，再读取直方图

Value.Float64Histogram 只适用于 KindFloat64Histogram。指标名称来自运行时支持集合，名称不再支持时，读取结果可能是 KindBad；因此诊断代码应该把这一步当成正常分支，而不是直接调用后等待 panic。

package main

import (
    "fmt"
    "runtime/metrics"
)

func pickHistogramMetric() (string, bool) {
    // 从当前运行时支持的指标中选择直方图，避免硬编码一个可能不存在的名称。
    for _, desc := range metrics.All() {
        if desc.Kind == metrics.KindFloat64Histogram {
            return desc.Name, true
        }
    }
    return "", false
}

func readHistogram(name string) error {
    samples := []metrics.Sample{{Name: name}}
    // Read 会把指定指标的当前值写回 Sample.Value。
    metrics.Read(samples)
    value := samples[0].Value
    if value.Kind() == metrics.KindBad {
        return fmt.Errorf("metric %q is not supported", name)
    }
    if value.Kind() != metrics.KindFloat64Histogram {
        return fmt.Errorf("metric %q has kind %v, not a histogram", name, value.Kind())
    }

    histogram := value.Float64Histogram()
    // Float64Histogram 用一个多出的边界描述 N 个区间。
    if len(histogram.Buckets) 

这里的关键不是“找到一个指标就打印”，而是把读取、类型确认和形状确认分开。这样以后换成指定指标名时，仍然能保留同一套保护。

两个切片应该怎样配对

假设边界是 [-Inf, 0.001, 0.01, +Inf]，那么它围成三个区间：

所以遍历公式始终是 lower := Buckets[i]、upper := Buckets[i+1]、count := Counts[i]。不要写成遍历 Buckets 再访问 Counts[i]，那会在最后一个边界处越界或制造错误的“最后一桶”。

空样本不等于读取失败

一个合法直方图可以出现所有 Counts 都为零的情况，这通常只表示当前采样窗口没有观测到样本。判断“有没有样本”应累加计数，而不是拿某个边界值或切片长度判断。

func totalCount(histogram *metrics.Float64Histogram) uint64 {
    var total uint64
    for _, count := range histogram.Counts {
        // 计数为零时保留分桶结构，便于下一次采样复用同一组边界。
        total += count
    }
    return total
}

func sampleState(histogram *metrics.Float64Histogram) string {
    if totalCount(histogram) == 0 {
        // 空样本是“当前没有观测”，不要把它改写成读取错误。
        return "empty-sample"
    }
    return "has-sample"
}

另外，官方定义允许边界出现 -Inf 和 Inf。格式化输出时接受这两个值即可，不要为了让表格看起来整齐而把它们替换成随意的最小值和最大值。

为什么不能随手改 Buckets

对于同一个指标名称，Buckets 在进程退出前不会改变；同时这个切片可能与其他 Float64Histogram 的边界切片共享底层数据。它适合读取和缓存，不适合原地排序、截断或覆盖。

func copyBounds(histogram *metrics.Float64Histogram) []float64 {
    // 只有确实需要修改边界时才复制，避免改变运行时共享的只读视图。
    bounds := append([]float64(nil), histogram.Buckets...)
    return bounds
}

如果只是要渲染报表，不需要复制；如果要传给会原地排序的旧接口，先复制再交给它。计数和边界的配对关系仍然以原始切片为准。

做趋势比较时还要看 Cumulative

配好区间只是第一步。若要比较两次采样，先查看对应的 metrics.Description.Cumulative：

• 累计直方图的每个桶会随样本增加而单调增长，两次采样可以按桶做差得到时间段增量。
• 非累计值不能直接套用累计差分公式，应按指标说明解释当前值。
• 两次采样最好使用同一个指标名称和同一组边界；不要把不同指标或不同进程的 buckets 直接拼在一起。

如果只需要一次诊断快照，直接输出每个区间和 count 即可；如果要计算比例，先求所有 count 的总和，再用单桶 count 除以总和，并明确说明这是当前快照的分布，而不是延迟百分位。

我现在会保留的排查清单

1. 指标名是否来自当前支持集合，读取结果是否为 KindBad。
2. 是否只在 KindFloat64Histogram 时调用 Float64Histogram。
3. 是否确认 len(Counts) == len(Buckets)-1。
4. 是否用相邻边界组成半开区间，而不是把单个边界当成一桶。
5. 是否把全零计数识别为空样本，并保留 Inf 边界。
6. 是否避免原地修改可能共享的 Buckets。
7. 做多次比较时，是否先区分累计指标和瞬时指标。

相关问题

为什么调用 Float64Histogram 会 panic？ 通常是因为 Value 的 Kind 不是 KindFloat64Histogram。先检查 Kind，再调用对应的读取方法。

Counts 为什么比 Buckets 少一个？ Buckets 存的是边界，N 个边界只能围出 N-1 个相邻区间，因此 Counts 有 N-1 个元素。

空 Counts 是否说明指标名称错误？ 不一定。名称错误更应看 KindBad；合法直方图的计数全为零时，只表示当前没有观测样本。

可以把 Buckets 复制后重新分桶吗？ 可以在复制后做自己的展示或转换，但不能把修改后的边界再当作运行时原始直方图的语义依据。

对我来说，最稳妥的做法是把直方图当成“边界数组 + 区间计数数组”处理：先守住 Kind 和长度关系，再谈空样本、累计差分和报表格式。只要不把边界和计数误认成同长度字段，runtime/metrics 的这部分 API 就不会显得神秘。