Go runtime/metrics 的 runnable goroutine 指标与运行队列诊断

排查 Go 服务“goroutine 很多但吞吐没有上去”时，不能只看 runtime.NumGoroutine()。更有用的做法是用 runtime/metrics 连续读取 /sched/goroutines/runnable:goroutines：它表示已经准备运行、但当前还没执行的 goroutine 近似数量；再和 live、running、waiting 等指标及业务延迟放在同一时间窗口比较。runnable 长时间偏高且 running 接近 GOMAXPROCS，才值得把问题收敛到调度压力；单次采样不能直接证明存在 goroutine 泄漏。

官方资料：https://pkg.go.dev/runtime/metrics

先分清 live、runnable 与 running

/sched/goroutines:goroutines 表示当前存活的 goroutine 数量。/sched/goroutines/runnable:goroutines 表示准备执行、但尚未执行的近似数量；/sched/goroutines/running:goroutines 表示正在执行的近似数量，它不会大于 /sched/gomaxprocs:threads。waiting 则是等待 I/O 或同步原语等资源的近似数量。

这些分类并不能简单相加。官方文档明确提醒，多个 goroutine 指标不保证加总后等于 live 总量，所以表格里的“差值”只能帮助观察方向，不能当作精确状态转移图。

用 runtime/metrics 按名称读取指标

runtime/metrics 的指标由“路径:单位”组成。推荐先用名称建立采样表，再检查 Value.Kind()；这样当某个指标在目标 Go 实现中不存在时，可以记录为 unavailable，而不是让监控协程 panic。

package main

import (
    "fmt"
    "runtime/metrics"
)

func readUint(name string) (uint64, bool) {
    samples := []metrics.Sample{{Name: name}}
    // Read 会把当前采样写回同一个 Sample，便于复用切片。
    metrics.Read(samples)
    // 只对明确的 uint64 指标取值，避免误读其他 ValueKind。
    if samples[0].Value.Kind() != metrics.KindUint64 {
        return 0, false
    }
    return samples[0].Value.Uint64(), true
}

func main() {
    names := []string{
        "/sched/goroutines:goroutines",
        "/sched/goroutines/runnable:goroutines",
        "/sched/goroutines/running:goroutines",
        "/sched/goroutines/waiting:goroutines",
    }
    for _, name := range names {
        value, ok := readUint(name)
        // 未支持的指标只报告缺失，不中断整轮采集。
        if !ok {
            fmt.Println(name, "unavailable")
            continue
        }
        fmt.Println(name, value)
    }
}

生产采集器可以先遍历 metrics.All() 建立支持列表，再决定要读哪些名称。官方接口允许实现提供的指标集合随运行时演进，因此把“支持性检查”和“读取逻辑”分开，比假设所有版本都有同一组名称更稳妥。

连续采样才有资格判断运行队列压力

把四个指标按固定间隔记录下来，并同时记录请求延迟、吞吐和错误率。若 runnable 只在批量任务开始时短暂升高，通常只是瞬时排队；若它在多个窗口持续偏高，且 running 接近 /sched/gomaxprocs:threads，同时业务延迟上升，才可以把“调度供给不足或任务并行度过高”列为优先假设。

不要把 runnable 当成“CPU 使用率”，也不要用它单独决定增大并发数。指标是近似的，采样时间点也会改变结果；至少要看一个完整业务周期，并保留异常前后的连续序列。

近似指标之后还要查什么

runtime/metrics 适合做低成本的趋势信号。它提示“有很多 goroutine 在等执行”，但不会告诉你是哪段代码产生工作、哪个锁造成等待，或哪个系统调用拖慢了线程。需要定位时，再按现象选择执行追踪、goroutine 栈、锁分析或 CPU profile；不要把采样图中的一个高点写成根因。

常见问题

runnable 数量高就是 goroutine 泄漏吗？

不是。泄漏更常见的信号是 live 数量持续增长且长期不回落；runnable 高更接近“工作等待执行”，仍要结合生命周期和业务流量判断。

为什么 runnable、running、waiting 加起来不一定等于 live？

这些运行时分类是近似指标，官方没有承诺它们可以构成互斥且完备的分区，因此只能作趋势观察。

什么时候应该改用 go tool trace？

当队列压力与延迟上升同时出现，并且需要知道调度、系统调用、GC 或并行化在哪个阶段受阻时，trace 比单个计数器更适合继续定位。

实际排查可以记住一句话：先用 runnable 发现“可能排队”，再用连续样本和业务指标确认“是否持续”，最后用 trace、栈或 profile 找到“谁造成排队”。这样不会把一个近似计数器误当成完整诊断结论。