Go runtime/metrics 怎么按指标描述选择正确的 Value 类型

我第一次把 runtime/metrics 接到周期采集代码里时，最容易犯的错是把所有 Value 都当成 uint64。真正稳定的做法是先看 metrics.All() 返回的 Description.Kind：KindUint64 调用 Uint64()，KindFloat64 调用 Float64()，KindFloat64Histogram 调用 Float64Histogram()。不匹配时，访问方法会 panic。

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

我为什么先从 Description 看类型

runtime/metrics 的指标不是结构体字段，而是带单位的字符串名称，例如 /memory/classes/heap/free:bytes。官方接口把这些名称和说明集中放在 metrics.All() 返回的 []metrics.Description 中。对我来说，这个设计的变化在于：读取值之前，先用描述建立“指标名称—值类型”的关系，采集代码就不会依赖猜测。

Description.Name 是完整指标名，Description.Description 是文字说明，Description.Kind 是值的类型标签，Description.Cumulative 则表示单值或分布是否单调累积。后一个字段影响速率计算的判断，但不决定调用哪个 Value 方法。

Description.Kind 决定 Value 应该怎么读

最小判断表可以直接写进采集器的设计文档。KindUint64 对应无符号整数，KindFloat64 对应浮点数，KindFloat64Histogram 对应指向 Float64Histogram 的指针；KindBad 表示没有可用类型，不能继续取值。

package main

import (
    "fmt"
    "runtime/metrics"
)

func printMetric(name string) {
    // 先从官方支持列表中找到描述，避免凭名称猜值类型。
    var desc metrics.Description
    found := false
    for _, item := range metrics.All() {
        if item.Name == name {
            desc, found = item, true
            break
        }
    }
    if !found {
        // 指标不存在时不构造一个看似有效的默认值。
        fmt.Printf("%s: description not found\n", name)
        return
    }

    // Sample.Name 必须对应支持列表中的名称，Read 才能填充 Value。
    samples := []metrics.Sample{{Name: desc.Name}}
    metrics.Read(samples)
    value := samples[0].Value

    // 先处理未知值，再按 Kind 调用唯一匹配的访问方法。
    if value.Kind() == metrics.KindBad {
        fmt.Printf("%s: unsupported metric\n", desc.Name)
        return
    }
    switch desc.Kind {
    case metrics.KindUint64:
        fmt.Printf("%s: %d\n", desc.Name, value.Uint64())
    case metrics.KindFloat64:
        fmt.Printf("%s: %f\n", desc.Name, value.Float64())
    case metrics.KindFloat64Histogram:
        histogram := value.Float64Histogram()
        // 这里只展示桶数量；完整处理还要同时理解 Buckets 和 Counts。
        fmt.Printf("%s: %d buckets\n", desc.Name, len(histogram.Buckets))
    default:
        // 新增 Kind 时先保守跳过，避免把未知布局误当成旧类型。
        fmt.Printf("%s: unsupported kind %v\n", desc.Name, desc.Kind)
    }
}

func main() {
    // 这两个名字只用于演示“按描述选择读取方法”的结构。
    printMetric("/memory/classes/heap/free:bytes")
    printMetric("/sched/latencies:seconds")
}

这里故意同时使用 desc.Kind 和 value.Kind()：前者来自支持列表，适合建立稳定的读取分支；后者来自本次采样结果，适合先挡住 KindBad。如果两者出现意外不一致，应该把它当作采集逻辑需要调查的信号，而不是强行转换。

KindBad 和新增 Kind 是两种不同的边界

我在整理旧采集器时发现，最容易混在一起的是“指标名称不认识”和“类型种类还没支持”。传给 metrics.Read 的名称不在 metrics.All() 中时，返回的 Value.Kind() 会是 KindBad；这通常表示名称拼写、运行时实现或支持范围出了问题。

另一种情况是 Go 未来增加新的 ValueKind。已有指标的 Kind 被保证不会改变，若必须改变会引入新的指标名称和新的 Kind，但代码仍然应该保留 default。这样新增类型不会被错误地塞进 uint64 或 float64 分支。

对固定指标可以依赖文档中保证的 Kind，但仍建议先判断是否为 KindBad；对希望跨 Go 版本工作的采集器，更稳的入口是遍历 metrics.All()，只处理自己理解的类型。

把 Description 与 Sample 组合成稳定读取流程

实际接入时，我会把流程收敛成四个职责：用 All() 得到支持列表；根据指标名称准备 Sample.Name；调用 metrics.Read 填充 Sample.Value；最后按 Kind 读取或跳过。这样名称、类型和结果的边界都在代码里留下了位置。

metrics.Read 可以复用同一片 []metrics.Sample，但要注意：一次 Read 正在使用某个 Value 时，不要并发读取或修改它；直方图这类指针值的底层存储也可能在下一次 Read 时复用。若要跨并发边界保存结果，应先深拷贝需要的数据。

• 只关心数值计数：支持 KindUint64 和 KindFloat64，遇到直方图时记录未处理。
• 需要分布信息：专门处理 Float64Histogram()，同时保存 Buckets 与 Counts 的对应关系。
• 需要跨版本兼容：从 All() 发现指标，给 KindBad 和未知 Kind 留出跳过路径。

常见问题

为什么不能所有指标都调用 Uint64？

因为 Value 可能是浮点数或直方图。官方文档规定，访问方法与 Kind 不匹配时会 panic，必须先判断类型。

Cumulative 能不能用来判断 Value 类型？

不能。它只说明值是否累积，适合用于判断是否计算速率；真正的读取方法由 Kind 决定。

固定指标还需要每次检查 Kind 吗？

可以依赖该指标 Kind 不变的兼容保证，但仍应处理 KindBad 和读取失败边界，尤其是指标名称来自配置时。