Skip to main content

Configuring Backtrace for iOS

Configure Backtrace for your iOS project. This page defines the configuration settings, classes, and methods available with the Backtrace Cocoa SDK.

Usage​

Usage Example
loading...

Advanced Usage​

For more advanced usage of BacktraceClient, you can supply BacktraceClientConfiguration as a parameter. See the following example:

let backtraceCredentials = BacktraceCredentials(endpoint: URL(string: "https://backtrace.io")!, token: "token")
let configuration = BacktraceClientConfiguration(credentials: backtraceCredentials,
                                                 dbSettings: BacktraceDatabaseSettings(),
                                                 reportsPerMin: 10,
                                                 allowsAttachingDebugger: false,
                                                 oomMode: .full)
BacktraceClient.shared = try? BacktraceClient(configuration: configuration)

BacktraceClientConfiguration​

Parameters​

SettingDescriptionTypeDefault
credentials (Swift) or
initWithCredentials (Objective-C)		The BacktraceCredentials (endpoint URL and submission token) used to initialize the BacktraceClient.Parameter
dbSettingsThe BacktraceDatabaseSettings used to initialize the BacktraceDatabase.Parameter
reportsPerMinThe shared client-side report limit for live, pending-native, and retried reports. Set to 0 for unlimited submissions.Integer30
delegateWeak reference to the delegate installed before startup report processing. Retain the delegate in your application.BacktraceClientDelegate?nil
loggingDestinationsOptional logging destinations installed before repository and crash reporter startup. See startup diagnostics.Set<BacktraceBaseDestination>?nil
allowsAttachingDebuggerSpecifies whether to send reports when the debugger is connected.

The options are:
  • false (Swift) / NO (Objective-C): BacktraceClient won't send reports when the debugger is connected.
  • true (Swift) / YES (Objective-C): BacktraceClient will send reports when the debugger is connected.
Booleanfalse / NO
oomModeSpecifies how the SDK should handle OOM (Out-Of-Memory) detection. See OOM Detection Modes for details.

The options are:
  • .none (Swift) / BacktraceOomModeNone (Objective-C): Disables OOM detection.
  • .light (Swift) / BacktraceOomModeLight (Objective-C): Lightweight OOM report — current thread only, no symbolication.
  • .full (Swift) / BacktraceOomModeFull (Objective-C): Full OOM report — all threads, symbolicated.
BacktraceOomMode.none / BacktraceOomModeNone

Database Settings​

BacktraceClient allows you to customize the initialization of BacktraceDatabase for local storage of error reports by supplying a BacktraceDatabaseSettings parameter, as follows:

let backtraceCredentials = BacktraceCredentials(endpoint: URL(string: "https://backtrace.io")!, token: "token")
let backtraceDatabaseSettings = BacktraceDatabaseSettings()
backtraceDatabaseSettings.maxRecordCount = 1000
backtraceDatabaseSettings.maxDatabaseSize = 10
backtraceDatabaseSettings.retryInterval = 5
backtraceDatabaseSettings.retryLimit = 3
backtraceDatabaseSettings.retryBehaviour = RetryBehaviour.interval
backtraceDatabaseSettings.retryOrder = RetryOrder.queue
let backtraceConfiguration = BacktraceClientConfiguration(credentials: backtraceCredentials,
                                                          dbSettings: backtraceDatabaseSettings,
                                                          reportsPerMin: 10)
BacktraceClient.shared = try? BacktraceClient(configuration: backtraceConfiguration)

BacktraceDatabaseSettings​

Parameters​

SettingDescriptionTypeDefault
maxRecordCountThe target maximum number of stored records. Set to 0 for no record limit. See storage limits for temporary exceptions.Integer0
maxDatabaseSizeThe physical SQLite file-size target in MB, excluding attachments and other SDK files. Set to 0 for no size limit. See storage limits.Integer0
retryIntervalThe amount of time (in seconds) to wait before the next retry if unable to send a report.Integer5
retryLimitControls exhaustion of stored retry failures. Use retryBehaviour = .none to disable retries.Integer3
retryBehaviour.interval enables ordinary retries. .none disables them but still permits a pending native report's first submission attempt, subject to reportsPerMin.Enuminterval
retryOrderThe retry order if unable to send a report.

The options are:
  • queue: The oldest reports are sent first (FIFO).
  • stack: The newest reports are sent first (LIFO).
Enumqueue

See Cocoa Report Delivery for initial submission, retry classification, storage limits, and startup diagnostics.

PLCrashReporter​

BacktraceClient allows you to customize the configuration of the PLCrashReporter by injecting its instance as follows:

let backtraceCredentials = BacktraceCredentials(endpoint: URL(string: "https://backtrace.io")!, token: "token")
let backtraceConfiguration = BacktraceClientConfiguration(credentials: backtraceCredentials)
BacktraceClient.shared = try? BacktraceClient(
    configuration: backtraceConfiguration,
    crashReporter: BacktraceCrashReporter(config: PLCrashReporterConfig.defaultConfiguration()))
// or
BacktraceClient.shared = try? BacktraceClient(
    configuration: backtraceConfiguration,
    crashReporter: BacktraceCrashReporter(reporter: PLCrashReporter.shared()))

Custom Crash Directory​

By default, PLCrashReporter stores .plcrash files in the app's standard cache directory. You can specify a custom basePath to control the PLCrashReporter payload location, and set a FileProtectionType to manage file access when the device is locked.

The basePath controls only PLCrashReporter payloads; it does not relocate the Backtrace database or metadata, or migrate existing reports. File protection applied to this directory does not configure those other locations.

This is useful when you need crash reports to be accessible before the device is first unlocked (for example, if your app runs in the background or launches before user unlock).

// Create a custom directory with FileProtectionType.none
// so crash files are accessible even when the device is locked
let baseURL = try FileManager.default.url(
    for: .libraryDirectory,
    in: .userDomainMask,
    appropriateFor: nil,
    create: true)
let crashDir = baseURL.appendingPathComponent("btcrash", isDirectory: true)
try FileManager.default.createDirectory(
    at: crashDir,
    withIntermediateDirectories: true,
    attributes: [.protectionKey: FileProtectionType.none])

// Create a PLCrashReporterConfig with the custom basePath
guard let plcrashConfig = PLCrashReporterConfig(
    signalHandlerType: .BSD,
    symbolicationStrategy: .all,
    basePath: crashDir.path) else {
    fatalError("Could not create PLCrashReporterConfig")
}

let reporter = BacktraceCrashReporter(config: plcrashConfig)
BacktraceClient.shared = try? BacktraceClient(
    configuration: backtraceConfiguration,
    crashReporter: reporter)

Swift FileProtectionType Options​

Protection LevelDescription
.noneNo file protection. Files are accessible at all times, including before the first device unlock. Use this for crash directories if your app launches before unlock.
.completeFiles are inaccessible whenever the device is locked.
.completeUnlessOpenFiles can be created while locked but become protected once closed.
.completeUntilFirstUserAuthenticationFiles are accessible after the user unlocks the device for the first time after boot. This is the default for most app directories.
note

File protection level tests only work on physical devices — simulators do not enforce file protection.

Handling Events​

BacktraceClient allows you to subscribe to events produced before and after sending each report by attaching an object that follows the BacktraceClientDelegate protocol.

To observe pending-report delivery during startup, assign a retained delegate instance to configuration.delegate before creating the client. Assigning the client delegate only after initialization can miss those events. See Configure Startup Diagnostics.

// assign `self` or any other object as a `BacktraceClientDelegate`
BacktraceClient.shared?.delegate = self

// handle events
func willSend(_ report: BacktraceReport) -> BacktraceReport
func willSendRequest(_ request: URLRequest) -> URLRequest
func connectionDidFail(_ error: Error)
func serverDidRespond(_ result: BacktraceResult)
func didReachLimit(_ result: BacktraceResult)

For example, you can use BacktraceClientDelegate to modify a report before send:

func willSend(_ report: BacktraceReport) -> (BacktraceReport) {
    report.attributes["added"] = "just before send"
    return report
}

Attributes​

You can add custom attributes to send alongside every crash and error report:

BacktraceClient.shared?.attributes = ["foo": "bar", "testing": true]

You can also specify a unique set of attributes for a specific report with the willSend(_:) method of BacktraceClientDelegate.

File Attachments​

All Reports​

You can specify file attachments to send with every crash and error report. File attachments are specified as an array of URL that contain the path to the file.

guard let libraryDirectoryUrl = try? FileManager.default.url(
     for: .libraryDirectory, in: .userDomainMask, appropriateFor: nil, create: true) else {
     throw CustomError.runtimeError
}

let fileUrl = libraryDirectoryUrl.appendingPathComponent("sample.txt")

var crashAttachments = Attachments()
crashAttachments.append(fileUrl)

BacktraceClient.shared?.attachments = crashAttachments

Per Report​

You can specify file attachments to send for a specific report by supplying an array of file paths.

let filePath = Bundle.main.path(forResource: "test", ofType: "txt")!
BacktraceClient.shared?.send(attachmentPaths: [filePath]) { (result) in
    print(result)
}

You can also specify a unique set of files for specific reports with the willSend(_:) method of BacktraceClientDelegate.

Error-Free Metrics​

Error-free metrics allow you to determine:

  • How many of your unique users (i.e., unique device IDs) using your app are experiencing errors/crashes.
  • How many application sessions (i.e., individual application sessions from startup till shutdown/exit) of your app are experiencing errors/crashes.

You can track those metrics at-a-glance, as well as in detail to find out what kinds of errors/crashes are most common. For more information, see Stability Metrics Widgets.

Enabling Error-Free Metrics​

You can enable error-free metrics as follows:

Code Sample
loading...

iOS and macOS Only

Breadcrumbs allow you track events leading up to your crash, error, or other submitted object. When breadcrumbs are enabled, any captured breadcrumbs will automatically be attached as a file to your crash, error, or other submitted object (including native crashes).

Enabling Breadcrumbs​

You can enable breadcrumbs as follows:

Code Sample
loading...

Adding Manual Breadcrumbs​

You can add breadcrumbs as follows:

Code Sample
loading...
caution

We recommend that you do not make calls to addBreadcrumb from performance-critical code paths.

Automatic Breadcrumbs​

By default, if you enable breadcrumbs, Backtrace registers handlers to capture common iOS system events, such as low memory warnings, battery state, screen orientation changes, background/foreground/inactive changes, and more.

You can limit the types of automatic events that are captured by specifying which automatic breadcrumb types you want to enable. For example:

let settings = BacktraceBreadcrumbSettings()
settings.breadcrumbTypes = [BacktraceBreadcrumbType.system, BacktraceBreadcrumbType.configuration]

OOM Detection Modes​

The SDK provides configurable OOM (Out-Of-Memory) detection through the BacktraceOomMode enum. OOM detection monitors for low-memory pressure events and reports them to your Backtrace instance when the app is terminated due to memory pressure.

BacktraceOomMode​

ModeSwiftObjective-CDescription
None.noneBacktraceOomModeNoneOOM detection is disabled. No launch-time overhead.
Light.lightBacktraceOomModeLightLightweight OOM report. Captures only the current thread without symbolication. Minimal performance impact.
Full.fullBacktraceOomModeFullFull OOM report. Captures all threads with symbolication. Provides the most diagnostic detail but has higher overhead at launch.

Choosing the Right Mode​

Use CaseRecommended ModeRationale
Games and performance-critical apps.lightAvoids launch-time stalls from symbolication and thread enumeration. Games are especially sensitive to frame drops and launch latency.
Standard apps.fullProvides complete stack traces across all threads, making it easier to diagnose memory issues. The overhead at launch is acceptable for most apps.
Apps where launch time is critical.lightThe .light mode skips symbolication and runs on the current thread only, keeping launch fast.
OOM detection not needed.noneZero overhead. Use when OOM crashes are not a concern or are tracked through other means.

How It Works​

  • .light mode captures a snapshot of the current thread at the moment of the low-memory warning. It skips symbolication, so the report is fast to generate but contains less detail. If the lightweight capture fails, it automatically falls back to .full mode.
  • .full mode captures all threads with full symbolication. This runs on a dedicated background dispatch queue (com.backtrace.oom) to avoid blocking the main thread, but the I/O and symbolication work can still impact launch performance.
  • Both modes capture the resident memory footprint at the time of the low-memory warning.

Usage​

// Lightweight mode — recommended for games and performance-sensitive apps
let configuration = BacktraceClientConfiguration(
    credentials: backtraceCredentials,
    dbSettings: BacktraceDatabaseSettings(),
    reportsPerMin: 10,
    allowsAttachingDebugger: false,
    oomMode: .light)

// Full mode — recommended for standard apps that need complete diagnostics
let configuration = BacktraceClientConfiguration(
    credentials: backtraceCredentials,
    dbSettings: BacktraceDatabaseSettings(),
    reportsPerMin: 10,
    allowsAttachingDebugger: false,
    oomMode: .full)

Legacy API (detectOOM)​

The detectOOM boolean parameter is deprecated but still supported for backward compatibility. It maps to the new oomMode as follows:

Legacy detectOOMEquivalent oomMode
false (default).none
true.full
// Legacy API (deprecated) — still works but prefer oomMode
let configuration = BacktraceClientConfiguration(
    credentials: backtraceCredentials,
    dbSettings: BacktraceDatabaseSettings(),
    reportsPerMin: 10,
    allowsAttachingDebugger: false,
    detectOOM: true) // maps to oomMode: .full
note

The legacy detectOOM API does not support .light mode. To use lightweight OOM reporting, you must migrate to oomMode.