Advanced Usage

Capturing uncaught exceptions on macOS

By default, MacOS applications do not crash whenever an uncaught exception occurs. To enable this with Sentry:

• Open the application's Info.plist file
• Search for Principal class (the entry is expected to be NSApplication)
• Replace NSApplication with SentryCrashExceptionApplication

Dealing with Scopes

There are three different ways to interact with Scopes in the SDK. Either using configureScope, passing a scope or using the scope callback.

configureScope

Using SentrySDK:configureScope lets you set context data globally, which will be attached to all future events.

import Sentry

SentrySDK.configureScope { scope in
    scope.setTag(value: "my-tag", key: "my value")
    let user = User()
    user.email = "john.doe@example.com"
    scope.setUser(user)
}

Passing a Scope Instance

Setting an instance of Scope is helpful when you want to completely control what should be attached to the event. This is helpful in cases where you completely want to control what should be attached to the event.

import Sentry

let exception = NSException(name: NSExceptionName("My Custom exception"), reason: "User clicked the button", userInfo: nil)
let scope = Scope()
scope.setLevel(.fatal)
// By explicity just passing the scope, only the data in this scope object will be added to the event
// The global scope (calls to configureScope) will be ignored
// Only do this if you have mastered this SDK, otherwise, you risk losing useful info
// If you just want to mutate what's in the scope use the callback, see: captureError
SentrySDK.capture(exception: exception, scope: scope)

Using Scope Callback

To maintain global state, but mutate context data for one capture call, use the Scope callback:

import Sentry

let userInfo = [NSLocalizedDescriptionKey : "Object does not exist"]
let error = NSError(domain: "YourErrorDomain", code: 0, userInfo: userInfo)
SentrySDK.capture(error: error) { (scope) in
    // Changes in here will only be captured for this event
    // The scope in this callback is a clone of the current scope
    // It contains all data but mutations only influence the event being sent
    scope.setTag(value: "value", key: "myTag")
}

Integrations

The SDK enables all integrations by default. To disable any of them:

import Sentry

SentrySDK.start(options: [
    //...
    "integrations": Sentry.Options.defaultIntegrations().filter { (name) -> Bool in
        return name != "SentryAutoBreadcrumbTrackingIntegration" // This will disable  SentryAutoBreadcrumbTrackingIntegration
    }
    //...
])

SentryCrashIntegration

This integration is the core part of the SDK. It hooks into all signal and exception handlers to capture uncaught errors or crashes. This integration is also responsible for adding most of the device information to events. If it is disabled, you will not receive crash reports, nor will events contain much device data.

SentryAutoBreadcrumbTrackingIntegration

This integration will swizzle some methods to create breadcrumbs e.g.: for UIApplicationDidReceiveMemoryWarningNotification, sendAction:to:from:forEvent: (UI interactions) or viewDidAppear: those breadcrumbs will be attached to your events.

Known Limitations

• Since version 6.0.0, this SDK can't be used on Macs with Apple Silicon when importing it via Carthage because of an open issue in Carthage.