Migration Guide

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:

Copied
SentryOptions#addEventProcessor { event, _ -> event }

New:

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

Spring Boot

The property sentry.enable-tracing is deprecated. To enable tracing simply set sentry.traces-sample-rate or create a bean implementing TracesSamplerCallback.

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:

Copied
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:

Copied
@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:

Copied
@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:

Copied
@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.

Copied
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:

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

Updated:

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

Capture custom exception

Previous:

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

New:

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

Capture a message

Previous:

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

New:

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

Previous:

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

New:

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

User

Previous:

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

New:

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

Set extra

Previous:

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

New:

Copied
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:

Copied
tags=tag1:value1,tag2:value2

New:

Copied
tags.tag1=value1
tags.tag2=value2

“In Application” Stack Frames

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

New:

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

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

Copied
in-app-excludes=com.packages.to.exclude
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").