Java JFR 事件流定位短时延迟尖峰

Java 服务的短时延迟尖峰，最怕只看平均值：一次 300 毫秒的抖动可能来自锁等待、GC、线程调度，也可能是外部 I/O 恰好变慢。更稳妥的做法是让 JFR 事件流只观察与尖峰相关的事件，把事件时间、持续时间、线程和堆栈放到同一条证据链里，再决定修复方向。

官方资料：https://docs.oracle.com/en/java/javase/26/docs/api/jdk.jfr/jdk/jfr/consumer/RecordingStream.html

定位重点不是“打开 JFR 后看所有事件”，而是先圈定延迟窗口，再用少量高价值事件解释窗口内发生了什么。

本文要点：按事件名缩小范围；给流设置周期与保留上限；把尖峰时间和线程/堆栈关联；结束时安全停止并按需导出。

先把尖峰变成可对照的时间窗口

先记录接口或任务的尖峰时间段，例如 14:05:10.200—14:05:10.800，并明确延迟指标来自哪里。若只看到应用耗时，优先关注执行样本、线程停顿、锁竞争和 GC 暂停；若还伴随外部依赖变慢，再加入 Socket 或文件相关事件。JFR 的事件时间线是线索，不等于业务请求的完整 trace，所以要把请求日志中的时间戳作为关联锚点。

用 RecordingStream 只订阅高价值事件

RecordingStream 可以从当前 JVM 产生事件流。下面示例用执行样本和 GC 事件做最小观察，并给流设置最大年龄；真实项目应按 JDK 版本和目标事件的字段定义调整。

import jdk.jfr.consumer.RecordingStream;
import java.time.Duration;

try (var stream = new RecordingStream()) {
    // 只打开与延迟尖峰有关的事件，避免把所有事件都送进回调。
    stream.enable("jdk.ExecutionSample").withPeriod(Duration.ofMillis(20));
    stream.enable("jdk.GarbageCollection");
    // 限制磁盘仓库中的保留时间，防止长时间运行无界增长。
    stream.setMaxAge(Duration.ofMinutes(2));
    stream.onEvent("jdk.ExecutionSample", event -> {
        // 这里只做轻量聚合；不要在回调里执行阻塞 I/O。
        var thread = event.getThread();
        if (thread != null) {
            System.out.println(thread.getJavaName());
        }
    });
    // 异步消费后由外部生命周期控制停止时机。
    stream.startAsync();
    stream.awaitTermination(Duration.ofSeconds(30));
}

这里的周期只对支持周期设置的事件有意义；没有周期的事件通常依赖其触发条件。回调应尽量轻量，必要时只把计数、时间窗口和关键标识送入有界队列，避免诊断逻辑反过来制造新的延迟。

把事件字段整理成根因证据

单条事件不能直接证明根因。可以按尖峰窗口聚合：执行样本看堆栈顶部是否集中在同一段代码；锁相关事件看等待时长和持有线程；GC 事件看暂停区间是否覆盖尖峰；I/O 事件则与依赖请求日志按时间和线程交叉核对。

结束流并保留可复盘材料

长时间观察必须有结束策略。短测试可用 awaitTermination(Duration) 到时返回；需要完整消费已到达事件时使用 stop()，但不要在事件回调内部调用它，以免等待自身造成阻塞。若要后续用 JMC 或 jfr 命令复盘，应在流启动后设置最大年龄或最大大小，再调用 dump(Path) 导出。

try (var stream = new RecordingStream()) {
    // 设置上限后再开始，给导出保留一个明确的时间边界。
    stream.setMaxAge(Duration.ofMinutes(2));
    stream.startAsync();
    observeRequestWindow();
    // 在控制线程停止，等待已经进入流的事件处理完毕。
    stream.stop();
    stream.dump(java.nio.file.Path.of("latency-spike.jfr"));
} catch (java.io.IOException e) {
    // 导出失败要记录路径和权限信息，但不要掩盖原始延迟证据。
    throw new IllegalStateException("JFR dump failed", e);
}

复查时至少保存尖峰窗口、JDK/JVM 参数、启用的事件和文件保留策略。这样下一次复现可以区分“没有采到事件”和“事件显示没有对应根因”，而不是凭一条日志下结论。

常见边界与复查清单

• 只订阅少量事件，并为流设置 setMaxAge 或 setMaxSize；未设置上限时记录可能持续增长。
• 事件流里的时间点用于关联，不替代业务 trace；跨线程或异步任务要补充请求 ID、线程名和日志时间。
• 事件回调不做网络请求、重型序列化或无限队列写入；否则诊断器会改变被观察系统。
• 结束后核对 stop/dump 是否完成，并把事件配置和观察窗口一同归档。

相关问题

RecordingStream 和读取 .jfr 文件有什么区别？前者消费当前 JVM 的流，适合在线观察；后者读取已经落盘的录制，适合离线复盘。

为什么事件流看不到业务方法名？执行样本是否带堆栈、事件是否启用以及采样时刻都会影响结果，应检查事件设置和关联窗口，而不是只看事件数量。