Skip to content

Add tracing support for native method calls via Java FFM API#10718

Merged
gh-worker-dd-mergequeue-cf854d[bot] merged 17 commits intomasterfrom
andrea.marziali/ffm-instrument
Mar 31, 2026
Merged

Add tracing support for native method calls via Java FFM API#10718
gh-worker-dd-mergequeue-cf854d[bot] merged 17 commits intomasterfrom
andrea.marziali/ffm-instrument

Conversation

@amarziali
Copy link
Copy Markdown
Contributor

@amarziali amarziali commented Mar 3, 2026

What Does This Do

Introduces automatic tracing of native (downcall) method invocations made through the Java Foreign Function & Memory (FFM) API (available since JDK 22).

  • Adds a new configuration option trace.native.methods that follows the same library[method1,method2] / library[*] format as trace.methods, letting users opt-in to tracing specific native calls.
  • Instruments Linker.downcallHandle(MemorySegment, ...) to wrap the produced MethodHandle with span creation/finalization logic built using MethodHandles.tryFinally + MethodHandles.foldArguments — zero overhead when the handle is not traced.
  • Instruments NativeLibrary to capture the library identity at when the symbol address is resolved. This allow to connect the dot when using:
    • Linker.defaultLookup()
    • Linker.loaderLookup()
    • SymbolLookup.libraryLookup(String name, Arena)
    • SymbolLookup.libraryLookup(Path path, Arena)
  • Spans use operation name trace.native, component trace-ffm.
  • The resource name is lib_name.symbol_name. The lib_name is lowercased. Does not contain path or extension

A note about the library name used to resolve syscalls. Java use internally libsyslookup. I don't know how portable is it. If yes we can strip this prefix. However, today, to say I'd like to trace strlen from the libc the user needs to say that want to trace libsyslookup[strlen]

Motivation

R&D week

Additional Notes

Contributor Checklist

Jira ticket: [PROJ-IDENT]

Note: Once your PR is ready to merge, add it to the merge queue by commenting /merge. /merge -c cancels the queue request. /merge -f --reason "reason" skips all merge queue checks; please use this judiciously, as some checks do not run at the PR-level. For more information, see this doc.

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

inst: others All other instrumentations tag: experimental Experimental changes type: enhancement Enhancements and improvements

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants