Configuration

Configure native Android sampling, memory channels, screenshots, touch input, pairing, custom properties, artifacts, tools, and guard policy.

Configure Android with AnsightOptions or AnsightOptions.createBuilder().

import ai.ansight.Ansight
import ai.ansight.runtime.AnsightOptions

val options = Ansight.options(
    AnsightOptions.createBuilder(Ansight.developerOptions(clientName = "Android App"))
        .withReadOnlyToolAccess()
        .withBatteryLevel()
        .registerCustomProperty("app", "region", "au")
        .build(),
)

Core Defaults

AnsightOptions() starts with:

Option	Default
`sampleFrequencyMilliseconds`	`500`
`retentionPeriodSeconds`	`600`
`enableFramesPerSecond`	`true`
`enableBatteryLevel`	`false`
`defaultMemoryChannels`	Java heap, native heap, RSS
`sessionJpegCapture`	`null`
`touchCapture`	enabled with Android defaults
`toolGuard`	`AnsightToolGuard.Disabled`
`hostAutoProbe`	enabled

Ansight.developerOptions(...) changes the local-development defaults to 400 ms sampling, 120 s retention, JPEG capture 2000/60/480, full tool access, bundled developer pairing, and standard native tools.

Important: Screen capture will result in an FPS drop while the SDK captures, encodes, and transports frames. Disable session JPEG capture for performance-focused runs unless visual evidence is required.

Builder Methods

Method	Purpose
`withSampleFrequencyMilliseconds(...)`	Set built-in telemetry cadence.
`withFramesPerSecond()` / `withoutFramesPerSecond()`	Toggle FPS sampling.
`withBatteryLevel()` / `withoutBatteryLevel()`	Toggle battery sampling.
`withRetentionPeriodSeconds(...)`	Set local metric/event retention.
`withAdditionalChannels(...)` / `addAdditionalChannel(...)`	Register custom metric channels.
`withDefaultMemoryChannels(...)` / `withoutDefaultMemoryChannels(...)`	Configure Java heap, native heap, and RSS channels.
`withSessionJpegCapture(...)` / `withoutSessionJpegCapture()`	Configure live JPEG frame capture. Accepts `captureGpuBackedSurfaces` for cross-platform parity.
`withTouchCapture(...)` / `withoutTouchCapture()`	Configure touch input capture.
`withToolGuard(...)`	Set an explicit tool guard.
`withToolsDisabled()`	Disable tool discovery and execution.
`withReadOnlyToolAccess()`	Allow read-scoped tools only.
`withReadWriteToolAccess()`	Allow read and write scopes.
`withAllToolAccess()`	Allow read, write, and delete scopes.
`withHostAutoProbe(...)` / `withoutHostAutoProbe()`	Configure background reconnect probing.
`withHostConnection(...)` / `configureHostConnection(...)`	Configure saved, bundled, and developer pairing.
`withSecureStorage(...)`	Configure secure-storage options.
`withTools(...)` / `addTool(...)` / `addTools(...)`	Register app or package tools.
`withArtifactProviders(...)` / `addArtifactProvider(...)`	Register artifact providers.

Validation clamps sample frequency to 200-2000 ms, retention to 60-3600 s, JPEG quality to 1-100, and JPEG max width to 8192.

captureGpuBackedSurfaces defaults to true. The capture-mode tradeoff is currently meaningful on iOS, where setting it to false selects a lower-overhead path that may miss GPU-backed surfaces.

Host Auto-Probe

AnsightHostAutoProbeOptions controls remembered-host retries while the runtime is active. When enabled, the SDK retries previous host connections so the app can reconnect after the host disappears and later reappears.

Property	Default
`enabled`	`true`
`initialDelayMilliseconds`	`1000`
`probeIntervalMilliseconds`	`5000`
`reconnectDelayMilliseconds`	`10000`
`clientName`	`null`

Use withoutHostAutoProbe() when reconnects should only happen after an explicit app action.

Tool Guard

Guard	Allowed scopes
`AnsightToolGuard.Disabled`	none
`AnsightToolGuard.ReadOnly`	`Read`
`AnsightToolGuard.ReadWrite`	`Read`, `Write`
`AnsightToolGuard.FullAccess`	`Read`, `Write`, `Delete`