RFC: Display contextual event fields in jfr view command

[Erik Gahlin]

I meant, something like PrettyWriter but with columns (not FormRenderer).

Erik

________________________________________
From: hotspot-jfr-dev <hotspot-jfr-dev-retn at openjdk.org> on behalf of Erik Gahlin <erik.gahlin at oracle.com>
Sent: Monday, January 26, 2026 1:34 PM
To: Jaroslav Bachorík; hotspot-jfr-dev
Subject: Re: RFC: Display contextual event fields in jfr view command

Hi Jaroslav,

The 'jfr print' command is meant for presentations, demos, and debugging. It was never designed for application troubleshooting. The contextual support added in JDK 25 was included to demonstrate to application developers how the @Contextual annotation can be used, and to show third parties how contextual support can be implemented using the jdk.jfr.consumer API.

The 'view' command, on the other hand, was designed for troubleshooting and can be used on a live process, so it should not use excessive memory or CPU.

You added a command-line flag, --show-context, perhaps to prevent additional overhead from contextual processing, but before adding flags, I think it might be a good time to step back and think about how we best can present contextual information to users. A flag is usually hard for users to find. It would be better to add support in JMC, so users can discover contexts and then drill deeper by clicking in the GUI.

I'm also wondering if contextual support belongs in the query language. It's not clear how columns of nested contexts should be identified. It may be better to create something like FormRenderer that only handles event types.

We have also discussed adding a bit in the chunk header if a contextual event has been emitted. This would allow a parser to have a fast path when there are no contextual events.

Thanks
Erik
________________________________________
From: hotspot-jfr-dev <hotspot-jfr-dev-retn at openjdk.org> on behalf of Jaroslav Bachorík <jaroslav.bachorik at datadoghq.com>
Sent: Wednesday, January 21, 2026 10:03 PM
To: hotspot-jfr-dev
Subject: RFC: Display contextual event fields in jfr view command

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