Skip to content

Latest commit

 

History

History
282 lines (214 loc) · 7.36 KB

MIGRATION.md

File metadata and controls

282 lines (214 loc) · 7.36 KB
Raw

Upgrading from 5.x to 6.x

In this version there are a few breaking changes. This guide should help you to update your code.

Configuration Changes

With this version we changed a few things for the configuration:

  • Auto Session Tracking is enabled per 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 removed enabled on the SentryOptions.

Breaking Changes

Store Endpoint

This version uses the envelope endpoint. If you are using an on-premise installation it requires Sentry version >= v20.6.0 to work. If you are using sentry.io nothing will change and no action is needed. For this change, we also cache events now in envelopes on the disk. We decided not to take the effort to migrate these few cached events from 5.x to 6.x into envelopes. Instead we remove them from the disk. This means you might lose a few cached events of your users when upgrading.

SDK Inits

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

SentrySDK.start { options in
    options.dsn = "___PUBLIC_DSN___"
    // ...
}
[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
    options.dsn = @"___PUBLIC_DSN___";
    // ...
}];

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 either make the class public again or provide another API for you.

New type SentryId for eventId

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

5.x

let eventId = SentrySDK.capture(message: "A message")
if (nil != eventId) {
    // event was queued for submission
} else {
    // event wasn't queued for submission
}
SentryId *eventId = [SentrySDK captureMessage:@"A message"];
if (nil != eventId) {
    // event was queued for submission
} else {
    // event wasn't queued for submission
}

6.x

let eventId = SentrySDK.capture(message: "A message")
if (eventId != SentryId.empty) {
    // event was queued for submission
} else {
    // event wasn't queued for submission
}
SentryId *eventId = [SentrySDK captureMessage:@"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 gives you the possibilty to pass a format string with parameters to Sentry, which can help to group similar messages into the same issue.

5.x

let event = Event()
event.message = "Hello World"
SentryEvent *event = [[SentryEvent alloc] init];
event.message = "Hello World";

6.x

let event = Event()
event.message = SentryMessage(formatted: "Hello World")
SentryEvent *event = [[SentryEvent alloc] init];
event.message = [SentryMessage messageWithFormatted:"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 checkout the Changelog for a complete list of changes.

Upgrading from 4.x to 5.x

Here are some examples of how the new SDK works.

Initialization

4.x.x

do {
    Client.shared = try Client(dsn: "___PUBLIC_DSN___")
    try Client.shared?.startCrashHandler()
} catch let error {
    print("\(error)")
}
NSError *error = nil;
SentryClient *client = [[SentryClient alloc] initWithDsn:@"___PUBLIC_DSN___" didFailWithError:&error];
SentryClient.sharedClient = client;
[SentryClient.sharedClient startCrashHandlerWithError:&error];
if (nil != error) {
    NSLog(@"%@", error);
}

5.x.x

SentrySDK.start(options: [
    "dsn": "___PUBLIC_DSN___",
    "debug": true
])
[SentrySDK startWithOptions:@{
    @"dsn": @"___PUBLIC_DSN___",
    @"debug": @(YES)
}];

Add Breadcrumb

4.x.x

Client.shared?.breadcrumbs.add(Breadcrumb(level: .info, category: "test"))
[SentryClient.sharedClient.breadcrumbs addBreadcrumb:[[SentryBreadcrumb alloc] initWithLevel:kSentrySeverityInfo category:@"test"]];

5.x.x

SentrySDK.addBreadcrumb(Breadcrumb(level: .info, category: "test"))
[SentrySDK addBreadcrumb:[[SentryBreadcrumb alloc] initWithLevel:kSentrySeverityInfo category:@"test"]];

CaptureMessage with tags/environment/extra

4.x.x

let event = Event(level: .debug)
event.message = "Test Message"
event.environment = "staging"
event.extra = ["ios": true]
Client.shared?.send(event: event)
SentryEvent *event = [[SentryEvent alloc] initWithLevel:kSentrySeverityDebug];
event.message = @"Test Message";
event.environment = @"staging";
event.extra = @{@"ios": @(YES)};
[SentryClient.sharedClient sendEvent:event withCompletionHandler:nil];

5.x.x

SentrySDK.capture(message: "Test Message") { (scope) in
    scope.setEnvironment("staging")
    scope.setExtras(["ios": true])
    let u = Sentry.User(userId: "1")
    u.email = "[email protected]"
    scope.setUser(u)
}
[SentrySDK captureMessage:@"Test Message" withScopeBlock:^(SentryScope * _Nonnull scope) {
    [scope setEnvironment:@"staging"];
    [scope setExtras:@{@"ios": @(YES)}];
    SentryUser *user = [[SentryUser alloc] initWithUserId:@"1"];
    user.email = @"[email protected]";
    [scope setUser:user];
}];

setUser

4.x.x

let u = User(userId: "1")
u.email = "[email protected]"
Client.shared?.user = user
SentryUser *user = [[SentryUser alloc] initWithUserId:@"1"];
user.email = @"[email protected]";
SentryClient.sharedClient.user = user;

5.x.x

let u = Sentry.User(userId: "1")
u.email = "[email protected]"
SentrySDK.setUser(u)
SentryUser *user = [[SentryUser alloc] initWithUserId:@"1"];
user.email = @"[email protected]";
[SentrySDK setUser:user];

For more features, usage examples and configuration options, please visit: https://docs.sentry.io/platforms/cocoa/