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,
detectOOM: true)
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 maximum number of reports per minute that BacktraceClient will send.Integer30
allowsAttachingDebuggerSpecifies 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.
Booleanfalse / NO
detectOOMSpecifies whether to detect and send reports for out of memory (OOM) crashes.

The options are:
  • false (Swift) / FALSE (Objective-C): BacktraceClient won't detect or send reports for out of memory (OOM) crashes.
  • true (Swift) / TRUE (Objective-C): BacktraceClient will detect and send reports for out of memory (OOM) crashes.
Booleanfalse / 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:

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)

BacktraceDatabaseSettings

Parameters

SettingDescriptionTypeDefault
maxRecordCountThe maximum number of records stored in the database. If set to '0', then there is no record limit.Integer0
maxDatabaseSizeThe maximum size of the database in MB. If set to '0', then there is no size limit.Integer0
retryIntervalThe amount of time (in seconds) to wait before the next retry if unable to send a report.Integer5
retryLimitThe maximum number of retries to attempt if unable to send a report.Integer3
retryBehaviourThe 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.
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

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

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.

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

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]