RFC: Display contextual event fields in jfr view command

Tue Feb 10 12:00:37 UTC 2026

Hi Erik,

Thanks for the reply. Please, bear in mind that this is just an exploratory
RFC, nothing is set in stone.

When we started talking about using JFR events for expressing context we
also talked about having support in the 'jfr' tool that would be able to
show the context in a concise manner. What is 'concise manner' is still not
completely clear and hence this RFC to start the discussion about what
would make sense from the end-user point of view.

>From your reply it seems like having context support in the 'jfr' tool is
not strictly necessary as long as there is JMC support? Am I reading this
correctly?

Cheers,

Jaroslav

On Mon, Jan 26, 2026 at 1:34 PM Erik Gahlin <erik.gahlin at oracle.com> wrote:

> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/hotspot-jfr-dev/attachments/20260210/13e863b4/attachment.htm>