flight recorder 缓冲区太小会丢掉哪些事件

Go 的 flight recorder 缓冲区太小时，并不会“优先丢 GC 事件”或“只丢用户标注”。它维护的是最近一段执行追踪数据，并按完整的 trace generation 保留或淘汰：当 MaxBytes 压力先到来时，较老 generation 中的 goroutine 调度、阻塞与唤醒、系统调用、GC、堆变化、处理器状态、用户日志与 region、CPU 样本都可能一起离开窗口。

因此，真正损失的是较早的时间上下文。快照仍然可以是可读取的 trace，但慢请求的起点、锁竞争的诱因或触发前的 GC 活动可能已经不在了。官方文档还明确说明 MaxBytes 优先于 MinAge，且它只是提示值，不保证快照文件、运行时额外内存严格小于该值。

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

一、缓冲区小，不是按事件类型降采样

我第一次看见一个很短的 flight recorder 快照时，也以为运行时为了省空间，先把“次要事件”过滤掉了。对照 Go 的实现后才发现，这个理解不对：记录器接收运行时 trace 的完整批次，把批次归入 generation，再维护一个由多个完整 generation 组成的窗口。容量不足时，旧 generation 不再进入新窗口；最新的完整 generation 则会保留。

这也解释了一个常见现象：触发告警的那个瞬间还在，但导致告警的早期链路不见了。不是某类事件被针对性丢弃，而是它们所在的旧 generation 已经超出保留窗口。

二、MaxBytes 会覆盖 MinAge，但两者都不是硬切线

MinAge 表示记录器希望可靠保留的最小事件年龄。官方博客建议把它设成目标故障窗口的大约两倍，例如排查 5 秒超时，可先设为 10 秒。MaxBytes 是窗口大小的上界提示，并且优先级更高：如果在达到 MinAge 前就触及容量压力，旧 generation 仍会被淘汰。

这里有三个不能忽略的边界：

• 最新完整 generation 始终会被保留，所以单个 generation 很大时，窗口可能越过配置阈值。
• MaxBytes 不保证 WriteTo 写出的字节数严格小于它，也不保证记录器全部内存开销严格受它约束。
• 较老 generation 可能跨过阈值而被保留，因此时间和容量边界都不是按单个事件精确裁切。

换句话说，MaxBytes 适合做资源预算的控制信号，不适合当成精确文件大小合同。

三、最容易丢的是“触发前因”，不是触发点本身

假设服务在请求超过 2 秒时调用 WriteTo。如果缓冲区只够保存最近约 700 毫秒，快照通常还能看到请求超时附近的调度状态，却可能看不到 1.5 秒前持锁的 goroutine、早期系统调用阻塞、GC 周期开始或业务 Task 创建。对于长事务，开始标注与结束标注还可能分处不同 generation，最后只剩半段上下文。

这类快照并不等于损坏。Flight recorder 以完整 generation 维护窗口，目的之一就是让导出的数据仍能被追踪工具处理；问题只是诊断视野过窄。遇到以下迹象时，应优先怀疑容量不足：

• 快照最早时间明显晚于故障操作的起点；
• 能看到 goroutine 被唤醒，却找不到对应的更早阻塞背景；
• 业务 region 只剩后半段，或关键 trace.Log 不在快照内；
• 低流量环境能还原原因，高流量生产环境却只保留触发附近片段。

四、按故障窗口和峰值 trace 速率配置

官方博客给出的经验是：一般程序每秒可能产生数 MB trace，繁忙服务可能达到约 10 MB/s。这个数字只适合做起点，最终应以自己的高峰流量测量。一个实用估算是：

MaxBytes ≈ 峰值 trace 字节率 × MinAge × 1.3～2.0 余量

如果目标是分析 5 秒超时，可先把 MinAge 设为 10 秒，再根据峰值 trace 产出决定容量。若峰值约 6 MB/s，10 秒窗口至少需要约 60 MB，生产上还要给 generation 跨界和流量抖动留余量。

package diagnostics

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

func StartRecorder() (*trace.FlightRecorder, error) {
    fr := trace.NewFlightRecorder(trace.FlightRecorderConfig{
        // 目标故障窗口约 5 秒，因此先按两倍时间保留上下文。
        MinAge: 10 * time.Second,
        // 容量必须覆盖峰值 trace 产出；这里用 96 MiB 作为起始值。
        MaxBytes: 96 

不要只在空闲环境估算。goroutine 数量、锁竞争、系统调用、GC 频率和用户标注都会影响 trace 产出；同一个 MaxBytes 在压测和生产高峰中对应的可见时长可能差很多。

五、串行写出快照，并记录可见范围

WriteTo 会取得当前移动窗口的快照，但同一时刻只允许一个 goroutine 执行。并发调用会返回错误，因此告警风暴下要做串行化或去重。写出后记录实际字节数、触发原因和时间，再用 go tool trace 检查最早可见事件是否早于目标操作起点。

package diagnostics

import (
    "fmt"
    "os"
    "runtime/trace"
    "sync"
)

type Snapshotter struct {
    mu sync.Mutex // 串行化 WriteTo，避免多个告警同时导出。
    fr *trace.FlightRecorder
}

func (s *Snapshotter) Save(path string) (int64, error) {
    s.mu.Lock()
    defer s.mu.Unlock()

    if !s.fr.Enabled() {
        return 0, fmt.Errorf("flight recorder is not active")
    }
    f, err := os.Create(path)
    if err != nil {
        return 0, fmt.Errorf("create trace snapshot: %w", err)
    }
    defer f.Close() // 即使 WriteTo 失败也释放文件描述符。

    n, err := s.fr.WriteTo(f)
    if err != nil {
        return n, fmt.Errorf("write trace snapshot: %w", err)
    }
    return n, nil
}

# 在受控环境打开快照，核对触发点之前是否覆盖完整目标窗口。
go tool trace snapshot.trace

如果最早可见时间晚于目标操作起点，先增加 MaxBytes；如果窗口明显长于需要，再逐步回收容量。每次只改一个参数，并在相同流量级别下比较实际快照覆盖范围，避免把低峰结果外推到高峰。

快速检查清单

• 确认运行版本支持 trace.NewFlightRecorder，该 API 从 Go 1.25 加入。
• MinAge 至少覆盖故障窗口，通常可从约两倍窗口开始。
• MaxBytes 按峰值 trace 速率估算，而不是按平均流量估算。
• 不要期待容量不足时保留某个事件类别；旧 generation 中所有类别都可能消失。
• 为 WriteTo 做串行化，并记录输出字节数、触发原因和快照时间。
• 用最早可见时间核对上下文，而不是只看快照能否打开。

相关问题

MaxBytes 越小，快照一定越小吗？

不一定。官方文档将它定义为提示性的窗口上界，不保证 WriteTo 输出和全部内存开销严格低于该值。

MinAge 设置了 10 秒，就一定能保留 10 秒吗？

不一定。MaxBytes 优先；如果容量先被高流量 trace 用完，时间目标会被覆盖。

缓冲区太小会让 trace 文件损坏吗？

正常淘汰旧 generation 不等于文件损坏。导出的 trace 仍应可处理，但较早的因果上下文可能不存在。

能并发保存多个快照吗？

同一个 flight recorder 同时只允许一个 WriteTo。另一个并发调用会报错，应在业务层串行化或复用正在生成的结果。