Understand performance during a session

Telemetry adds performance context to what happened in your app. Record numeric samples over time to see how frame rate, memory, and your own metrics change around actions or errors in a session.

For app logs and timeline events, see Capturing Logs.

Built-In Channels

The iOS runtime can record:

• managed heap where available
• physical footprint through native process memory APIs
• FPS through CADisplayLink
• battery level when enabled
• process open-file-handle count when enabled
• custom channels registered by the app

The aggregate developer setup enables FPS and the default memory channels. Battery remains opt-in.

Minimal Setup

let options = try AnsightOptions.createBuilder()
    .withFramesPerSecond()
    .build()

try AnsightRuntime.shared.initializeAndActivate(options: options)

Tune Sampling And Retention

let options = try AnsightOptions.createBuilder()
    .withSampleFrequencyMilliseconds(250)
    .withRetentionPeriodSeconds(900)
    .withFramesPerSecond()
    .build()

Lower sample intervals produce denser graphs and more overhead.

Battery Level

let options = try AnsightOptions.createBuilder()
    .withBatteryLevel()
    .build()

The SDK enables battery monitoring while active and restores the previous system setting when deactivated.

Custom Metrics

try AnsightRuntime.shared.registerMetricChannel(
    AnsightChannel(
        id: 42,
        name: "Queue Depth",
        color: "#FF9500",
        unit: "items",
        type: "queue"
    )
)

try AnsightRuntime.shared.metric(17, channel: 42)

For sampled values, register a metric stream:

try AnsightRuntime.shared.registerMetricStream(
    AnsightMetricStream(
        channel: AnsightChannel(id: 43, name: "Cache Items", unit: "items", type: "cache")
    ) {
        Int64(cache.itemCount)
    }
)

Do not use reserved channel ids. The cross-platform SDK reserves ids 0-7 for built-in memory, FPS, lifecycle, battery, JNI reference count, and open file handles, plus 255 for the unspecified channel. JNI reference sampling is Android-only; id 6 remains reserved on iOS for a stable cross-platform contract.

Open File Handles

Open-file-handle tracking is off by default. Enable channel 7 when the session needs a process-level resource trend:

let options = try AnsightOptions.createBuilder()
    .withOpenFileHandleTracking()
    .build()

Use File Descriptor Diagnostics when a point-in-time investigation needs individual descriptors, paths, or limit utilization rather than only the sampled count.

Runtime Sampling

Capture a built-in telemetry sample manually when you need a point-in-time reading before the next scheduled sample:

AnsightRuntime.shared.captureBuiltInTelemetrySample()