Investigate objects retained through JNI references

JNI Reference Diagnostics helps investigate which Java objects remain reachable through JNI roots when reference counts need explanation. Capture a bounded, redacted graph for a focused retention investigation.

.NET Android exposes the ToolPolicy.Read jni_references.capture_graph tool through Ansight.Core. The Ansight and Ansight.Maui all-in-one setup registers it automatically on Android; it is not available on iOS, Mac Catalyst, or non-Android .NET targets.

Register in a Core-Only Android App

using Ansight;
using Ansight.Tools.JniReferenceDiagnostics;

var options = Options.CreateBuilder()
    .WithJniReferenceDiagnosticsTools()
    .WithReadOnlyToolAccess()
    .Build();

The extension and tool are compiled only for an Android target framework.

Capture a Graph

{
  "toolId": "jni_references.capture_graph",
  "arguments": {
    "maxNodes": 512,
    "maxEdges": 1024,
    "maxDepth": 4
  }
}

Call defaults are 512 nodes, 1,024 edges, and depth 4. Accepted hard bounds are 1-8,192 nodes, 1-16,384 edges, and depth 0-16.

The Android bridge writes a temporary HPROF snapshot, indexes it, and walks objects reachable from JNI global, local, or monitor roots. Results contain capture-local opaque ids, class names, shallow sizes, root metadata, reference edges, counts, and truncation state. Raw heap ids, JNI handle addresses, primitive values, strings, and field values are omitted.

Availability and Cost

The tool catalog evaluates runtime availability before invocation. An initialized Android Application is required; otherwise the entry is non-executable with reason code android_application_unavailable and remediation context.

HPROF capture briefly pauses the app and graph indexing requires additional memory. The temporary heap file is deleted after graph construction. Keep the suite in trusted Debug builds and avoid invoking it during trend measurements.

Use Trends Telemetry with WithJniReferenceCountTracking() for a lightweight trend, then capture a graph only when the trend needs explanation.