RFC: Display contextual event fields in jfr view command

[Jaroslav Bachorík]

Hello,

I'd like to propose adding context display support to the `jfr view`
command. This would allow users to see which @Contextual events were active
when other events occurred, without requiring any changes to the JFR
recording format or runtime.

Background

Back in 2021, there was a discussion on this list about adding a Recording
Context concept to JFR (thread starting at 2021-June/002777). Erik
suggested an alternative to modifying the event format: use dedicated
context events with begin/end markers and correlate them during recording
analysis.

This proposal implements exactly that approach on the tooling side. When
users have events with @Contextual annotated fields (such as trace IDs,
span IDs, or request contexts), they can now view which contexts were
active during any event - all computed at analysis time from the existing
recording data.
---

Current State

The `jfr print` command already supports displaying contextual events. When
printing events, it shows active context fields inline:

  jfr print recording.jfr

  jdk.ThreadSleep {
    Context: Trace.traceId = "abc-123-def"
    Context: Trace.service = "order-service"
    startTime = 12:00:01.000
    duration = 50 ms
    ...
  }

This works well for detailed event inspection, but the `jfr view` command
(which displays events in a tabular format) has no equivalent capability.
---

The Problem

When using `jfr view` to analyze recordings from distributed systems, users
cannot see which contexts were active. The tabular format is often
preferred for scanning many events quickly, but without context information
users must:

1. Note the timestamp of the event of interest
2. Switch to `jfr print` or manually search for overlapping contextual
events
3. Match by thread ID to avoid cross-thread confusion
4. Repeat for every event they want to analyze

This breaks the workflow when trying to correlate events with their
contexts at scale.
---

Proposed Solution

Add a `--show-context` flag to `jfr view` that automatically displays
contextual event fields as additional columns:

 jfr view --show-context jdk.ThreadSleep recording.jfr

 ThreadSleep

  Time        Sleep Time   Trace.traceId       Trace.service
  ----------------------------------------------------------------
  12:00:01    50 ms        abc-123-def         order-service
  12:00:02    100 ms      abc-123-def         order-service
  12:00:03    25 ms        N/A                       N/A

The context matching rule is: a contextual event is active when
contextStart <= eventStart AND contextEnd >= eventStart.

Users can optionally filter which context types to display:

  jfr view --show-context=Span,Trace WorkEvent recording.jfr
---

Why This Approach?

1. No runtime overhead - context correlation happens entirely at analysis
time
2. No format changes - works with existing recordings that have @Contextual
events
3. Backward compatible - recordings remain readable by older tools
4. Flexible - users choose which contexts to display
5. Proven pattern - based on the timeline approach already used in
PrettyWriter
---

[PoC] Implementation Notes

The implementation tracks context per-thread using a timeline-based
approach similar to PrettyWriter.java. Events are buffered in a priority
queue ordered by timestamp. Contextual events contribute both start and end
timestamps, and active contexts are tracked per-thread to prevent
cross-thread leakage. Memory is bounded (~1M events) to handle large
recordings. Queries without --show-context bypass this entirely, so there's
no overhead for existing usage.

I've also added support for referencing contextual fields in GROUP BY
clauses for the `jfr query` command (debug builds), enabling aggregation
queries like:

  SELECT COUNT(*), Trace.traceId FROM WorkEvent GROUP BY Trace.traceId
---

Questions for Discussion

1. Is the matching rule (contextStart <= eventStart) correct? An
alternative would be to require the event to fall entirely within the
context.
2. Should there be a maximum number of context columns to prevent very wide
output?
3. Is 1M events a reasonable buffer size? This balances memory (~100MB)
with accuracy for long-running contexts.
4. The `jfr print` command already shows context - should there be a way to
disable it for consistency, or is the current always-on behavior correct?


I'd welcome feedback on the approach before proceeding further.

Thanks,

Jaroslacv
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/hotspot-jfr-dev/attachments/20260121/94f42b15/attachment-0001.htm>