Go runtime/metrics Value.Float64Histogram 的分桶读取与统计方法

Go 的 runtime/metrics 直方图不能当成一个普通浮点数读取。正确顺序是：先用 metrics.Read 得到 Sample.Value，检查 Value.Kind() 是否为 metrics.KindFloat64Histogram，再调用 Float64Histogram()。拿到对象后，Buckets 保存递增边界，Counts[i] 对应 [Buckets[i], Buckets[i+1])，因此桶数量比边界少一个。

先判断 Value.Kind，再取出 Float64Histogram

runtime/metrics 支持的指标集合会随运行时实现变化，稳定的做法是从 metrics.All() 找到名称，再把名称放入可复用的 metrics.Sample 切片。对于具体指标，也要保留 KindBad 和类型不匹配的处理分支。

package main

import (
    "fmt"
    "runtime/metrics"
)

func readHistogram(name string) error {
    samples := make([]metrics.Sample, 1)
    samples[0].Name = name // 复用 Sample，只为指定指标准备一个采样槽位
    metrics.Read(samples)

    value := samples[0].Value
    if value.Kind() != metrics.KindFloat64Histogram { // 先验类型，避免错误取值触发 panic
        return fmt.Errorf("%s is not a float64 histogram: %v", name, value.Kind())
    }
    histogram := value.Float64Histogram() // 只有 Kind 匹配时才能调用
    if len(histogram.Buckets) != len(histogram.Counts)+1 { // 防止错误数据导致边界越界
        return fmt.Errorf("invalid histogram shape: buckets=%d counts=%d", len(histogram.Buckets), len(histogram.Counts))
    }

    var total uint64
    for i, count := range histogram.Counts {
        total += count // Counts[i] 对应左闭右开区间 [Buckets[i], Buckets[i+1])
        fmt.Printf("[%g, %g): %d\\n", histogram.Buckets[i], histogram.Buckets[i+1], count)
    }
    fmt.Printf("total samples: %d\\n", total) // 这里只汇总权重，不伪造精确均值
    return nil
}

Buckets 与 Counts 必须错一位配对

直方图的关键不是“每个边界有一个数量”，而是“两个相邻边界定义一个区间”。假设 Buckets 有五个值，就能形成四个桶：第一个桶包含左边界、不包含右边界，依次向右排列。首个边界允许是负无穷，末个边界允许是正无穷，代码不应把它们当成普通业务数值再做格式化假设。

汇总时先区分累计指标与单次快照

把 Counts 相加可以得到当前直方图里的总权重，适合判断分布规模；但这不是原始观测值列表，也不能从桶边界直接还原精确平均值。若指标描述的 Cumulative 为真，连续两次读取的桶计数表示累计变化，可以用差值计算窗口增量；如果只是读取一次，就不要把它解释成某个时间窗口的请求数。

另外，Buckets 的切片可能与其他直方图共享底层数据，读取即可，别在业务代码中原地修改。需要长期保存边界时复制一份；需要长期保存计数时也应复制 Counts，不要把运行时返回的切片当作自己的可变缓存。

常见问题

为什么直接调用 Float64Histogram 会 panic？

因为当前 Value 的类型标签不是 KindFloat64Histogram。先检查 Kind()，并为 KindBad 或未来新增类型保留降级路径。

Buckets 和 Counts 为什么长度不同？

这是正常结构：N 个桶由 N+1 个边界定义，所以应满足 len(Buckets) == len(Counts)+1；零个桶时边界也可能是零长度。

能否用桶中点计算精确平均值？

不能。桶只告诉你样本落在哪个区间，中点只能做近似估计，而且首尾无穷边界无法直接取中点；需要精确均值时应采集独立的总和或原始观测。