Understand app behavior with logs

The reason behind an error or unexpected screen often lives in your app’s logs. Record meaningful app events with the session so people and agents can compare those details with other evidence.

Use app events for logs that should become part of the Ansight session timeline. Use sendClientLog(...) for ad hoc live-session log lines. Use AnsightLogger only for Ansight SDK diagnostics.

App Events

try AnsightRuntime.shared.event(
    "Checkout loaded",
    type: .info,
    details: "route=/checkout"
)

try AnsightRuntime.shared.event(
    "Payment failed",
    type: .error,
    details: "httpStatus=500"
)

Attach a custom channel when the event belongs to a specific metric or subsystem:

try AnsightRuntime.shared.event(
    "Queue retry",
    type: .warning,
    details: "attempt=2",
    channel: 42
)

Live Client Logs

await AnsightRuntime.shared.sendClientLog("Checkout loaded cartId=debug-42")

sendClientLog(...) sends the line over the active live session. It does not automatically mirror print, OSLog, or third-party logging frameworks.

SDK Diagnostics

Observe Ansight SDK-internal logs with AnsightLogger:

let callback = AnsightClosureLogCallback { level, message, error in
    print("[Ansight] \(level.rawValue): \(message)")
}

AnsightLogger.registerCallback(callback)
AnsightLogger.removeCallback(callback)

SDK diagnostics are useful while debugging the integration. They are not the primary app-log capture path.

Session Properties

Grouped session properties are included in session.open. When a live session is connected, updates are also sent immediately.

await AnsightRuntime.shared.updateSessionProperties([
    "app": [
        "region": "au",
        "tenant": "debug"
    ]
])

await AnsightRuntime.shared.clearSessionProperties()

Logging Quality

Prefer stable labels and compact structured details. Sparse or inconsistent logs make session analysis weaker.

Crash Candidates

Native exception, signal, and platform-diagnostic hooks are installed automatically while Crash Capture is enabled. A framework or app integration can add context to the native outbox:

let candidateId = AnsightRuntime.shared.recordCrashCandidate(
    runtime: "swift",
    kind: "task_failure",
    message: error.localizedDescription,
    stack: Thread.callStackSymbols.joined(separator: "\n"),
    fatal: false,
    metadata: ["component": "checkout"]
)

A non-fatal candidate is context for an independently confirmed native exit; it is not a crash report by itself. Continue recording ordinary exception events when an error should appear immediately in the current timeline. Do not include secrets or personal data in messages, stacks, breadcrumbs, or metadata.