Summary

Add the annotation class jdk.jfr.Throttle to indicate that an event should be rate-limited.

Problem

Currently, JDK Flight Recorder (JFR) has two ways to prevent an excessive number of events: disabling the event or setting a threshold.

The threshold setting only records events that exceed a minimum duration, which doesn't work for events that lack a duration, like exception events. As a result, those events must be turned off by default to prevent excessive CPU usage or flooding of JFR buffers, which can cause other, more important events to be lost.

The threshold setting is also limited when it comes to events with a duration, such as the jdk.SocketRead and jdk.SocketWrite events, since the duration depends on the program - for example, the number of users currently using a web application. This means the threshold must be set to a very high value by default to prevent high CPU usage or flooding. Today the socket event uses a 20 ms threshold.

Solution

Introduce a Throttle annotation that can be used on JDK events, but also on events that users define themselves. The Throttle annotation has existed since JDK 16, but has been located in an internal package, not available to end users, only for HotSpot events. The annotation will be off by default, but users can set a rate, expressed as a number of events per time unit, for example, "1000/s"

The throttle option can be used in combination with threshold, for example, record all socket events that take more than 1 ms, but never more than 500 events / second.

Specification