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
- Objective-C
loading...
loading...
Advanced Usage
For more advanced usage of BacktraceClient, you can supply BacktraceClientConfiguration as a parameter. See the following example:
- Swift
- Objective-C
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)
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:
| Boolean | false / NO |
oomMode | Specifies how the SDK should handle OOM (Out-Of-Memory) detection. See OOM Detection Modes for details. The options are:
| 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
- Objective-C
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)
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:
| Enum | interval |
retryOrder | The retry order if unable to send a report. The options are:
| Enum | queue |
PLCrashReporter
BacktraceClient allows you to customize the configuration of the PLCrashReporter by injecting its instance as follows:
- Swift
- Objective-C
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()))
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
- Objective-C
// 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. |
// 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. |
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
- Objective-C
// 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)
// 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
- Objective-C
func willSend(_ report: BacktraceReport) -> (BacktraceReport) {
report.attributes["added"] = "just before send"
return report
}
- (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
- Objective-C
BacktraceClient.shared?.attributes = ["foo": "bar", "testing": true]
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
- Objective-C
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
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
- Objective-C
let filePath = Bundle.main.path(forResource: "test", ofType: "txt")!
BacktraceClient.shared?.send(attachmentPaths: [filePath]) { (result) in
print(result)
}
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
- Objective-C
loading...
loading...
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
- Objective-C
loading...
[BacktraceClient.shared enableBreadCrumbs];
Adding Manual Breadcrumbs
You can add breadcrumbs as follows:
- Swift
- Objective-C
loading...
loading...
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
- Objective-C
let settings = BacktraceBreadcrumbSettings()
settings.breadcrumbTypes = [BacktraceBreadcrumbType.system, BacktraceBreadcrumbType.configuration]
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
.lightmode 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.fullmode..fullmode 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
- Objective-C
// 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)
// 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
- Objective-C
// 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
// 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
The legacy detectOOM API does not support .light mode. To use lightweight OOM reporting, you must migrate to oomMode.