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

Swift

Usage Example

loading...

View on GitHub

Objective-C

Usage Example

loading...

View on GitHub

Advanced Usage

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

Swift

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)

Objective-C

BacktraceCredentials *credentials = [[BacktraceCredentials alloc]
                                     initWithEndpoint: [NSURL URLWithString: @"https://backtrace.io"]
                                     token: @"token"];

BacktraceClientConfiguration *configuration = [[BacktraceClientConfiguration alloc]
                                               initWithCredentials: credentials
                                               dbSettings: [[BacktraceDatabaseSettings alloc] init]
                                               reportsPerMin: 3
                                               allowsAttachingDebugger: NO
                                               oomMode: BacktraceOomModeFull];

BacktraceClient.shared = [[BacktraceClient alloc] initWithConfiguration: configuration error: nil];

BacktraceClientConfiguration

Parameters

Setting	Description	Type	Default
credentials (Swift) or initWithCredentials (Objective-C)	The BacktraceCredentials (endpoint URL and submission token) used to initialize the BacktraceClient.	Parameter
dbSettings	The BacktraceDatabaseSettings used to initialize the BacktraceDatabase.	Parameter
reportsPerMin	The maximum number of reports per minute that BacktraceClient will send.	Integer	30
allowsAttachingDebugger	Specifies whether to send reports when the debugger is connected. The options are: false (Swift) / NO (Objective-C): BacktraceClient will send reports when the debugger is connected. true (Swift) / YES (Objective-C): BacktraceClient won't send reports when the debugger is connected.	Boolean	false / NO
oomMode	Specifies 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:

Swift

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 = RetryOder.queue
let backtraceConfiguration = BacktraceClientConfiguration(credentials: backtraceCredentials,
                                                          dbSettings: backtraceDatabaseSettings,
                                                          reportsPerMin: 10)
BacktraceClient.shared = try? BacktraceClient(configuration: backtraceConfiguration)

Objective-C

BacktraceCredentials *credentials = [[BacktraceCredentials alloc]
                                     initWithEndpoint: [NSURL URLWithString: @"https://backtrace.io"]
                                     token: @"token"];

BacktraceDatabaseSettings *backtraceDatabaseSettings = [[BacktraceDatabaseSettings alloc] init];
backtraceDatabaseSettings.maxRecordCount = 1000;
backtraceDatabaseSettings.maxDatabaseSize = 10;
backtraceDatabaseSettings.retryInterval = 5;
backtraceDatabaseSettings.retryLimit = 3;
backtraceDatabaseSettings.retryBehaviour = RetryBehaviourInterval;
backtraceDatabaseSettings.retryOrder = RetryOderStack;

BacktraceClientConfiguration *configuration = [[BacktraceClientConfiguration alloc]
                                               initWithCredentials: credentials
                                               dbSettings: backtraceDatabaseSettings
                                               reportsPerMin: 3
                                               allowsAttachingDebugger: NO];

BacktraceClient.shared = [[BacktraceClient alloc] initWithConfiguration: configuration error: nil];

BacktraceDatabaseSettings

Parameters

Setting	Description	Type	Default
maxRecordCount	The maximum number of records stored in the database. If set to '0', then there is no record limit.	Integer	0
maxDatabaseSize	The maximum size of the database in MB. If set to '0', then there is no size limit.	Integer	0
retryInterval	The amount of time (in seconds) to wait before the next retry if unable to send a report.	Integer	5
retryLimit	The maximum number of retries to attempt if unable to send a report.	Integer	3
retryBehaviour	The retry behaviour if unable to send a report. The options are: interval: If unable to send a report, the database will retry based on the retryInterval. none: If unable to send a report, the database will not retry.	Enum	interval
retryOrder	The 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).	Enum	queue

PLCrashReporter

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

Swift

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

Objective-C

BacktraceCredentials *credentials = [[BacktraceCredentials alloc]
                                     initWithEndpoint: [NSURL URLWithString: @"https://backtrace.io"]
                                     token: @"token"];

BacktraceClientConfiguration *configuration = [[BacktraceClientConfiguration alloc]
                                                initWithCredentials: credentials];

BacktraceClient.shared = [[BacktraceClient alloc]
                            initWithConfiguration: configuration
                            crashReporter: [[BacktraceCrashReporter alloc] initWithConfig: PLCrashReporterConfig.defaultConfiguration]
                            error: nil];

// or
BacktraceClient.shared = [[BacktraceClient alloc]
                            initWithConfiguration: configuration
                            crashReporter: [[BacktraceCrashReporter alloc] initWithReporter: PLCrashReporter.sharedReporter]
                            error: nil];

Custom Crash Directory

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

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

Swift

// 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 Level	Description
.none	No 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.
.complete	Files are inaccessible whenever the device is locked.
.completeUnlessOpen	Files can be created while locked but become protected once closed.
.completeUntilFirstUserAuthentication	Files are accessible after the user unlocks the device for the first time after boot. This is the default for most app directories.

Objective-C

// Create a custom directory with NSFileProtectionNone
NSError *error = nil;
NSURL *libraryUrl = [[NSFileManager defaultManager] URLForDirectory:NSLibraryDirectory
                                                           inDomain:NSUserDomainMask
                                                  appropriateForURL:nil
                                                             create:YES
                                                              error:&error];
NSURL *crashDir = [libraryUrl URLByAppendingPathComponent:@"btcrash" isDirectory:YES];
[[NSFileManager defaultManager] createDirectoryAtURL:crashDir
                         withIntermediateDirectories:YES
                                          attributes:@{NSFileProtectionKey: NSFileProtectionNone}
                                               error:&error];

// Create a PLCrashReporterConfig with the custom basePath
PLCrashReporterConfig *plcrashConfig = [[PLCrashReporterConfig alloc]
    initWithSignalHandlerType: PLCrashReporterSignalHandlerTypeBSD
        symbolicationStrategy: PLCrashReporterSymbolicationStrategyAll
                     basePath: crashDir.path];

BacktraceCrashReporter *reporter = [[BacktraceCrashReporter alloc] initWithConfig: plcrashConfig];
BacktraceClient.shared = [[BacktraceClient alloc]
                            initWithConfiguration: configuration
                            crashReporter: reporter
                            error: nil];

Objective-C FileProtectionType Options

Protection Level	Description
NSFileProtectionNone	No 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.
NSFileProtectionComplete	Files are inaccessible whenever the device is locked.
NSFileProtectionCompleteUnlessOpen	Files can be created while locked but become protected once closed.
NSFileProtectionCompleteUntilFirstUserAuthentication	Files are accessible after the user unlocks the device for the first time after boot. This is the default for most app directories.
NSFileProtectionCompleteWhenUserInactive	(iOS 17+) Files 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.

Swift

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

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

Objective-C

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

//handle events
- (BacktraceReport *) willSend: (BacktraceReport *)report;
- (void) serverDidFail: (NSError *)error;
- (void) serverDidRespond: (BacktraceResult *)result;
- (NSURLRequest *) willSendRequest: (NSURLRequest *)request;
- (void) didReachLimit: (BacktraceResult *)result;

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

Swift

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

Objective-C

- (BacktraceReport *)willSend:(BacktraceReport *)report {
    NSMutableDictionary *dict = [report.attributes mutableCopy];
    [dict setObject: @"just before send" forKey: @"added"];
    report.attributes = dict;
    return report;
}

Attributes

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

Swift

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

Objective-C

BacktraceClient.shared.attributes = @{@"foo": @"bar", @"testing": @YES};

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.

Swift

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

Objective-C

NSString *fileName = @"myCustomFile.txt";
NSURL *libraryUrl = [[[NSFileManager defaultManager] URLsForDirectory:NSLibraryDirectory
         inDomains:NSUserDomainMask] lastObject];
NSURL *fileUrl = [libraryUrl URLByAppendingPathComponent:fileName];

BacktraceClient.shared.attachments = [NSArray arrayWithObjects:fileUrl, nil];

Per Report

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

Swift

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

Objective-C

NSArray *paths = @[[[NSBundle mainBundle] pathForResource: @"test" ofType: @"txt"]];
[[BacktraceClient shared] sendWithAttachmentPaths:paths completion:^(BacktraceResult * _Nonnull result) {
    NSLog(@"%@", 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:

Swift

Code Sample

loading...

View on GitHub

Objective-C

Code Sample

loading...

View on GitHub

Breadcrumbs

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:

Swift

Code Sample

loading...

View on GitHub

Objective-C

Code Sample

[BacktraceClient.shared enableBreadCrumbs];

Adding Manual Breadcrumbs

You can add breadcrumbs as follows:

Swift

Code Sample

loading...

View on GitHub

Objective-C

Code Sample

loading...

View on GitHub

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:

Swift

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

Objective-C

BacktraceBreadcrumbSettings *settings = [[BacktraceBreadcrumbSettings alloc]
                                             init:4096
                                             maxQueueFileSizeBytes: 64 * 1024
                                             breadcrumbLogFileName:@"bt-breadcrumbs-0"
                                             breadcrumbTypes:@[[NSNumber numberWithInt:BacktraceBreadcrumbTypeManual],
                                                               [NSNumber numberWithInt:BacktraceBreadcrumbTypeLog]]
                                             breadcrumbLevel:BacktraceBreadcrumbLevelInfo];

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

Mode	Swift	Objective-C	Description
None	.none	BacktraceOomModeNone	OOM detection is disabled. No launch-time overhead.
Light	.light	BacktraceOomModeLight	Lightweight OOM report. Captures only the current thread without symbolication. Minimal performance impact.
Full	.full	BacktraceOomModeFull	Full OOM report. Captures all threads with symbolication. Provides the most diagnostic detail but has higher overhead at launch.

Choosing the Right Mode

Use Case	Recommended Mode	Rationale
Games and performance-critical apps	.light	Avoids launch-time stalls from symbolication and thread enumeration. Games are especially sensitive to frame drops and launch latency.
Standard apps	.full	Provides 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	.light	The .light mode skips symbolication and runs on the current thread only, keeping launch fast.
OOM detection not needed	.none	Zero 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

Swift

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

Objective-C

// Lightweight mode — recommended for games and performance-sensitive apps
BacktraceClientConfiguration *configuration = [[BacktraceClientConfiguration alloc]
                                               initWithCredentials: credentials
                                               dbSettings: [[BacktraceDatabaseSettings alloc] init]
                                               reportsPerMin: 10
                                               allowsAttachingDebugger: NO
                                               oomMode: BacktraceOomModeLight];

// Full mode — recommended for standard apps that need complete diagnostics
BacktraceClientConfiguration *configuration = [[BacktraceClientConfiguration alloc]
                                               initWithCredentials: credentials
                                               dbSettings: [[BacktraceDatabaseSettings alloc] init]
                                               reportsPerMin: 10
                                               allowsAttachingDebugger: NO
                                               oomMode: BacktraceOomModeFull];

Legacy API (detectOOM)

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

Legacy detectOOM	Equivalent oomMode
false (default)	.none
true	.full

Swift

// 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

Objective-C

// Legacy API (deprecated) — still works but prefer oomMode
BacktraceClientConfiguration *configuration = [[BacktraceClientConfiguration alloc]
                                               initWithCredentials: credentials
                                               dbSettings: [[BacktraceDatabaseSettings alloc] init]
                                               reportsPerMin: 3
                                               allowsAttachingDebugger: NO
                                               detectOOM: TRUE]; // maps to oomMode: BacktraceOomModeFull

note

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