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 to1.4
.Gson
is removed as a transitive dependency and vendored in the SDK.- Protocol classes now implement the
JsonSerializable
andJsonDeserializer
interfaces.
- Protocol classes now implement the
Spring Boot has been upgraded to
2.5.13
SentryOptions#shutdownTimeout
is renamed toshutdownTimeoutMillis
.Removed
@Deprecated
and@ApiStatus.ScheduledForRemoval
methodsITransaction#setRequest
ITransaction#getRequest
ITransaction#getContexts
SentryBaseEvent#getOriginThrowable
SentryOptions#getCacheDirSize
SentryOptions#setCacheDirSize
SentryOptions#isEnableSessionTracking
SentryOptions#setEnableSessionTracking
sentry.enable-tracing
propertySentrySpringRequestListener
,SentrySpringFilter
is used instead.SentryUserProviderEventProcessor
, please useSentryUserProvider
instead.
SentryOptions#enableScopeSync
is now enabled by default.ISpan
now has higher precision using theSystem#nanoTime
instead of milliseconds.TransactionNameProvider
is now an interface andSpringMvcTransactionNameProvider
is the default implementation.Hints changed its type from
Object
toio.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
ofsentry
, Sentry's version >= v21.9.0 is required or you have to manually disable sending client reports via thesendClientReports
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
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:
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 withSentryOptions#cacheDirPath
buffer.size
- can be set withSentryOptions#cacheDirSize
buffer.flushtime
- can be set withSentryOptions#flushTimeoutMillis
buffer.shutdowntimeout
buffer.gracefulshutdown
async
async.shutdowntimeout
- can be set withSentryOptions#shutdownTimeout
async.gracefulshutdown
async.queuesize
- can be set withSentryOptions#maxQueueSize
async.threads
async.priority
compression
maxmessagelength
factory
mdcTags
extra
- can be set on the scope withScope#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
- throughSentryOptions#sampleRate
timeout
- throughSentryOptions#connectionTimeoutMillis
andSentryOptions#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
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").
- Package:
- maven:io.sentry:sentry
- Version:
- 6.17.0
- Repository:
- https://github.com/getsentry/sentry-java