Reporting Crashes
Covered here are APIs relevant to crash reporting for your iOS app.
Privacy Policy
It is highly recommended to mention in your privacy policy that you may be collecting logging data in order to assist with troubleshooting crashes.
There are two ways to have your application report a crash; either automatically or manually. After the crash is sent to your dashboard, you can easily sort and filter for specific crashes.
Automatic Crash Reporting
If you enable Crash Reporting, crashes will automatically be reported to and viewable from the crashes page of your Instabug dashboard.
You'll also see the trends covering the previous 7 days for the percentage of crash-free sessions (sessions that ran and concluded without any fatal errors), the total number of crashing sessions, the total number of sessions, and the total number of unique affected users. You can also see the total number of occurrences, the total number of fatal sessions, the total number of OOMs, and the total number of non-fatal errors. If there is a sharp decline in the crash-free sessions rate, an email will be sent to notify you.

This is the crashes page of the Instabug dashboard.
C++ Crashes
The Instabug SDK also supports and captures C++ crashes.
Out of Memory Crashes
By default, if Crash Reporting is enabled, Instabug captures OOM crashes, however, the crashes will not contain a stack trace and will only be captured if they happen while the app is in the foreground.
You can disable/enable capturing OOM crashes using the following API:
CrashReporting.OOMEnabled = false
IBGCrashReporting.OOMEnabled = NO
User Terminations
Starting from SDK version 11.1.0, Instabug automatically reports User Terminations. A User Termination is when a user force terminates your application and re-launches it within 5 seconds, which could indicate performance issues.
Please note that User Termination reports will not contain a stack trace.
App Hangs
Starting SDK version 10.13.0
, Instabug automatically reports App Hangs. An App Hang is captured when the main thread is blocked for more than 3 seconds. App Hangs that last more than 3 seconds are considered severe and are likely to cause user frustration. They are reported along with a stack trace for debugging.
Warning
Crash reporting will not function correctly if the device is connected to Xcode. When it is, Xcode catches all exceptions and they will not be sent to your dashboard.
Manual Crash Reporting
You can use the following method and API to manually report any error or exception that you handle in your code and assign it a severity level.
Report Exception
To report exceptions manually, use the following method:
CrashReporting.report(exception)
[IBGCrashReporting reportException:exception];
Adding Level to Exception
You can set different levels for manually reported exceptions using the following API:
let exception = NSException(name: NSExceptionName("some_exception"), reason: "Exception reason")
if let nonFatalException = CrashReporting.exception(exception) {
nonFatalException.userAttributes = [
"hello" : "world"
]
nonFatalException.groupingString = "com.service.method.some_exception"
nonFatalException.level = .critical
nonFatalException.report()
}
NSException *exception = [NSException exceptionWithName:@"some_exception" reason:@"Exception reason" userInfo:nil];
IBGNonFatalException *nonFatalException = [IBGCrashReporting exception:exception];
nonFatalException.userAttributes = @{
@"hello" : @"world"
};
nonFatalException.groupingString = @"com.service.method.some_exception";
nonFatalException.level = IBGNonFatalLevelWarning;
[nonFatalException report];
Here are the different severity levels available. In case no level is indicated, the default level would be error
warning
error
critical
info
IBGNonFatalLevelWarning
IBGNonFatalLevelError
IBGNonFatalLevelCritical
IBGNonFatalLevelInfo
Report Errors
To report errors manually, use the following method:
let error = NSError(domain: "domain", code: 500, userInfo: nil)
CrashReporting.reportError(error)
NSError *error = [[NSError alloc] initWithDomain:@"domain" code:500 userInfo:nil];
[IBGCrashReporting reportError:error];
Adding Level to Error
You can set different levels for manually reported exceptions using the following API:
let error = NSError(domain: "com.service.method", code: 404)
if let nonFatalError = CrashReporting.error(error) {
nonFatalError.userAttributes = [
"hello" : "world"
]
nonFatalError.groupingString = "com.service.method.404"
nonFatalError.level = .critical
nonFatalError.report()
}
NSError *error = [NSError errorWithDomain:@"com.service.method" code:404 userInfo:nil];
IBGNonFatalError *nonFatalError = [IBGCrashReporting error:error];
nonFatalError.userAttributes = @{
@"hello" : @"world"
};
nonFatalError.groupingString = @"com.service.method.404";
nonFatalError.level = IBGNonFatalLevelWarning;
[nonFatalError report];
Here are the different severity levels available. In case no level is indicated, the default level would be error
warning
error
critical
info
IBGNonFatalLevelWarning
IBGNonFatalLevelError
IBGNonFatalLevelCritical
IBGNonFatalLevelInfo
Set Stack Trace Mode
Performance Improvements
On average, it takes 5ms less to capture a stack trace while using
CallerThreadOnly
.
In the events that you manually report a high number of non-fatal crashes, you may want to report only the calling threads in order to further optimize performance. You can use the below APIs to set the stack trace mode you want to capture.
if let nonFatal = CrashReporting.error(error) {
nonFatal.stackTraceMode = .callerThreadOnly
nonFatal.report()
}
IBGNonFatalError *nonFatal = [IBGCrashReporting error:error];
nonFatal.stackTraceMode = IBGNonFatalStackTraceModeCallerThreadOnly
Below are the different modes available:
.full //default
.callerThreadOnly
IBGNonFatalStackTraceModeFull //default
IBGNonFatalStackTraceModeCallerThreadOnly
Grouping
When an already existing crash occurs once more for any user, that crash is reported as an occurrence in the original entry. However, in order to calculate whether a crash already exists and needs to be grouped, Instabug generates a fingerprint based on attributes used in the grouping logic.
The default Instabug grouping algorithm uses a mix of the exception and stack trace information. In some cases, you might want to change how the issues are grouped together using custom grouping or fingerprints.
Custom Grouping
Required dSYM Files
Please note that in order for custom grouping to be applied, dSYM files are required to be uploaded first; otherwise, default grouping will be applied. For more information on uploading dSYM files, please visit the symbolication page.
One way to customize how crashes are grouped together is by providing Instabug with packages that you would like us to ignore from our default grouping logic. If you define a package to be ignored, Instabug will skip the frame with that package and move on to find the next one that is not on your ignored list. This is done on an application level by going to your Application → Settings → Custom Crash Grouping.
Expected Input:
- Path
- Binary Image
Paths will be evaluated on a starts with basis, while Binary Images will be evaluated on an equality basis.
Examples:
-
Path =
Instabug
-- Ignores =Instabug
,Instabug/CrashReporting
,Instabug/APM
-
Path =
Instabug/APM
-- Ignores =Instabug/APM
,Instabug/APM/AppLaunch
-- Doesn't Ignore =Instabug
,Instabug/CrashReporting
-
Binary Image =
BinaryImage
-- Ignores =BinaryImage
-- Doesn't Ignore =BinaryImage2
,Binaryimage
Sample Stack Trace:
libobic.A.dylib foreach_realized_class(bool (objc_class*) block_pointer) + 123
CoreFoundation. -__NSSingleObjectArraylenumerateObjectsWithOptions:usingBlock:] + 11
ThirdParty -[LoggerManager LogArray:] + 80
Myapp - ViewController tableView:didSelectRowAtindexPath:
UIKitCore -[UIKBUndoStateHUD initWithKeyboardAppearance:] + 4171
Myapp _main
-
Without custom grouping, Instabug would group the crash based on
ThirdParty -[LoggerManager LogArray:] + 80
since it's the first non-system frame -
With custom grouping while ignoring path
home/files/ThirdParty/
and binary imageThirdParty
, we will skip the first frameThirdParty -[LoggerManager LogArray:] + 80
, and the crash will be grouped based onMyapp - ViewController tableView:didSelectRowAtindexPath:
.
Custom Fingerprinting
Overriding the default grouping
Please note that using custom fingerprinting will override Instabug's default grouping by sending a fingerprint string.
In the event that you'd like to report the exception manually with a custom grouping fingerprint in mind, you can use the below APIs to do just that.
CrashReporting.reportError(error, withGroupingString: "grouping string")
CrashReporting.report(exception, withGroupingString: "grouping string")
[IBGCrashReporting reportException:exception groupingString:@"grouping string"];
[IBGCrashReporting reportError:error groupingString:@"grouping string"];
Crashes List
This section contains a list of all the crashes that have been reported by your application. The title of each crash is usually the most significant line in the stack trace.

An example of the list of crashes in the crashes page of the Instabug dashboard.
Next to each crash in the list, you can find the following details, all of which can be used to sort the crashes:
- Occurrences: The number of times this crash has occurred and a bar graph representing its occurrences over the past seven days.
- Users: The number of users affected by this crash.
- Min ver.: The oldest app version that was affected by this crash.
- Max ver.: The latest app version that was affected by this crash.
- Last seen: The last time an occurrence of this crash was reported.
You can then filter for crashes that match any of the following criteria:
- App version
- Date
- Device
- OS
- User attributes
- Type
- Status
- Assignee
- Team
- Tags
- Current view
- Experiments
Updated 5 days ago