Migration Guide

To upgrade from the 4.x version of the SDK to the 7.x version of the SDK, you must first migrate from 4.x to 5.x, then 5.x to 6.x and finally from 6.x to 7.x.

Migrating from 6.x to 7.x

Migrating to 7.x from 6.x includes a few breaking changes. We provide this guide to help you to update your SDK.

Configuration Changes

This version includes the following configuration changes:

• Change the default maximum number of cached envelopes from 100 to 30. You can now configure this number with SentryOptions.maxCacheItems.
• When setting a value SentryOptions.sampleRate that is not >= 0.0 and <= 1.0 the SDK sets it to the default of 1.0 instead of keeping the set value.

Breaking Changes

Issue Grouping

This version introduces a change to the grouping of issues. The SDK now sets the inApp flag for frames originating from only the main executable using CFBundleExecutable. In previous versions, all frames originating from the application bundle were marked as inApp. This had the downside of marking frames of private frameworks inside the bundle as inApp. This problem is fixed now. Applications using static frameworks shouldn't be affected by this change. For more information read mark in-app frames.

Cleanup Public Classes

We cleaned up our public classes by removing a few functions and properties, that shouldn't be public, to make the API cleaner. In case we removed something you need, please open an issue on GitHub.

• Remove SentrySDK.currentHub and SentrySDK.setCurrentHub.
• Remove SentryClient.storeEnvelope, which is reserved for Hybrid SDKs.
• Make closeCachedSessionWithTimestamp private, which is reserved for internal use.
• Remove deprecated SentryHub.getScope. Use SentryHub.scope instead.
• Replace SentryException.thread with SentryException.threadId and SentryException.stacktrace to align with the unified API.
• Replace dict SentryMechanism.meta with new class SentryMechanismMeta and move SenryNSError to SentryMechanismMeta to align with the unified API.
• Change SentryEvent.timestamp to nullable.

SentryLogLevel

We replaced the SentryLogLevel with SentryLevel, renamed logLevel to diagnosticLevel on SentryOptions to align with other Sentry SDKs, and set the default diagnosticLevel to SentryLevel.debug. Furthermore, we removed setting the logLevel statically on the SentrySDK. Please use the SentryOptions to set the diagnosticLevel instead.

6.x

SentrySDK.start { options in
  options.logLevel = SentryLogLevel.verbose
}

// Or

SentrySDK.logLevel = SentryLogLevel.verbose

7.x

SentrySDK.start { options in
  options.diagnosticLevel = SentryLevel.debug
}

Migrating from 5.x to 6.x

Migrating to 6.x from 5.x includes a few breaking changes. We provide this guide to help you to update your SDK.

Configuration Changes

This version includes the following configuration changes:

• Auto Session Tracking is enabled by default. This feature is collecting and sending health data about the usage of your application.
• Attach stacktraces is enabled per default.
• We bumped the minimum iOS version to 9.0.
• Use a BOOL in SentryOptions instead of NSNumber to store booleans.
• We had previously removed the enabled option from SentryOptions, but we brought it back in version 6.0.7 with slightly changed functionality. Previously setting an empty or incorrect DSN also set enabled to false. This side effect is removed. Setting the DSN has no impact on enabled. If the DSN is nil or empty or enabled is set to false and the client won't send any data to Sentry.

Breaking Changes

Store Endpoint

This version uses the envelope endpoint. If you are using self-hosted Sentry, you must use Sentry version >= v20.6.0 or higher. If you are using sentry.io, there is no impact. For this change, we also now cache events in envelopes on the disk. We decided not to migrate the few cached events from 5.x to 6.x into envelopes. Instead, we remove them from the disk. As a result, you might lose a few cached events when upgrading.

SDK Inits

We removed the deprecated SDK inits. The recommended way to initialize Sentry is now:

import Sentry

SentrySDK.start { options in
    options.dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
    // ...
}

Cleanup Public Headers

We cleaned up our public headers and made most of our classes private. If you can't access one of the classes you need please open an issue and tell us your use case so we can evaluates whether to either make the class public again or provide another API for you.

New type SentryId for eventId

In 5.x, we used a nullable NSString to represent an event ID. The SDK, Hub, and Client returned this nullable NSString for the event ID to capture messages, events, errors, and so forth. In 6.x, we have a new type SentryId, which is not nullable, to represent an event ID. Instead of returning nil when an event couldn't be queued for submission we return SentryId.empty.

Example in 5.x:

import Sentry

let eventId = SentrySDK.capture(message: "A message")
if (nil != eventId) {
    // event was queued for submission
} else {
    // event wasn't queued for submission
}

Example in 6.x:

import Sentry

let eventId = SentrySDK.capture(message: "A message")
if (eventId != SentryId.empty) {
    // event was queued for submission
} else {
    // event wasn't queued for submission
}

New type SentryMessage for Event.message

In 6.x, we introduce a new type SentryMessage for event.message. SentryMessage provides you the ability to pass a format string with parameters to Sentry, which can help group similar messages into the same issue.

Example in 5.x:

import Sentry

let event = Event()
event.message = "Hello World"

Example in 6.x:

import Sentry

let event = Event()
event.message = SentryMessage(formatted: "Hello World")

Make Scope nonnull for capture methods

In 5.x, you could pass a nullable scope to capture methods of the SDK, Hub, and Client, such as SentrySdk.captureMessage(). In 6.x, we changed the Scope to nonnull and provide overloads for the Hub and the Client.

Please see the Changelog for a complete list of changes.

Upgrading from 4.x to 5.x

The samples below illustrate how the SDK works:

Initialization

Example in 4.x:

do {
    Client.shared = try Client(dsn: "https://examplePublicKey@o0.ingest.sentry.io/0")
    try Client.shared?.startCrashHandler()
} catch let error {
    print("\(error)")
}

Example in 5.x:

SentrySDK.start(options: [
    "dsn": "https://examplePublicKey@o0.ingest.sentry.io/0",
    "debug": true
])

Add Breadcrumb

Example in 4.x:`

Client.shared?.breadcrumbs.add(Breadcrumb(level: .info, category: "test"))

Example in 5.x:

SentrySDK.addBreadcrumb(Breadcrumb(level: .info, category: "test"))

CaptureMessage with tags/environment/extra

Example in 4.x:

let event = Event(level: .debug)
event.message = "Test Message"
event.environment = "staging"
event.extra = ["ios": true]
Client.shared?.send(event: event)

Example in 5.x:

SentrySDK.capture(message: "Test Message") { (scope) in
    scope.setEnvironment("staging")
    scope.setExtras(["ios": true])
    let u = Sentry.User(userId: "1")
    u.email = "tony@example.com"
    scope.setUser(u)
}

setUser

Example in 4.x:

let u = User(userId: "1")
u.email = "tony@example.com"
Client.shared?.user = user

Example in 5.x:

let u = Sentry.User(userId: "1")
u.email = "tony@example.com"
SentrySDK.setUser(u)