Go runtime/metrics 如何读取调度器指标而不依赖 pprof

线上 Go 服务出现请求排队时，先知道“有多少 goroutine 在等”和“它们等了多久”，通常比立即抓一份 pprof 更适合做持续监控。runtime/metrics 提供了一个标准运行时指标入口：用字符串名称选择指标，用 metrics.Read 读取当前值，不需要启动 HTTP 调试端点。

runtime/metrics 适合回答哪些调度问题

这个包解决的是“运行时现在暴露了哪些可观测量”，而不是“哪一行代码占用了调用栈”。例如，/sched/goroutines:goroutines 表示存活 goroutine 数，/sched/goroutines/runnable:goroutines 表示已经可以运行但尚未执行的数量，/sched/gomaxprocs:threads 表示当前可同时执行用户级 Go 代码的处理器上限。

如果关注的是调度等待，应该再看 /sched/latencies:seconds。它是一个分布，描述 goroutine 处于 runnable 状态后到真正运行之间的等待时间。它不是平均值字段，不能直接当成一个普通浮点数相加。

用 All 和 Read 建立可兼容的采样入口

最稳妥的入口是先调用 metrics.All，从返回的描述中挑出本次需要的名称，再把名称写入 []metrics.Sample，最后交给 metrics.Read。生产代码可以复用这段切片，避免每个采样周期重新分配。

package main

import (
    "fmt"
    "runtime/metrics"
)

func main() {
    // 只从当前 Go 实现支持的描述中选择需要的指标。
    wanted := map[string]bool{
        "/sched/goroutines:goroutines":         true,
        "/sched/goroutines/runnable:goroutines": true,
        "/sched/gomaxprocs:threads":             true,
        "/sched/latencies:seconds":              true,
    }
    var samples []metrics.Sample
    for _, desc := range metrics.All() {
        // All 返回的名称是兼容性边界，未知名称不会被硬编码进样本。
        if wanted[desc.Name] {
            samples = append(samples, metrics.Sample{Name: desc.Name})
        }
    }
    metrics.Read(samples)
    for _, sample := range samples {
        fmt.Printf("%s: %v\n", sample.Name, sample.Value.Kind())
    }
}

这里没有把“找不到某个名称”当成程序错误。官方文档允许指标集合随运行时演进，也允许不同 Go 实现提供不同集合；如果业务强依赖某个指标，应把兼容策略放在构建或部署层，而不是悄悄把空值当成零。

调度器指标的值类型和直方图怎么处理

Sample.Value 不是一个可以直接打印成数字的字段。先用 Kind() 判断，再调用对应的取值方法。计数型调度指标通常是 KindUint64；调度等待延迟是 KindFloat64Histogram，其 Counts 与 Buckets 描述各区间的样本分布。

func printSchedulerSample(sample metrics.Sample) {
    // 先判断类型，避免对错误的 Value 调用 Uint64 或 Float64Histogram。
    switch sample.Value.Kind() {
    case metrics.KindUint64:
        fmt.Printf("%s = %d\n", sample.Name, sample.Value.Uint64())
    case metrics.KindFloat64Histogram:
        h := sample.Value.Float64Histogram()
        // 只输出桶数量，完整桶边界应交给监控系统保存或聚合。
        fmt.Printf("%s: %d buckets\n", sample.Name, len(h.Counts))
    case metrics.KindBad:
        // 名称不在 All 中时不要把未知值当成有效的零值。
        fmt.Printf("%s: unsupported\n", sample.Name)
    default:
        // 新增类型暂不解析，但保留指标名便于后续升级处理。
        fmt.Printf("%s: unhandled kind %v\n", sample.Name, sample.Value.Kind())
    }
}

读取直方图时要注意生命周期：Read 可能复用底层存储，因此不要把指针直接交给异步消费者。如果采样值要跨 goroutine 或跨下一次 Read 使用，应复制 Counts 和 Buckets；只在当前函数内立即读取则不必为了“保险”复制所有数据。

和 pprof 怎么分工，生产采样要注意什么

可以把两者看成不同层级的接口：runtime/metrics 适合按固定周期输出少量运行时指标，做趋势、阈值和容量判断；pprof 适合在异常窗口内回答“哪个函数阻塞、哪条调用链消耗 CPU 或内存”。指标采集不依赖 pprof，但深度定位仍然可以在需要时使用 pprof。

采样器本身也要有边界：固定周期复用样本切片，避免每秒扫描全部指标；记录指标名称与单位，避免把 :seconds 当成毫秒；当 Go 版本升级后重新检查 All 的结果。这样既能保持低侵入的运行时观测，又不会把监控 API 误当成完整性能剖析器。

常见问题：runtime/metrics 读取调度器指标

为什么读取 runnable 数量后不能推导所有 goroutine 状态？

官方定义中的多个 goroutine 分类是近似值，并不保证与总数严格相加。它们适合观察趋势和异常变化，不适合做精确账本。

可以直接把 /sched/latencies:seconds 转成一个数字吗？

不建议。它是浮点直方图，应根据桶边界和计数计算分位趋势，或交给支持 histogram 的监控后端。

为什么不直接硬编码指标名？

硬编码并非绝对禁止，但官方更鼓励从 All 发现当前支持集合。硬编码时至少要处理指标缺失，并把它视为兼容性决策。