Go runtime/metrics Sample 怎样批量读取 metric 值

批量读取 runtime/metrics 时，先建立 []metrics.Sample 并为每项设置完整 Name，再调用一次 metrics.Read(samples) 就地填充 Value。消费数据时按 Value.Kind() 分派到对应访问器，未知指标按 KindBad 处理；不能把所有值都当作 uint64，也不能把重复读取同一切片当成独立历史快照。

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

能力一句话：把多个指标放进同一采样容器

runtime/metrics 提供按字符串键访问运行时指标的接口。这里讨论的是现有能力的使用方式，不把它包装成本轮新发布功能。与逐个维护不同统计入口相比，Sample 将请求名称和读取结果放在同一元素里，适合一次采集一组所需指标。

Sample 中 Name 是请求，Value 是 Read 写入的结果；创建切片不等于已经采样。指标键包含路径和单位，例如 /gc/heap/allocs:bytes，冒号后的单位也是键的一部分。

为什么采用键与类型：数量和表示形式可以不同

运行时支持的指标集合可通过 metrics.All() 获取。每个 Description 提供 Name、Kind、Description 和 Cumulative 等信息，适合启动时建立支持目录，再选择采集范围。接口稳定不代表所有 Go 实现和版本都支持完全相同的名称集合。

某个键的类型是其契约的一部分；访问器与实际类型不匹配会 panic。类型检查应写在采集器里，不要依赖“以前这个键一直是整数”的口头约定。

对旧采集代码的影响：重点检查结果所有权

迁移现有采集器时，不需要机械删除原有 runtime 统计调用。先为每个业务展示项找到等价指标定义，确认单位、累计属性和统计范围，再决定是否替换。名称相近并不足以证明两个值可直接互换。

还要检查老代码是否把本次结果交给异步线程后立刻复用容器。Read 可以复用切片和直方图底层存储；在 Read 正在操作某份值时，另一协程读取或修改同份值会造成数据竞争。两个切片变量若共享底层数组，也不能作为互相独立的采样容器。

迁移建议：先实现一个完整的批量读取例子

下面使用三项指标展示整数与直方图分支，同时保留浮点和不支持分支。它是可保存为 main.go 的独立示例，本文未在本机执行，不提供固定输出数值。

package main

import (
    "fmt"
    "runtime/metrics"
)

func main() {
    // 选择明确的指标键；未知键由 KindBad 分支处理。
    samples := []metrics.Sample{
        {Name: "/sched/goroutines:goroutines"},
        {Name: "/gc/heap/allocs:bytes"},
        {Name: "/sched/latencies:seconds"},
    }
    metrics.Read(samples) // 就地填充每个元素的 Value，没有返回值。
    for _, sample := range samples {
        switch sample.Value.Kind() {
        case metrics.KindUint64:
            fmt.Printf("%s = %d\n", sample.Name, sample.Value.Uint64())
        case metrics.KindFloat64:
            fmt.Printf("%s = %g\n", sample.Name, sample.Value.Float64())
        case metrics.KindFloat64Histogram:
            histogram := sample.Value.Float64Histogram()
            // 这里只展示桶结构；不把桶计数误当成耗时数值。
            fmt.Printf("%s: counts=%v, buckets=%v\n",
                sample.Name, histogram.Counts, histogram.Buckets)
        case metrics.KindBad:
            fmt.Printf("%s: 当前运行时不支持\n", sample.Name)
        default:
            fmt.Printf("%s: 未处理的类型\n", sample.Name)
        }
    }
}

遍历时把 sample 复制到局部变量适合本例的同步消费；它并没有深拷贝直方图。若要把历史直方图放入队列，必须在下一次复用前复制 Counts 和 Buckets 的内容，并同步好读写边界。只 append 一份 Sample 切片仍可能保留内部共享。

固定指标列表适合有明确采集契约的应用；通用采集器更适合根据 All 建立列表并按 Kind 处理。不要为了“全量”而无条件把每个指标导出到每个业务面板。

最小使用确认：检查类型，而不是预设数值

将示例接入项目后，先确认每个目标名称能得到预期类型，KindBad 能被记录为不支持，直方图的 Counts 与 Buckets 能按其结构解释。通常桶边界数量比桶计数多一项；第 i 个计数对应相邻边界围成的区间，不能把 Counts 当成秒数。

本文不将一次 Read 宣称为所有指标在完全相同瞬间的事务快照。周期采集还应由调用者记录采样时间。累计指标计算速率需要相邻样本与时间差；当前量则不应随意做相同处理。

• 初始化时设置 Name，后续同步复用切片。
• 每轮 Read 后按 Kind 读取，先处理无效类型。
• 同步消费结束后再复用；异步交付前复制需要保留的数据。
• 采样间隔与范围由实际监控需要确定，不承诺批量读取零开销。

Read 返回什么错误？

它没有 error 返回值。名称不支持时检查对应 Value 的 KindBad，程序不要在这种值上调用具体数值访问器。

能每个协程共享一份 Sample 数组吗？

不要在未同步的情况下共享。并行 Read 的参数需要不共享底层内存；指针型结果也要考虑共享存储。

复制 Sample 就能永久保存历史值吗？

标量与直方图应区别处理。直方图内部数据可能被后续读取复用，历史记录需深拷贝相关数组。

参考：接口与指标定义 https://pkg.go.dev/runtime/metrics；Read 与复用约定 https://go.dev/src/runtime/metrics/sample.go；访问器类型约束 https://go.dev/src/runtime/metrics/value.go。