NOTE: While Backtrace fully supports using the base PLCrashReporter library, we also provide a custom built backtrace-cococa library to simplify the integration and submission of errors to Backtrace. Read more in the iOS Integration Guide.
PLCrashReporter is an open source project maintained by Microsoft (previously, Plausible Labs). It is MIT licensed with some libraries such as Protocol Buffers covered under the Apache License. It can be integrated to Objective-C and Swift applications to retrieve crash information on MacOS and iOS platforms. The source code is available on the GitHub mirror.
Once PLCrashReporter is integrated into your application, it can generate Crash Reports. These Crash Reports can be uploaded to Backtrace, which provides a central location for developers to triage, prioritize and debug crashes that occur in production and development environments.
This article will discuss how to integrate and send PLCrashReports to Backtrace.
Integration
Integration of PLCrashReporter is straightforward. Code examples are provided on the PLCrashReporter website.
In essence, the following snippet in Objective-C enables PLCrashReporter for the application.
PLCrashReporterConfig *config = [PLCrashReporterConfig defaultConfiguration];
PLCrashReporter *reporter = [[PLCrashReporter alloc] initWithConfiguration: config];
[reporter enableCrashReporter];
For the code to compile you need to link to the CrashReporter framework.
This is a minimal example. For production use, it is recommended to add include error checking, for example by using enableCrashReporterAndReturnError.
PLCrashReports will be stored in the ~/Library/Caches/com.plausiblelabs.crashreporter.data/
Managing PLCrashReports
PLCrashReporter helps managing existing crash reports. This allows an application developer to check for pending crash reports as soon as the application starts up to allow acting upon them.
To do so, the PLCrashReporter class provides instance methods to check for pending crash reports - hasPendingCrashReport - as well as loadPendingCrashReportData. The provided code snippet allows to check for pending crash reports on start up and calling a function - submit - on it, which will send the data to the backtrace servers.
if ([reporter hasPendingCrashReport]) {
NSdata *crash = [reporter loadPendingCrashReportData];
upload(crash);
}
Upload Methods
PLCrashReporter doesn’t support any upload methods directly natively. The API merely provides callbacks to retrieve prior crashes and allows a developer to upload those themselves. Using the Foundation Classes this might look as follows:
static void upload(NSData *crash) {
NSURL *url = [NSURL URLWithString:@"https://instance.sp.backtrace.io:6098/post?format=plcrash&token=xxxxxxxxxxxxxxxxxxxxxxx"];
NSMutableURLRequest *req = [NSMutableURLRequest requestWithURL: url];
NSHTTPURLResponse *res = nil;
NSError *err = nil;
[req setHTTPMethod: @"POST"];
[req setHTTPBody: crash];
[NSURLConnection sendSynchronousRequest:req returningResponse:&res error:&err];
}
After a successful transmission you can purge the pending download:
[reporter purgePendingCrashReport];
At this point, you can check again for pending crash reports and upload any other queued crashes from your system.
System Level Attributes
When you open the Crash Report in Backtrace's Web Debugger, you'll notice that in addition to the Callstack, system level attributes, such as process uptime, memory usage, CPU, and OS details have been extracted and are available for you to review.
Adding Custom Attributes
In addition to the system level attributes, custom user-defined attributes, such as graphic card driver, application mode, or version information, can be associated with the PLCrashReport. This instance-level attribution provides contextual data points to support investigating root cause.
Custom attributes have to be created in the Backtrace project's settings. See the Attributes article for more information about how to configure Backtrace to index those incoming attributes appropriately. Once indexed, they will be available for filter, group and aggregate operations in the web and morgue tool.
The submission process can attach the key value attributes to the URL during submission, e.g. in this case a dictionary value my_custom_attribute with a value of sample_string
Uploading File Attachments
Backtrace also accepts generic file attachments, such as log or configuration files, to be associated to a crash. This additional contextual information can be invaluable during debugging as the engineers are looking to see what happened in the recent past, and what additional configurations might be set. See the File Attachments article for more details on how to submit an attachment using HTTP submission.
Manage Symbols
During compilation of MacOS application the compiler generates a directory with dSYM information of the project. To allow backtrace to symbolicate the backtrace, it is necessary to upload dSYM information. The easiest approach is to create an archive in tar or zip format of the dSYM directory and upload it via the morgue command line tool or use the web interface functionality in the project's settings.
Additionally it is possible to generate the necessary sym files by using breakpad's dump_syms(_mac) tools. They can be uploaded by the usual means as well.
More information on how to do so is available in the symbolication guide.