Docs Platforms macOS Legacy Handled exceptions
bugsnag.com Start Free Trial

Reporting handled exceptions

This documentation is for version 5 of the BugSnag macOS notifier. We recommend upgrading to the latest release using our Upgrade guide. Documentation for the current release can be found here.

In order to quickly understand and fix some errors, it is often helpful to send additional diagnostic data which is specific to that error.

The notify and notifyError functions accept a block to modify the error report using a representation of the report which will be sent. Below are the available options for modifying the report.

The report object

context

Set the context of the error report. This is normally the location of the error and should be populated automatically. Context is displayed in the dashboard prominently.

[Bugsnag notify:exception block:^(BugsnagCrashReport *report) {
    report.context = @"XYZMenuController";
}];

Bugsnag.notifyError(error) { report in
    report.context = "XYZMenuController"
}

depth

Set the number of frames discarded at the top of the stacktrace. By default, this value is the number of frames within BugSnag’s library, but you can increase this number particularly if you have a single place to log errors and/or exceptions and wish to avoid grouping in that function. This field only affects generated stacktraces. Stacktraces are generated for NSError instances and NSExceptions which have not been thrown.

void logError(NSError *error) {
    [Bugsnag notifyError:error block:^(BugsnagCrashReport *report) {
        // Increment the number of stackframes to discard
        report.depth += 1;
    }];
}

func logError(err: NSError) {
    Bugsnag.notifyError(err) { report in
        // Increment the number of stackframes to discard
        report.depth += 1
    }
}

errorClass

The type of the error which generated the report. This should be populated automatically with the class name of the error.

[Bugsnag notify:exception block:^(BugsnagCrashReport *report) {
    report.errorClass = @"Authentication failed";
}];

Bugsnag.notifyError(error) { report in
    report.errorClass = "Authentication failed"
}

errorMessage

The message or description of the error which generated the report.

[Bugsnag notify:exception block:^(BugsnagCrashReport *report) {
    report.errorMessage = @"Username rejected by the auth server";
}];

Bugsnag.notifyError(error) { report in
    report.errorMessage = "Username rejected by the auth server"
}

groupingHash

Sets the grouping hash of the error report. All errors with the same grouping hash are grouped together. This is an advanced usage of the library and mis-using it will cause your errors not to group properly in your dashboard.

[Bugsnag notify:exception block:^(BugsnagCrashReport *report) {
    report.groupingHash = @"unexpected-auth-failures";
}];

Bugsnag.notifyError(error) { report in
    report.groupingHash = "unexpected-auth-failures"
}

metaData

The metaData property is mapped to the metadata tabs on a reports in the Bugsnag dashboard. Each top level key indicates an additional tab. To attach additional diagnostic data to a report, use the addMetadata method, which merges added data into the existing metadata in a report.

[Bugsnag notify:exception block:^(BugsnagCrashReport *report) {
    NSDictionary *meals = @{
        @"breakfast": @"toast and eggs",
        @"lunch": @"hamburger"
    };
    [report addMetadata:meals toTabWithName:@"meals"];
    // use addAttribute:withValue:toTabWithName: to add an individual value
    [report addAttribute:@"dessert" withValue:@"cake" toTabWithName:@"meals"];
}];

Bugsnag.notifyError(error) { report in
    let meals = ["breakfast": "eggs and toast",
                 "lunch": "hamburger"]
    report.addMetadata(meals, toTabWithName: "food")
    // use addAttribute() to add an individual value
    report.addAttribute("dessert", withValue: "cake", toTabWithName: "meals");
}

To edit and remove diagnostic data included in a report, edit the metaData property directly.

[Bugsnag notify:exception block:^(BugsnagCrashReport *report) {
    NSMutableDictionary *metadata = report.metaData.mutableCopy;
    NSMutableDictionary *supportInfo = [metadata[@"support-info"] mutableCopy];
    [food removeObjectForKey:@"password"];
    metadata[@"support-info"] = food;
    report.metaData = metadata;
}];

Bugsnag.notifyError(error) { report in
    if var metadata = report.metaData as? [String: [String: Any]] {
        if var supportInfo = metadata["support-info"] {
            supportInfo.removeValue(forKey: "password")
            metadata["support-info"] = supportInfo
        }
        report.metaData = metadata
    }
}

releaseStage

The stage of development of the application currently running.

[Bugsnag notify:exception block:^(BugsnagCrashReport *report) {
    report.releaseStage = @"beta-group-23";
}];

Bugsnag.notifyError(error) { report in
    report.releaseStage = "beta-group-23"
}

severity

A rating of how critical an error report is.

[Bugsnag notify:exception block:^(BugsnagCrashReport *report) {
    report.severity = BSGSeverityError;
}];

Bugsnag.notifyError(error) { report in
    report.severity = .error;
}