Add source information to events (source file, line number)

[jlittle-ptc]

Is your feature request related to a problem? Please describe.
Our application can identify areas of concern in a log file, and having the ability to direct the user to the specific line(s) in the source file where the problem occurs would improve the user experience.

Describe the solution you'd like
At a minimum the starting line number added to the GCEvent. Adding an end line is optional, but might be useful.

We currently only use the SingleGCLogFile source in our application, but those using the RotatingGCLogFile may want to have the source filename/path available as well.

[dsgrieve]

The complicating factor here is that an event can span multiple, not necessarily contiguous, lines. I think a way to handle this would be to collect the line numbers and lines in the forward reference.

[jlittle-ptc]

Good point. For Unified logging, it's not as big of a deal as each line has an event ID attached, though that's also the only place I've noticed event interleaving. Our specific use case will do fine with start-only, anything above is bonus.

[brunoborges]

/relevance-check

[github-actions]

Relevance Assessment: Still Relevant

• Summary: This feature request to add source file and line number information to GC events has not been implemented and remains a valid, actionable enhancement.

• Evidence:

  • The GCEvent class (api/src/main/java/com/microsoft/gctoolkit/event/GCEvent.java) has no fields for line numbers or source file paths. It only contains gcType and cause, inheriting timeStamp and duration from JVMEvent.
  • The ForwardReference class (parser/src/main/java/com/microsoft/gctoolkit/parser/ForwardReference.java), which was suggested as a potential place to collect line numbers (per @dsgrieve's comment), currently tracks decorators, gcID, duration, gcCause, cpuSummary, and survivorRecord — no source location fields.
  • SingleGCLogFile and RotatingGCLogFile provide file path access via FileDataSource.getPath() but do not track line numbers during stream processing.
  • No commits since this issue was opened (July 2025) relate to adding source information to events. Recent commits have focused on ZGC parsing, G1GC memory pools, dependency bumps, and workflow fixes.
  • No duplicate or superseding issues were found.
  • No open or merged PRs address this feature.

• Recommendation: ✅ Keep open — The feature has not been implemented, the codebase classes it would affect (GCEvent, ForwardReference, SingleGCLogFile, RotatingGCLogFile) still exist and are actively maintained, and the request remains well-defined and actionable. The requester (jlittle-ptc) is an active contributor, and a maintainer (@dsgrieve) has already engaged with a concrete implementation suggestion around the ForwardReference mechanism.

Generated by Relevance Check Agent for issue #449