Trends Telemetry

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