Go debug.ReadGCStats 怎么读取 GC 暂停历史并避免复用切片陷阱

如果 Go 服务需要周期性记录 GC 暂停，runtime/debug.ReadGCStats 足够做轻量采样，但不能把返回的 Pause 直接当成永久历史。官方文档明确说明：暂停条目数由系统决定，Pause 在容量足够时会被复用，而且下一次读取可能使用它的全部容量。

先分清 GCStats 里哪些数据会变化

GCStats 同时包含累计值、最近一次信息和有限的历史窗口。NumGC 是累计回收次数，PauseTotal 是累计暂停时间，LastGC 是最近一次回收时间；Pause 和 PauseEnd 则是最近暂停及其结束时间，且都按最近记录优先。

最容易踩坑的是切片所有权。复用 stats 本身通常没有问题，问题在于把 stats.Pause 的切片头直接放入历史队列：下一次 ReadGCStats 可能复用同一数组，旧快照就会悄悄改变。即使本次只看到 len(Pause) 个元素，也不要假设容量之外的区域不会被运行时写入。

读取后立即复制，形成可异步使用的采样快照

推荐把一个 GCStats 作为采样工作区，把需要跨越本次函数调用保存的字段复制到自己的结构体中。下面的复制不是为了制造“更多历史”，而是为了切断下一次读取对底层数组的影响。

package main

import (
    "fmt"
    "runtime/debug"
    "time"
)

type GCSnapshot struct {
    SampledAt time.Time
    LastGC    time.Time
    NumGC     int64
    Pause     []time.Duration
    PauseEnd  []time.Time
}

func readSnapshot(work *debug.GCStats) GCSnapshot {
    debug.ReadGCStats(work) // 先写入可复用的采样工作区

    return GCSnapshot{
        SampledAt: time.Now(),
        LastGC:    work.LastGC,
        NumGC:     work.NumGC,
        // 复制底层数组，避免下一次读取改写已保存的快照。
        Pause:    append([]time.Duration(nil), work.Pause...),
        PauseEnd: append([]time.Time(nil), work.PauseEnd...),
    }
}

func main() {
    var work debug.GCStats
    snapshot := readSnapshot(&work)
    fmt.Printf("gc=%d pauses=%d last=%s\\n", snapshot.NumGC, len(snapshot.Pause), snapshot.LastGC.Format(time.RFC3339))
}

这里的 append([]T(nil), source...) 会创建与源切片无关的新底层数组。若需要复用自己的快照缓冲区，也可以使用 dst = append(dst[:0], source...)，但要确认 dst 不会同时被别的 goroutine 读取。生产代码里通常把复制动作和发送动作放在同一采样协程中，再把只读快照交给下游。

用 PauseQuantiles 做固定长度的延迟摘要

如果监控端只需要摘要，不必每次上传整段暂停历史。调用前给 PauseQuantiles 预置长度，ReadGCStats 会把结果写入这个切片。长度为 5 时，官方定义对应最小值、25%、50%、75% 和最大值。

func readLatencySummary(work *debug.GCStats) [5]time.Duration {
    // 固定五个槽位，分别承载 min、p25、p50、p75、max。
    work.PauseQuantiles = make([]time.Duration, 5)
    debug.ReadGCStats(work) // 同一次读取同时刷新 Pause 和分位数

    var result [5]time.Duration
    copy(result[:], work.PauseQuantiles) // 复制到值数组，脱离工作区生命周期
    return result
}

分位数适合做面板摘要，但它不是暂停样本的完整列表，也不能反推出每一次 GC 的时间点。若要解释某个尖峰，仍需保存复制后的 Pause 与 PauseEnd，并结合采样时的 NumGC 判断窗口是否发生了变化。

采样方案的边界与排查清单

这套写法解决的是“周期性读取并安全保存 GC 摘要”。它不保证 Pause 覆盖进程从启动以来的所有回收，也不提供完整的分配调用链。遇到数据异常时，可以按下面顺序检查：

• 是否把 Pause 或 PauseEnd 的切片头直接交给了异步队列？如果是，先在采样点复制。
• 是否把 len(PauseQuantiles) 当成样本数量？它只是你请求的摘要槽位数。
• 是否需要持续剖析而不是轻量摘要？那就换用更适合长期分析的运行时观测工具，不要靠扩大切片容量“保存全部历史”。

相关问题

ReadGCStats 会返回完整 GC 暂停历史吗？

不会。暂停历史条目数由系统决定，Pause 是有限窗口，而且最近记录在前。

只读 stats.Pause 的当前内容也需要复制吗？

如果只在下一次读取前同步消费，可以不复制；一旦要缓存、异步发送或跨函数长期保存，就应复制。

PauseQuantiles 长度应该固定为 5 吗？

不一定。长度由你的监控需求决定；长度为 5 时语义清晰，正好覆盖最小值、四分位点和最大值。