PLCrashReporter is a reliable open source library that provides an in-process live crash reporting framework for use on iOS, macOS and tvOS. The library detects crashes and generates reports to help your investigation and troubleshooting with the information of application, system, process, thread, etc. as well as stack traces.
The easiest way to use PLCrashReporter is by using AppCenter. However, if you want to use PLCrashReporter directly, grab the latest release at releases page.
Crash reports are output as protobuf-encoded messages, and may be decoded using the CrashReporter library or any Google Protocol Buffers decoder.
In addition to the in-library decoding support, you may use the included plcrashutil
binary to convert crash reports to apple's standard iPhone text format:
plcrashutil convert --format=iphone example_report.plcrash
You can use atos
command-line tool to symbolicate the output. For more information about this tool, see Adding Identifiable Symbol Names to a Crash Report.
Future library releases may include built-in re-usable formatters, for outputting alternative formats directly from the phone.
PLCrashReporter can be added to your app via CocoaPods, Carthage, Swift Package Manager, or by manually adding the binaries to your project.
Podfile
:
pod 'PLCrashReporter'
pod install
to install your newly defined pod and open the project's .xcworkspace
.Cartfile
:
github "microsoft/plcrashreporter"
carthage update --use-xcframeworks
to fetch dependencies.Frameworks, Libraries and Embedded Content
section. For iOS and tvOS, set Embed
to Do not embed
. For macoS, set Embed
to Embed and Sign
.NOTE: Carthage integration doesn't build the dependency correctly in Xcode 12 with flag "--no-use-binaries" or from a specific branch. To make it work, refer to this instruction.
NOTE: PLCrashReporter xcframework contains static binaries for iOS and tvOS, and dynamic binaries for macOS. When adding the framework to your project make sure that in
Frameworks, Libraries and Embedded Content
sectionEmbed
is selected toDo not embed
for iOS and tvOS andEmbed and Sign
for macOS.PLCrashReporter-Static-{version}.zip
is an exception - it contains static frameworks for all platforms.
The following example shows a way how to initialize crash reporter. Please note that enabling in-process crash reporting will conflict with any attached debuggers so make sure the debugger isn't attached when you crash the app.
@import CrashReporter;
...
// Uncomment and implement isDebuggerAttached to safely run this code with a debugger.
// See: https://github.com/microsoft/plcrashreporter/blob/2dd862ce049e6f43feb355308dfc710f3af54c4d/Source/Crash%20Demo/main.m#L96
// if (![self isDebuggerAttached]) {
// It is strongly recommended that local symbolication only be enabled for non-release builds.
// Use PLCrashReporterSymbolicationStrategyNone for release versions.
PLCrashReporterConfig *config = [[PLCrashReporterConfig alloc] initWithSignalHandlerType: PLCrashReporterSignalHandlerTypeMach
symbolicationStrategy: PLCrashReporterSymbolicationStrategyAll];
PLCrashReporter *crashReporter = [[PLCrashReporter alloc] initWithConfiguration: config];
// Enable the Crash Reporter.
NSError *error;
if (![crashReporter enableCrashReporterAndReturnError: &error]) {
NSLog(@"Warning: Could not enable crash reporter: %@", error);
}
// }
Checking collected crash report can be done in the following way:
if ([crashReporter hasPendingCrashReport]) {
NSError *error;
// Try loading the crash report.
NSData *data = [crashReporter loadPendingCrashReportDataAndReturnError: &error];
if (data == nil) {
NSLog(@"Failed to load crash report data: %@", error);
return;
}
// Retrieving crash reporter data.
PLCrashReport *report = [[PLCrashReport alloc] initWithData: data error: &error];
if (report == nil) {
NSLog(@"Failed to parse crash report: %@", error);
return;
}
// We could send the report from here, but we'll just print out some debugging info instead.
NSString *text = [PLCrashReportTextFormatter stringValueForCrashReport: report withTextFormat: PLCrashReportTextFormatiOS];
NSLog(@"%@", text);
// Purge the report.
[crashReporter purgePendingCrashReport];
}
import CrashReporter
...
// Uncomment and implement isDebuggerAttached to safely run this code with a debugger.
// See: https://github.com/microsoft/plcrashreporter/blob/2dd862ce049e6f43feb355308dfc710f3af54c4d/Source/Crash%20Demo/main.m#L96
// if (!isDebuggerAttached()) {
// It is strongly recommended that local symbolication only be enabled for non-release builds.
// Use [] for release versions.
let config = PLCrashReporterConfig(signalHandlerType: .mach, symbolicationStrategy: .all)
guard let crashReporter = PLCrashReporter(configuration: config) else {
print("Could not create an instance of PLCrashReporter")
return
}
// Enable the Crash Reporter.
do {
try crashReporter.enableAndReturnError()
} catch let error {
print("Warning: Could not enable crash reporter: \(error)")
}
// }
Checking collected crash report can be done in the following way:
// Try loading the crash report.
if crashReporter.hasPendingCrashReport() {
do {
let data = try crashReporter.loadPendingCrashReportDataAndReturnError()
// Retrieving crash reporter data.
let report = try PLCrashReport(data: data)
// We could send the report from here, but we'll just print out some debugging info instead.
if let text = PLCrashReportTextFormatter.stringValue(for: report, with: PLCrashReportTextFormatiOS) {
print(text)
} else {
print("CrashReporter: can't convert report to text")
}
} catch let error {
print("CrashReporter failed to load and parse with error: \(error)")
}
}
// Purge the report.
crashReporter.purgePendingCrashReport()
Also, next optional tools are used to build additional resources:
protobuf-c
to convert Protocol Buffer .proto
files to C descriptor code. See the official protobuf-c repository for more information or use Homebrew to install it.Open a new window for your Terminal.
Go to PLCrashReporter's root folder and run
xcodebuild -configuration Release -target 'CrashReporter'
to create binaries for all platforms.
We are looking forward to your contributions via pull requests.
To contribute to PLCrashReporter, you need the tools mentioned above to build PLCrashReporter for all architectures and protobuf-c
to convert Protocol Buffer .proto
files to C descriptor code.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
link |
Stars: 2756 |
Last commit: 2 weeks ago |
Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics