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,
detectOOM: true)
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
detectOOM: TRUE];
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 |
detectOOM | Specifies whether to detect and send reports for out of memory (OOM) crashes. The options are:
| Boolean | false / FALSE |
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];
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];