Today, a user-defined event can be created to indicate that other events, such as JDK or SQL events, happens in a context, for example:

@Name("example.ExecutionContext");
public class ExecutionContextEvent extends Event {
     String ECID;
}

@Name("example.Scope")
public class ScopeEvent {
    String operationName;
    String traceId;
    String spanId;
    String parentId;
}

Users can filter out events, programmatically or in JMC, to see which context that is responsible for a slow database query, contended lock or a high CPU usage.

Problem is that other events, such as Socket Read or Java Monitor Blocked event, have to be thresholded to keep overhead low and recording files to a reasonable size. This results in users not getting all, or any, events for a particular context.

The space requirements and CPU overhead could be lowered if context events are only emitted if an outlier event happens during the context, or events during the context are only recorded every hundredth time, but with a threshold set to 0 ms for all other events.

For this to work, JFR would need to know which events that are context events, and then provide filtering capabilities for those. This can be achieved by introducing an annotation users can put on their events, for example:

    @Contextual
    public class ScopeEvent extends Event {
    ....
    }

Example usage:

    $ java -XX:StartFlightRecording:example.Scope#select=if-outliers ...

The mechanism can be combined with a throttling capability similar to what already exists for native events:

    $ java -XX:StartFlightRecording:
        example.ExecutionContext#select=all ...
        example.ExecutionContext#throttle=100/s ...

The throttle decision has to be made when the begin method is invoked and not at the call to commit(). It might be interesting to explore if user-defined filtering could also be done using custom settings, for example, an URL setting for a HTTP context event.

    $ java -XX:StartFlightRecording:
        example.HttpRequest#select=all ...
        example.HttpRequest#url=https://www.example.com/login/.* ...

The syntax and semantics of the settings above are illustrative. An implementation would need to flesh out the concepts to make it consistent.

Allowing context events to have thresholds would be desirable, for example, record all events that happens during a HTTP request that takes more than 10 ms, but hard to implement efficiently since the duration of the request is not known until the event is over. A well though-out design should not rule out thresholded context events in the future.

A context annotation would allow tools, such as JMC, to create dedicated context visualization, for example tooltips, property pages or predefined pages where events are broken down by context. For instance, this is how the 'jfr print' command could display lock contention and tie it to an execution context happening in Java.

jdk.JavaMonitorEnter {
  startTime = 00:51:46.326 (2024-02-13)
  duration = 20.01 ms
  monitorClass = java.lang.Object (classLoader = bootstrap)
  ...
  context = { ECID = 0000M31FtLAFo2H6yvR_6G1QJ7Wl0000K }
}