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.

[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

[jkoritzinsky]

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?

I think contextPointer may be stable, but componentIndex is definitely not.

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?

On the runtime side, we only can track which bridge objects die, not which ones continue to live unless we add additional tracking both over here and in dotnet/runtime.

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: steveisok/android-gcbridge-investigation

I think adding a sampling counter would make sense.

[jkoritzinsky]

@copilot please add EventCounter-based aggregate metrics (that can be enabled separately from the fine-grained events) for the following scenarios:

• number of .NET objects only reachable from Java
• number of Java objects only reachable from .NET
• number of bridge objects still alive after bridge processing
• number of bridge objects that are unreachable after bridge processing

[Copilot]

@copilot please add EventCounter-based aggregate metrics (that can be enabled separately from the fine-grained events) for the following scenarios:

• number of .NET objects only reachable from Java...

Implemented this in 79f463a. The aggregate metrics now come from a separate Microsoft.Android.Runtime.InteropMetrics EventCounter provider, so they can be enabled independently from the fine-grained interop events.

[jkoritzinsky]

@copilot It looks like ManagedObjectsOnlyReachableFromJavaCount and BridgeObjectsAliveAfterProcessingCount are identical here. (and the same for the other two options).

Please remove the BridgeObjectsAliveAfterProcessingCount and BridgeObjectsUnreachableAfterProcessingCount metrics.

[Copilot]

Addressed in 9cc31d8. The duplicate BridgeObjectsAliveAfterProcessingCount and BridgeObjectsUnreachableAfterProcessingCount metrics are removed, and the remaining counter API/tests/docs now only expose the two distinct reachability counts.