Performance Telemetry

Performance telemetry is numeric data recorded on metric channels. 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
• 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 SDK reserves built-in memory channels, FPS, lifecycle, battery level, and the unspecified channel.

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()