Understand performance during a session

Use telemetry to see when frame rate drops, memory grows, or an app-defined metric changes during a session. Android records these numeric samples on metric channels so you can compare them with the surrounding app evidence.

Built-In Channels

The native Android runtime can record:

• Java heap
• native heap
• RSS
• FPS through Android frame callbacks
• battery level when enabled
• JNI global-reference count when enabled
• process open-file-handle count when enabled
• app-defined channels and metric streams

Custom Metrics

import ai.ansight.Ansight
import ai.ansight.runtime.AnsightChannel
import ai.ansight.runtime.AnsightRuntime

Ansight.registerMetricChannel(
    AnsightChannel(
        id = 42,
        name = "Queue Depth",
        colorHex = "#FF9500",
        unit = "items",
        type = "queue",
    ),
)

AnsightRuntime.metric(17, channel = 42)

For sampled values:

import ai.ansight.runtime.AnsightMetricSampler
import ai.ansight.runtime.AnsightMetricStream

Ansight.registerMetricStream(
    AnsightMetricStream(
        channel = AnsightChannel(43, "Cache Items", unit = "items", type = "cache"),
        sampler = AnsightMetricSampler { cache.itemCount.toLong() },
    ),
)

Reserved channel ids are 0-7 for built-in memory, FPS, lifecycle, battery, JNI reference count, and open file handles, plus 255 for unspecified events. App-defined channels must not reuse them.

Runtime Resource Channels

Both diagnostic channels are off by default:

val options = AnsightOptions.createBuilder()
    .withJniReferenceCountTracking()
    .withOpenFileHandleTracking()
    .build()

withJniReferenceCountTracking() emits channel 6 and is useful for spotting growth in JNI global references. withOpenFileHandleTracking() emits channel 7 from the current process descriptor count. These sampled channels are lightweight trend signals; use JNI Reference Diagnostics or File Descriptor Diagnostics when a point-in-time investigation needs individual roots or descriptors.

Runtime Sampling

AnsightRuntime.captureBuiltInTelemetrySample()

Battery telemetry is opt-in:

val options = AnsightOptions.createBuilder()
    .withBatteryLevel()
    .build()