Migration Guide

Migrating from io.sentry:sentry 5.x to io.sentry:sentry 6.0.0

• Kotlin plugin is upgraded to 1.5.

• Kotlin languageVersion is upgraded to 1.4.

• Gson is removed as a transitive dependency and vendored in the SDK.

  • Protocol classes now implement the JsonSerializable and JsonDeserializer interfaces.

• Spring Boot has been upgraded to 2.5.13

• SentryOptions#shutdownTimeout is renamed to shutdownTimeoutMillis.

• Removed @Deprecated and @ApiStatus.ScheduledForRemoval methods

  • ITransaction#setRequest
  • ITransaction#getRequest
  • ITransaction#getContexts
  • SentryBaseEvent#getOriginThrowable
  • SentryOptions#getCacheDirSize
  • SentryOptions#setCacheDirSize
  • SentryOptions#isEnableSessionTracking
  • SentryOptions#setEnableSessionTracking
  • sentry.enable-tracing property
  • SentrySpringRequestListener, SentrySpringFilter is used instead.
  • SentryUserProviderEventProcessor, please use SentryUserProvider instead.

• SentryOptions#enableScopeSync is now enabled by default.

• ISpan now has higher precision using the System#nanoTime instead of milliseconds.

• TransactionNameProvider is now an interface and SpringMvcTransactionNameProvider is the default implementation.

• Hints changed its type from Object to io.sentry.Hint

Old:

Sentry.captureException(RuntimeException("exception"), "myStringHint")

New:

val hints = mutableMapOf<String, Any>("myHint" to "myStringHint")
Sentry.captureException(RuntimeException("exception"), hints)

• SentryOptions#sendClientReports is now enabled by default. To disable it, see sendClientReports. For more information on the option see sendClientReports.

Sentry Self-hosted Compatibility

• Starting with version 6.0.0 of sentry, Sentry's version >= v21.9.0 is required or you have to manually disable sending client reports via the sendClientReports option. This only applies to self-hosted Sentry. If you are using sentry.io, no action is needed.

There are more changes and refactors, but they are not user breaking changes.

Migrating from io.sentry:sentry 4.3.0 to io.sentry:sentry 5.0.0

Sentry#startTransaction by default does not bind created transaction to the scope. To start transaction with binding to the scope, use one of the new overloaded startTransaction methods taking bindToScope parameter and set it to true. Bound transaction can be retrieved with Sentry#getSpan.

All SDK methods have been annotated with JetBrains Annotations: @Nullable and @NotNull. Kotlin compiler respects these annotations and as a result, in Kotlin code, some fields that were recognized as not-null, are now nullable, and the other way around.

SentryBaseEvent#getOriginThrowable has been deprecated in favor of SentryBaseEvent#getThrowable, and SentryBaseEvent#getThrowable now returns the unwrapped throwable.

The ShutdownHookIntegration now flushes the SDK instead of closing it.

SentryOptions#getCacheDirSize has been deprecated in favor of SentryOptions#getMaxCacheItems.

InvalidDsnException has been removed. It is replaced by IllegalArgumentException.

EventProcessor interface has a new default method which could break the instantiation when using trailing lambdas.

Old:

SentryOptions#addEventProcessor { event, _ -> event }

New:

SentryOptions#addEventProcessor(object : EventProcessor {
    override fun process(event: SentryEvent, hint: Hint): SentryEvent? {
        return event
    }
})

Spring Boot

The property sentry.enable-tracing is deprecated. To enable

Migrating from io.sentry:sentry 4.1.0 to io.sentry:sentry 4.2.0

operation is now a required property of the SentryTransaction and SentrySpan. Whenever a transaction or span is started, the value for operation must be provided:

Sentry.startTransaction("transaction-name", "operation-name");

Spring

RestTemplate instrumentation

Simplified RestTemplate instrumentation does not involve anymore setting UriTemplateHandler using SentrySpanClientHttpRequestInterceptor.

Code snippet adding Sentry RestTemplate instrumentation changed from:

@Bean
RestTemplate restTemplate(IHub hub) {
  RestTemplate restTemplate = new RestTemplate();
  SentrySpanClientHttpRequestInterceptor sentryRestTemplateInterceptor = new SentrySpanClientHttpRequestInterceptor(hub);
  UriTemplateHandler templateHandler = restTemplate.getUriTemplateHandler();
  restTemplate.setUriTemplateHandler(sentryRestTemplateInterceptor.createUriTemplateHandler(templateHandler));
  restTemplate.setInterceptors(Collections.singletonList(sentryRestTemplateInterceptor));
  return restTemplate;
}

into:

@Bean
RestTemplate restTemplate(IHub hub) {
  RestTemplate restTemplate = new RestTemplate();
  SentrySpanClientHttpRequestInterceptor sentryRestTemplateInterceptor = new SentrySpanClientHttpRequestInterceptor(hub);
  restTemplate.setInterceptors(Collections.singletonList(sentryRestTemplateInterceptor));
  return restTemplate;
}

SentryExceptionResolver does not send handled errors by default

To prevent SentryExceptionResolver from sending errors that have been already captured by @ExceptionHandlers, we've changed the order for SentryExceptionResolver to 1.

Old behavior can be brought back by setting exceptionResolverOrder property on @EnableSentry:

@EnableSentry(exceptionResolverOrder = -2147483648)
class CustomConfiguration {
  ...
}

Spring Boot

SentryExceptionResolver does not send handled errors by default

To prevent SentryExceptionResolver from sending errors that have been already captured by @ExceptionHandlers, we've changed the order for SentryExceptionResolver to 1.

Old behavior can be brought back by setting a property sentry.exception-resolver-order=-2147483648

@SentryTransaction operation is now required

@SentryTransaction must have operation property provided.

class MyComponent {

  @SentryTransaction(name = "transaction-name", operation = "operation-name")
  @Scheduled(fixedRate = 3 * 1000L)
  void execute() {
      ...
    }
}

Migrating from io.sentry:sentry 1.x to io.sentry:sentry 4.x

Our update to the API follows the Unified API more closely. It's a completely updated code base, written to support our Android SDK.

API Changes

Set tag

Previous:

Sentry.getContext().addTag("tagName", "tagValue");

Updated:

Sentry.setTag("tagName", "tagValue");

Capture custom exception

Previous:

try {
  int x = 1 / 0;
} catch (Exception e) {
  Sentry.capture(e);
}

New:

try {
  int x = 1 / 0;
} catch (Exception e) {
  Sentry.captureException(e);
}

Capture a message

Previous:

Sentry.capture("This is a test");

New:

Sentry.captureMessage("This is a test"); // SentryLevel.INFO by default
Sentry.captureMessage("This is a test", SentryLevel.WARNING); // or specific level

Breadcrumbs

Previous:

Sentry.getContext().recordBreadcrumb(
  new BreadcrumbBuilder().setMessage("User made an action").build()
);

New:

Sentry.addBreadcrumb("User made an action");

User

Previous:

Sentry.getContext().setUser(
  new UserBuilder().setEmail("hello@sentry.io").build()
);

New:

User user = new User();
user.setEmail("hello@sentry.io");
Sentry.setUser(user);

Set extra

Previous:

Sentry.getContext().addExtra("extra", "thing");

New:

Sentry.setExtra("extra", "thing");

Removed Properties

Following configuration properties have been removed:

• buffer.dir - can be set with SentryOptions#cacheDirPath
• buffer.size - can be set with SentryOptions#cacheDirSize
• buffer.flushtime - can be set with SentryOptions#flushTimeoutMillis
• buffer.shutdowntimeout
• buffer.gracefulshutdown
• async
• async.shutdowntimeout - can be set with SentryOptions#shutdownTimeout
• async.gracefulshutdown
• async.queuesize - can be set with SentryOptions#maxQueueSize
• async.threads
• async.priority
• compression
• maxmessagelength
• factory
• mdcTags
• extra - can be set on the scope with Scope#extra

Property Name Changes

Following properties cannot be set anymore through external configuration and have to be set directly on SentryOptions object when initializing Sentry:

• sample.rate - through SentryOptions#sampleRate
• timeout - through SentryOptions#connectionTimeoutMillis and SentryOptions#readTimeoutMillis

See Configuration page to find all available configuration properties.

Tags

Previous:

tags=tag1:value1,tag2:value2

New:

tags.tag1=value1
tags.tag2=value2

“In Application” Stack Frames

stacktrace.app.packages=com.mycompany,com.other.name

New:

in-app-includes=com.mycompany,com.other.name

There is also an option to exclude certain packages from stacktraces:

in-app-excludes=com.packages.to.exclude