Add EventPipe interop instrumentation for wrapper lifecycle and GC-bridge reachability

[Copilot]

This adds first-class EventPipe visibility into the .NET↔Java interop layer so wrapper lifecycle and cross-runtime reachability transitions can be observed in production traces. The instrumentation covers wrapper creation/release on both sides and GC-bridge reachability state transitions with correlation data.

• New interop EventSource provider

  • Added a single provider: Java.Interop
  • Added stable event IDs/keywords for:
    • DotNetWrapperCreated
    • JavaWrapperCreated
    • DotNetWrapperReleasedJavaReference
    • JavaWrapperReleasedDotNetReference
    • DotNetObjectOnlyReachableFromJava
    • JavaObjectOnlyReachableFromDotNet
  • Standardized payload fields: managed type, Java type, JNI identity hash, managed object hash, runtime mode; reachability events also include component/context correlation fields.

• Wrapper creation instrumentation

  • Emitted .NET wrapper for Java object events from:
    • ReflectionJniValueManager.CreatePeer
    • TrimmableTypeMapValueManager.CreatePeer
    • AndroidRuntime.AndroidValueManager.CreatePeer
  • Emitted Java wrapper for .NET object events from:
    • ManagedPeer.Construct
    • ConstructPeerCore paths where Java peer references are established

• Wrapper release instrumentation

  • Emitted .NET wrapper releases Java reference from disposal/finalization paths:
    • JniValueManager.DisposePeer
    • JavaMarshalRegisteredPeers.FinalizePeer
  • Emitted Java wrapper releases .NET reference from registered-peer removal:
    • JavaMarshalRegisteredPeers.RemovePeer

• GC-bridge reachability instrumentation

  • Emitted reachability-transition events from JavaMarshalRegisteredPeers bridge processing:
    • .NET object only reachable from Java
    • Java object only reachable from .NET
  • Included bridge round correlation data (componentIndex, contextIndex, contextPointer) for trace-side reconstruction.

• Low-overhead event gating

  • Guarded all instrumentation paths with InteropEventSource.IsEnabled() before payload-heavy work (e.g., Java type resolution) to avoid unnecessary overhead when no listener is attached.

• API, tests, and docs

  • Added public API entries for InteropEventSource.
  • Added Java.Interop unit tests validating event emission and payload shape.
  • Added runtime-facing tests in Mono.Android for lifecycle event behavior.
  • Added event catalog and dotnet-trace usage documentation.

if (InteropEventSource.IsEnabled ()) {
	InteropEventSource.DotNetWrapperCreated (
		peer.GetType ().FullName,
		javaType,
		peer.JniIdentityHashCode,
		RuntimeHelpers.GetHashCode (peer),
		GetRuntimeMode ());
}

[Copilot]

Pull request overview

This PR introduces EventPipe instrumentation across the .NET↔Java interop layer to make wrapper lifecycle and GC-bridge reachability transitions observable in production traces via a new Java.Interop EventSource provider.

Changes:

• Added a new Java.Interop EventSource (InteropEventSource) with stable event IDs/keywords and a documented payload schema.
• Instrumented wrapper creation/release in Java.Interop value managers + Mono.Android runtime, and added GC-bridge reachability transition events with correlation fields.
• Added unit tests (Java.Interop) and runtime-facing tests (Mono.Android) plus documentation for capturing with dotnet-trace.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/Mono.Android-Tests/Mono.Android-Tests/Java.Interop/InteropEventSourceRuntimeTests.cs	Runtime tests validating lifecycle events are emitted on-device/in-runtime.
src/Mono.Android/Microsoft.Android.Runtime/TrimmableTypeMapValueManager.cs	Emits wrapper creation events for trimmable typemap value manager paths.
src/Mono.Android/Microsoft.Android.Runtime/JavaMarshalRegisteredPeers.cs	Emits wrapper release + GC-bridge reachability events during bridge processing.
src/Mono.Android/Android.Runtime/AndroidRuntime.cs	Emits wrapper creation events for AndroidValueManager.CreatePeer.
external/Java.Interop/tests/Java.Interop-Tests/Java.Interop/InteropEventSourceTests.cs	Unit tests validating EventSource emission and payload shape.
external/Java.Interop/src/Java.Interop/PublicAPI.Unshipped.txt	Declares new public API surface for InteropEventSource.
external/Java.Interop/src/Java.Interop/Java.Interop/ManagedPeer.cs	Emits JavaWrapperCreated during managed-peer construction from Java.
external/Java.Interop/src/Java.Interop/Java.Interop/JniRuntime.ReflectionJniValueManager.cs	Emits wrapper creation events in reflection-based value manager.
external/Java.Interop/src/Java.Interop/Java.Interop/JniRuntime.JniValueManager.cs	Emits wrapper release events during peer disposal.
external/Java.Interop/src/Java.Interop/Java.Interop/InteropEventSource.cs	New provider implementation + event definitions/keywords.
external/Java.Interop/Documentation/EventPipeInteropEvents.md	Event catalog, payload schema, and dotnet-trace collection instructions.

[jonathanpeppers]

There is some existing code in here for writing gref/lref logs. It is old and text-based. Does this replace or supplement this?

[jkoritzinsky]

I believe this replaces those logs.

[jkoritzinsky]

@copilot resolve the merge conflicts in this pull request

[Copilot]

@copilot resolve the merge conflicts in this pull request

Resolved the merge conflict and merged origin/main into this branch in 2a5b83e. The conflict in RuntimeFeature.cs now preserves both the interop EventSource feature switch and the new ManagedToJavaUsesAssemblyFullName switch from main.

[steveisok]

This helps — I've been investigating dotnet/runtime#131370 (Android frame drops from the GC bridge) and I think interop visibility is important if we get apps negatively impacted by the bridge. I suspect promotion cost has the potential to get in the way for games / high responsive graphic apps. A couple questions:

1. Are contextPointer and componentIndex a stable contract, or an implementation detail?

The bridge's cost tracks promoted bytes, not peer count — it force-promotes each peer's whole
transitive closure, so the objects hanging off a peer usually outweigh the peer itself. Those bytes
aren't computable from this layer; they'd have to come from a GC-side event in dotnet/runtime.

If we add one, these two fields are what would let the two sides join: "this bridge round promoted
N MB" + "here are the types that were in it." That only works if they're something we can depend
on. Can we treat them as such?

2. Would a sampling or aggregate-only keyword be worth adding?

I built a probe that has millions of peer registrations over a 40 s run. Each event carries two strings,
and CaptureReachabilityEvent makes a GetJniTypeNameFromInstance JNI call per object. Free when
off — but the reason to turn it on is a jank investigation, which is exactly when the app is
allocating hardest.

Repro and scripts: https://github.com/steveisok/android-gcbridge-investigation