Java Flight Recorder 怎样按事件类型导出记录

如果手里已经有一个 recording.jfr，想只导出某一种事件，最直接的做法是用 jdk.jfr.consumer.RecordingFile.write，把 RecordedEvent.getEventType().getName() 作为谓词条件。它会读取原录制并生成一个新的 JFR 文件，原文件不会被原地修改。

官方地址：https://docs.oracle.com/en/java/javase/25/jfapi/flight-recorder-api-programmers-guide.pdf

本文使用的 API 文档：https://docs.oracle.com/en/java/javase/25/docs/api/jdk.jfr/jdk/jfr/consumer/RecordingFile.html

下面的示例围绕“已有录制文件按事件类型导出”展开，不负责启动采集，也不把导出结果描述成已经在某台机器执行过的运行证据。配图是原创静态说明图，用来解释对象关系和选择规则。

先分清事件类型和采集设置

JFR 的事件类型名称例如 jdk.ExecutionSample、jdk.CPULoad 或自定义事件的完整名称。事件类型是录制数据中的识别字段；RecordingFile.write 的谓词只决定哪些已经存在的事件写入新文件。

这和录制阶段的设置不是一回事。Recording.enable(...)、enabled、period 和 threshold 决定采集什么；导出阶段只能从已有文件中筛选，不能把原文件里没有记录的事件补出来。若名称写错，结果可能是一个没有目标事件的文件，而不是自动匹配相近名称。

用事件名称过滤并导出新文件

单一事件类型时，可以把目标名称放在常量中，再用事件对象的类型名称进行精确比较。RecordingFile 实现了 AutoCloseable，因此用 try-with-resources 管理输入文件，异常发生时也能释放关联资源。

import java.io.IOException;
import java.nio.file.Path;
import jdk.jfr.consumer.RecordingFile;

public class ExportJfrByType {
    public static void main(String[] args) throws IOException {
        Path source = Path.of("recording.jfr"); // 输入文件必须是可读取的JFR录制
        Path target = Path.of("execution-samples.jfr"); // 输出到新文件，不覆盖输入文件
        String wantedType = "jdk.ExecutionSample"; // 使用事件类型的完整名称

        try (RecordingFile recording = new RecordingFile(source)) {
            recording.write(target, event ->
                    wantedType.equals(event.getEventType().getName())); // 只保留精确匹配的事件
        }

        System.out.println("已写出: " + target); // 这里只报告目标路径，不代表已做线上核验
    }
}

筛选的关键不是事件的显示标签，而是 getEventType().getName() 返回的名称。使用常量放在比较左侧，可以避免目标字符串为 null 时出现意外的空指针。输入和输出路径也应分开：不要把输出路径设置成正在读取的原文件。

多个事件类型要用集合表达

如果目标是“保留 CPU 负载和执行采样”，不要把条件拼成模糊的字符串搜索。用不可修改集合明确列出允许写出的事件类型，后续增删名称也更容易审查。

import java.io.IOException;
import java.nio.file.Path;
import java.util.Set;
import jdk.jfr.consumer.RecordingFile;

public class ExportSelectedJfrEvents {
    public static void export(Path source, Path target) throws IOException {
        Set wantedTypes = Set.of(
                "jdk.ExecutionSample", // 方法采样事件
                "jdk.CPULoad" // CPU负载事件
        );

        try (RecordingFile recording = new RecordingFile(source)) {
            recording.write(target, event ->
                    wantedTypes.contains(event.getEventType().getName())); // 白名单决定写出范围
        }
    }
}

集合匹配的语义是白名单：只有集合中的完整名称会被写入。它不会因为两个事件的标签相似、包名相同或字段结构相近而自动合并。需要保留自定义事件时，把自定义事件注册时使用的完整名称加入集合，并保持大小写一致。

先读取类型清单，再决定过滤条件

当你不知道录制里实际有哪些事件时，可以先调用 readEventTypes() 输出名称。这个动作只读取元数据，适合在构造白名单前确认拼写。它不会把事件正文全部装入内存。

import java.io.IOException;
import java.nio.file.Path;
import jdk.jfr.EventType;
import jdk.jfr.consumer.RecordingFile;

public class ListJfrEventTypes {
    public static void main(String[] args) throws IOException {
        Path source = Path.of(args.length == 0 ? "recording.jfr" : args[0]); // 允许命令行替换输入路径

        try (RecordingFile recording = new RecordingFile(source)) {
            for (EventType type : recording.readEventTypes()) {
                System.out.println(type.getName()); // 以完整名称作为后续过滤键
            }
        }
    }
}

如果清单里没有预期名称，应先回到录制配置检查事件是否启用、录制时是否产生过该事件，再调整导出谓词。不要用“看起来接近”的名称替代实际名称，因为过滤条件是精确的。

按目标选择三种读取方式

如果目标是生成新的、较小的 JFR 文件，优先使用 write。它把筛选条件交给文件消费者，并直接写出新的录制。若目标是统计数量、读取字段或把每个事件转换为自己的数据结构，可以使用 hasMoreEvents() 和 readEvent() 循环；这时你通常不需要另存一个 JFR 文件。

readAllEvents 会返回文件中的全部事件列表，适合小型且可信的录制文件，代码短但内存占用随事件数增长。它不适合为了“方便”处理大型录制，尤其当导出任务本来只需要少数事件时。

导出前后的边界问题

输出文件为空怎么办？先打印 readEventTypes() 的结果，确认名称、大小写和录制文件是否匹配。也要区分“没有目标事件”和“文件无法解析”：前者是筛选结果，后者通常会以 IOException 暴露。

能否把原文件直接覆盖吗？不建议。导出仍依赖原文件作为读取源，把目标设置为另一个路径更容易回退，也避免读写同一文件造成不可预期的破坏。

过滤会改变事件字段吗？不会。write 的谓词决定事件是否被写出，不是字段映射器。如果需要把事件转换成 CSV、JSON 或统计表，应改用逐条读取并自行定义输出格式。

为什么不直接调用 readAllEvents 再筛选？小文件可以这样做，但它先把全部事件装进列表；按类型导出时，write 更贴合目标，也避免不必要的内存峰值。

实践上可以按这个顺序处理：先用 readEventTypes() 确认实际名称，再用 write 生成新 JFR；只有当目标变成统计、转换或小文件快速分析时，才选择逐条读取或 readAllEvents。这样“采集什么”和“导出什么”各自有清晰边界，导出的文件也更容易交给后续分析工具使用。

参考：https://docs.oracle.com/en/java/javase/25/docs/api/jdk.jfr/jdk/jfr/consumer/RecordingFile.html；https://docs.oracle.com/en/java/javase/25/docs/api/jdk.jfr/jdk/jfr/EventType.html；https://docs.oracle.com/en/java/javase/25/docs/api/jdk.jfr/jdk/jfr/consumer/package-summary.html。