Summary

Add the annotation jdk.jfr.Contextual to indicate that the field of a user-defined event provides context for other events happening in the same thread at the same time.

Problem

User-defined events may carry information that is relevant to other events that happen in the same thread at the same time. For example, an HTTPRequest event may contain a URL and a trace ID. If the thread is stalled, perhaps because of lock contention, troubleshooting could be simplified if the request URL and trace ID was associated with the jdk.JavaMonitorEnter event.

Users can correlate these events today by manually examining other events that occur in the same thread while the HTTP request was being processed, but this is a cumbersome task. GUI and tooling can attempt to automate this process, but they lack knowledge of which fields provide contextual information

Solution

If a field in a user-defined event is annotated with @Contextual, that information could be propagated and potentially displayed as an additional field in the jdk.JavaMonitorEnter event. For example, an HTTPRRequest event could look like this:

 @Label("HTTP Request")
 class HttpRequest extend Event {
   @Label("Content-Type")
   String contentType;

   @Label("URL")
   @Contextual
   String url;

   @Label("Trace ID"
   @Contextual
   String traceID;
}

Tooling, such as the jfr print command, can then infer URL and trace ID for the jdk.JavaMonitorEnter event and display it like this:

$ jfr print --events JavaMonitorEnter recording.jfr

jdk.JavaMonitorEnter {
  startTime = 00:51:46.326 (2025-05-13)
  duration = 20.01 ms
  monitorClass = com.example.Logger (classLoader = sun.misc.Launcher$AppClassLoader)
  ...
  context = { 
    traceId = 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01 (HTTPRequest)
    url = https://com.example/service/show-playlist (HTTPRequest)
  }
}

Specification