Go runtime/metrics 怎样区分自动 GC 与手动 GC 次数

如果只看一个“GC 次数”，很难回答“是运行时自己回收，还是代码主动触发了回收”。Go 的 runtime/metrics 已经把这件事拆成三条累计指标：/gc/cycles/automatic:gc-cycles、/gc/cycles/forced:gc-cycles 和 /gc/cycles/total:gc-cycles。其中 automatic 表示运行时自动完成的周期，forced 表示应用主动触发的周期，total 表示全部已完成周期。

排查时不要比较累计值本身，而要保存两次采样的差值：如果一段时间内 forced 增长，优先检查是否调用了 runtime.GC() 或封装它的管理代码；如果 automatic 增长而 forced 不变，说明这段时间主要是运行时自动回收。

先区分三条 GC 周期指标

这三条指标都是累计计数，不是当前瞬时状态。可以把它们看成一张静态账本：

• automatic：Go 运行时自动生成并完成的 GC 周期数。
• forced：由应用主动要求完成的 GC 周期数。
• total：全部已完成的 GC 周期数，通常可用来和前两者的增量互相核对。

这里的“手动 GC”更准确地说是“应用主动触发的 GC”。不要把它理解成每次调用都立刻产生一个可见的独立结果；诊断代码应该观察计数在采样窗口内的变化。

用 metrics.Read 读取计数

metrics.Read 会把样本切片中的名称对应值填入。GC 周期计数的值类型是无符号整数，读取前用名称建立固定索引，后续采样只更新值，避免把名称判断散落在业务代码里。

package main

import (
    "fmt"
    "runtime/metrics"
)

const (
    metricAutomatic = "/gc/cycles/automatic:gc-cycles"
    metricForced    = "/gc/cycles/forced:gc-cycles"
    metricTotal     = "/gc/cycles/total:gc-cycles"
)

func readGCCycles() (automatic, forced, total uint64) {
    // 固定三条指标名称；它们都是累计完成的 GC 周期数。
    samples := []metrics.Sample{
        {Name: metricAutomatic},
        {Name: metricForced},
        {Name: metricTotal},
    }
    // Read 只负责把当前值写回 Sample，业务层再读取 Uint64。
    metrics.Read(samples)
    // 这些指标的 Value 类型是 uint64，取值前保持名称顺序一致。
    return samples[0].Value.Uint64(), samples[1].Value.Uint64(), samples[2].Value.Uint64()
}

func main() {
    automatic, forced, total := readGCCycles()
    // 输出累计值；不要把累计值直接当作本次请求产生的 GC 次数。
    fmt.Printf("automatic=%d forced=%d total=%d\\n", automatic, forced, total)
}

示例把三个名称放在固定顺序的切片里，适合小型采集器。若指标集合由配置决定，则应按名称查找并先确认 Value.Kind() 是否为 metrics.KindUint64，避免把不存在或类型不符的样本当成有效计数。

用采样增量定位触发来源

真正有诊断价值的是窗口差值。设上一次采样为 (a1, f1, t1)，本次为 (a2, f2, t2)，分别计算 da=a2-a1、df=f2-f1、dt=t2-t1：

这张表是排查优先级，不是性能结论。GC 周期数只能说明回收事件的计数来源，不能单独证明发生了内存泄漏、暂停变长或服务变慢。

处理路径、回滚与复盘

1. 先保留 automatic、forced、total 三个原始累计值和采样时间，不只记录计算后的比例。
2. 发现 forced 持续增长时，优先回到应用代码、定时任务和运维接口，确认主动触发是否有明确目的。
3. 如果主动触发来自新改动，先关闭对应开关或恢复旧调用路径，再观察后续采样窗口；不要为了“让次数下降”直接修改运行时限制。
4. 复盘时记录触发方、采样间隔、三项增量和请求流量，把 GC 计数与暂停时间、堆指标分开解释。

最常见的误区有三个：把 forced 当成“手动执行成功次数”的精确业务审计；把累计值当成单次请求值；以及看到 automatic 增长就直接认定代码泄漏。它们都需要更多上下文才能成立。

相关问题

为什么不直接使用 runtime.ReadMemStats？ ReadMemStats 更适合读取堆分配和 GC 统计快照，而 runtime/metrics 可以按稳定的字符串名称读取更细分的运行时指标；本文只需要 GC 周期来源拆分，所以选后者。

total 一定等于 automatic 加 forced 吗？ 三者描述的是同一类已完成 GC 周期的不同统计视角，排查时可用增量关系做一致性核对；若不一致，先检查采样进程、窗口和读取逻辑，不要立即改代码。