Migration Guide
To upgrade from version 4.x of the SDK to version 8.x of the SDK, you must first migrate from 4.x to 5.x, then 5.x to 6.x, then 6.x to 7.x, and finally from 7.x to 8.x.
Migrating to 8.x from 7.x includes a few breaking changes. We provide this guide to help you update your SDK. It's important to note that this version adds a dependency to Swift, and that we renamed the default branch on the sentry-cocoa repository from master
to main
.
The minimum supported OS versions have been bumped to macOS 10.13, iOS 11, tvOS 11, and watchOS 4. We bumped the minimum Xcode version to 13.
The following features are now enabled by default:
- The user interaction tracing integration
- The File I/O tracing integration
- Core Data tracing integration
- Capture failed requests
- App Hangs (not available for watchOS)
App Hang events might group differently as we now set the event stack trace snapshot property to true
.
The OOM (out of memory integration) actually tracks watchdog terminations based on heuristics. We renamed the integration to better reflect what it does.
This version includes the following configuration changes:
- Rename
SentryOptions.enableAutoPerformanceTracking
toSentryOptions.enableAutoPerformanceTracing
- Rename
SentryOptions.enableUIViewControllerTracking
toSentryOptions.enableUIViewControllerTracing
- Rename
SentryOptions.enablePreWarmedAppStartTracking
toSentryOptions.enablePreWarmedAppStartTracing
- Rename
SentryOptions.enableFileIOTracking
toSentryOptions.enableFileIOTracing
- Rename
SentryOptions.enableCoreDataTracking
toSentryOptions.enableCoreDataTracing
- Rename
SentryOptions.enableOutOfMemoryTracking
toSentryOptions.enableWatchdogTerminationTracking
We made some changes to make the API more ergonomic in Swift:
- Rename
SentrySDK.addBreadcrumb(crumb:)
toSentrySDK.addBreadcrumb(_ crumb:)
- Rename
SentryScope.add(_ crumb:)
toSentryScope.addBreadcrumb(_ crumb:)
- Rename
SentryScope.add(_ attachment:)
toSentryScope.addAttachment(_ attachment:)
- Rename
Client
toSentryClient
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.
- Make
SpanProtocol.data
non nullable - Mark
[SpanProtocol setExtraValue:forKey:]
as deprecated - Make
SpanContext
immutable- Remove tags from
SpanContext
- Remove context property from
SentrySpan
- Remove tags from
- Remove
SentryScope.apply(to:)
- Remove
SentryScope.apply(to:maxBreadcrumb:)
- Remove
[SentryOptions initWithDict:didFailWithError:]
- Remove
[SentryOptions sdkInfo]
- Make
SentrySession
andSentrySDKInfo
internal - Remove default attachment content type
- Remove
captureEnvelope
fromSentryHub
andSentryClient
- Remove confusing transaction tag
We removed the version of SentrySDK.startWithOptions
that took a dictionary, and renamed SentrySDK.startWithOptionsObject
to SentrySDK.startWithOptions
. The recommended way to initialize Sentry has not changed:
import Sentry
SentrySDK.start { options in
options.dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
// ...
}
SentrySDK.close
now calls flush, which is a blocking call.
Important
We recommend updating to at least 7.5.3, because the HTTP instrumentation can lead to crashes. Alternatively, you can also disable the feature.
Migrating to 7.x from 6.x includes a few breaking changes. We provide this guide to help you to update your SDK.
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.
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.
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
andSentrySDK.setCurrentHub
. - Remove
SentryClient.storeEnvelope
, which is reserved for Hybrid SDKs. - Make
closeCachedSessionWithTimestamp
private, which is reserved for internal use. - Remove deprecated
SentryHub.getScope
. UseSentryHub.scope
instead. - Replace
SentryException.thread
withSentryException.threadId
andSentryException.stacktrace
to align with the unified API. - Replace dict
SentryMechanism.meta
with new classSentryMechanismMeta
and moveSenryNSError
toSentryMechanismMeta
to align with the unified API. - Change
SentryEvent.timestamp
tonullable
.
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 to 6.x from 5.x includes a few breaking changes. We provide this guide to help you to update your SDK.
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 stack traces 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
tofalse
. This side effect is removed. Setting the DSN has no impact onenabled
. If the DSN is nil or empty orenabled
is set tofalse
and the client won't send any data to Sentry.
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.
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"
// ...
}
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.
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
}
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")
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.
The samples below illustrate how the SDK works:
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
])
Example in 4.x:`
Client.shared?.breadcrumbs.add(Breadcrumb(level: .info, category: "test"))
Example in 5.x:
SentrySDK.addBreadcrumb(Breadcrumb(level: .info, category: "test"))
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)
}
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)
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").