Java 自定义 JFR Event 怎么控制提交条件

Java 自定义 JFR Event 的提交条件，通常不是在业务代码里另加一个布尔开关，而是把三层判断分开：先用 isEnabled() 判断当前是否真的有录制在收集该事件；事件有时长时，在 end() 之后用 shouldCommit() 判断是否达到当前录制的阈值；最后才调用 commit()。这样既能跳过昂贵字段采集，也不会把低于阈值的事件写进 Flight Recorder。

先把 JFR Event 的三个开关分清

自定义事件继承 jdk.jfr.Event。事件类默认启用，也可以用 @Enabled(false) 作为默认关闭状态，再由 Recording 配置打开。isEnabled() 返回 true 的前提是至少有一个 Recording 正在运行，并且该事件当前处于 enabled 状态。

但启用不代表每个事件实例都会写入。一个 Recording 还可能配置了 threshold，例如只保留耗时不低于 20 ms 的事件。因此字段准备、阈值判断和最终写入要按成本从低到高排列。

用 isEnabled 把昂贵采集挡在最外层

如果事件只记录一个整数，直接 new、赋值、commit 的成本通常容易接受；但堆栈摘要、请求标签、序列化结果或复杂对象转换可能本身就很贵。此时先判断 isEnabled()，可以让没有录制或事件被关闭的普通请求快速返回。

static void recordQuery(String sql, long rows) {
    // 没有活动录制时，避免创建事件和准备额外诊断数据
    QueryEvent event = new QueryEvent();
    if (!event.isEnabled()) {
        return;
    }

    event.rows = rows;
    event.sqlShape = normalizeSql(sql); // 只保存脱敏后的查询形状
    event.commit(); // 启用时再提交事件
}

这里的判断解决的是“是否值得继续准备数据”，不是业务层的过滤条件。若还要按业务规则只记录慢查询，应把规则设计成字段采集成本可控的判断，并与 JFR 自身的 threshold 分工。

让 shouldCommit 依赖真实时长，而不是猜测

对有持续时间的事件，调用顺序应是 begin()、执行被观测代码、end()，然后再调用 shouldCommit()。官方 API 将 threshold 定义为当前运行中 Recording 的最小持续时间门槛；多个 Recording 同时存在时，判断结果由实际生效的配置共同决定。

static void executeTask(Task task) {
    SlowTaskEvent event = new SlowTaskEvent();
    if (!event.isEnabled()) {
        return; // 事件未启用时不测量、不采集附加信息
    }

    event.begin();
    try {
        task.run();
    } finally {
        event.end(); // shouldCommit 必须在 end 之后判断时长
        if (event.shouldCommit()) {
            event.detail = task.safeSummary(); // 只给可能写入的事件补充细节
            event.commit();
        }
    }
}

shouldCommit() 返回 false 时，事件不会因为“最后没有 commit”而自动写入；它只是告诉调用方当前实例不值得提交。若 safeSummary() 可能抛异常，应在事件采集边界内单独处理，不能让诊断逻辑改变业务任务的异常语义。

用 Recording 配置验证提交条件

默认事件阈值是 0，也就是不设持续时间门槛。需要只关注慢事件时，可以在 Recording 上启用自定义事件并设置阈值；这比把固定毫秒数硬编码到业务方法更容易按环境调整。

try (Recording recording = new Recording()) {
    // 只收集 SlowTaskEvent，阈值由录制配置控制
    recording.enable(SlowTaskEvent.class)
             .withThreshold(Duration.ofMillis(20));
    recording.start();

    runWorkload();

    recording.stop(); // 停止后再按需要 dump 或交给消费端读取
}

配置后要区分三种结果：isEnabled() 为 false，说明没有活动录制或事件被禁用；isEnabled() 为 true 但 shouldCommit() 为 false，说明事件启用却未达到有效阈值；两者都为 true 后调用 commit()，才是一次实际提交路径。

如果事件没有使用 begin/end，则没有持续时间可供 threshold 过滤，应该把提交条件放在事件自身可解释的字段或调用方规则上，不要误以为 shouldCommit() 会替你判断任意业务字段。

常见问题与判断清单

shouldCommit 要放在 commit 前还是 end 后？

有时长事件应放在 end() 之后、commit() 之前；否则测到的时长还没结束，阈值判断就没有完整依据。

isEnabled 为 true，为什么 shouldCommit 仍然是 false？

最常见原因是 Recording 的 threshold 高于本次事件时长。启用只说明事件有资格被记录，不代表当前实例一定满足持续时间门槛。

能不能只调用 shouldCommit，不调用 isEnabled？

可以得到提交判断，但无法尽早跳过昂贵数据准备。若事件字段便宜可直接使用；存在序列化、标签计算等额外成本时，保留两层判断更合适。

实际落地时可以记住一条简单顺序：先问“有没有录制”，再测量并结束事件，随后问“是否达到门槛”，最后才补齐必要字段并提交。这个顺序正好把 JFR 的运行时开关、时长过滤和业务采集成本隔离开。