Migrate from sentry 7.x to 8.0.0

Breaking Changes

• Contexts no longer extends ConcurrentHashMap, instead we offer a selected set of methods.
• sentry-android-okhttp has been removed in favor of sentry-okhttp, making the module independent from Android (#3510)
• Calling Sentry.init() on Android now throws a IllegalArgumentException, please use SentryAndroid.init() instead (#3596)
• The previous metrics API has been removed from the SDK (#3774)
  • A new Metrics feature is now available. See the Metrics documentation for setup instructions.
• enableTracing option (a.k.a enable-tracing) has been removed from the SDK (#3776)
  • Please set tracesSampleRate to a value >= 0.0 for enabling performance instead. The default value is null which means performance is disabled.
• Change OkHttp sub-spans to span attributes (#3556)
  • This will reduce the number of spans created by the SDK
• Replace synchronized methods and blocks with ReentrantLock (AutoClosableReentrantLock) (#3715)
  • If you are subclassing any Sentry classes, please check if the parent class used synchronized before. Please make sure to use the same lock object as the parent class in that case.
• traceOrigins option (io.sentry.traces.tracing-origins in manifest) has been removed, please use tracePropagationTargets (io.sentry.traces.trace-propagation-targets in manifest`) instead (#3780)
• profilingEnabled option (io.sentry.traces.profiling.enable in manifest) has been removed, please use profilesSampleRate (io.sentry.traces.profiling.sample-rate in manifest) instead (#3780)
  • Please set profileSampleRate to a value >= 0.0 for enabling profiling instead. The default value is null which means profiling is disabled.
• shutdownTimeout option has been removed, please use shutdownTimeoutMillis instead (#3780)
• profilingTracesIntervalMillis option for Android has been removed (#3780)
• io.sentry.session-tracking.enable manifest option has been removed (#3780)
• Sentry.traceHeaders() method has been removed, please use Sentry.getTraceparent() instead (#3718)
• Sentry.reportFullDisplayed() method has been removed, please use Sentry.reportFullyDisplayed() instead (#3717)
• User.other has been removed, please use data instead (#3780)
• SdkVersion.getIntegrations() has been removed, please use getIntegrationSet instead (#3780)
• SdkVersion.getPackages() has been removed, please use getPackageSet() instead (#3780)
• Device.language has been removed, please use locale instead (#3780)
• TraceContext.user and TraceContextUser class have been removed, please use userId on TraceContext instead (#3780)
• TransactionContext.fromSentryTrace() has been removed, please use Sentry.continueTrace() instead (#3780)
• SentryDataFetcherExceptionHandler has been removed, please use SentryGenericDataFetcherExceptionHandler in combination with SentryInstrumentation instead (#3780)
• One of the AndroidTransactionProfiler constructors has been removed, please use a different one (#3780)
• Use String instead of UUID for SessionId (#3834)
  • The Session constructor now takes a String instead of a UUID for the sessionId parameter.
  • Session.getSessionId() now returns a String instead of a UUID.
• The Android minSdk level for all Android modules is now 21 (#3852) (#3851)
• All status codes below 400 are now mapped to SpanStatus.OK (#3869)
• transaction.data has moved from extra to contexts.trace.data (#3735)
  • If you were filtering data in e.g. beforeSendTransaction please update accordingly

Deprecations

• Hub has been deprecated, we're replacing the following:
  • IHub has been replaced by IScopes, however you should be able to simply pass IHub instances to code expecting IScopes, allowing for an easier migration.
  • HubAdapter.getInstance() has been replaced by ScopesAdapter.getInstance()
  • The .clone() method on IHub/IScopes has been deprecated, please use .pushScope() or .pushIsolationScope() instead
  • Some internal methods like .getCurrentHub() and .setCurrentHub() have also been replaced.
• Sentry.popScope has been replaced by calling .close() on the token returned by Sentry.pushScope() and Sentry.pushIsolationScope(). The token can also be used in a try-with-resource block like this:

try (final @NotNull ISentryLifecycleToken ignored = Sentry.pushScope()) {
  // this block has its separate current scope
}

as well as:

try (final @NotNull ISentryLifecycleToken ignored = Sentry.pushIsolationScope()) {
  // this block has its separate isolation scope
}

You may also use LifecycleHelper.close(token), e.g. in case you need to pass the token around for closing later.

Behavioral Changes

• We're introducing some new Scope types in the SDK, allowing for better control over what data is attached where. Previously there was a stack of scopes that was pushed and popped. Instead we now fork scopes for a given lifecycle and then restore the previous scopes. Since Hub is gone, it is also never cloned anymore. Separation of data now happens through the different scope types while making it easier to manipulate exactly what you need without having to attach data at the right time to have it apply where wanted.
  • Global scope is attached to all events created by the SDK. It can also be modified before Sentry.init has been called. It can be manipulated using Sentry.configureScope(ScopeType.GLOBAL, (scope) -> { ... }).
  • Isolation scope can be used e.g. to attach data to all events that come up while handling an incoming request. It can also be used for other isolation purposes. It can be manipulated using Sentry.configureScope(ScopeType.ISOLATION, (scope) -> { ... }). The SDK automatically forks isolation scope in certain cases like incoming requests, CRON jobs, Spring @Async and more.
  • Current scope is forked often and data added to it is only added to events that are created while this scope is active. Data is also passed on to newly forked child scopes but not to parents.
• Sentry.popScope has been deprecated, please call .close() on the token returned by Sentry.pushScope instead or use it in a way described in more detail in "Migration Guide".
• We have chosen a default scope that is used for Sentry.configureScope() as well as for APIs like Sentry.setTag()
  • For Android the type defaults to CURRENT scope
  • For Backend and other JVM applications it defaults to ISOLATION scope
• Event processors on Scope can now be ordered by overriding the getOrder method on implementations of EventProcessor. NOTE: This order only applies to event processors on Scope but not SentryOptions at the moment. Feel free to request this if you need it.
• Hub is deprecated in favor of Scopes, alongside some Hub relevant APIs. More details can be found in the "Migration Guide" section.
• (Android) The JNI layer for sentry-native has now been moved from sentry-java to sentry-native (#3189)
  • This now includes prefab support for sentry-native, allowing you to link and access the sentry-native API within your native app code
  • Checkout the sentry-samples/sentry-samples-android example on how to configure CMake and consume sentry.h
• (Android) Replace thread id with kernel thread id in span data (#3706)
• (Android) Enable Performance V2 by default (#3824)
  • With this change cold app start spans will include spans for ContentProviders, Application and Activity load.

Sentry Self-hosted Compatibility

• The required Sentry version in version 8.0.0 of the SDK remains unchanged. Sentry's version >= v22.12.0 is required. This only applies to self-hosted Sentry. If you are using sentry.io, no action is needed.

Sentry Android SDK Compatibility

You must use Sentry Gradle plugin 5.+ together with the Sentry Android SDK 8.+ otherwise, it might crash at runtime due to missing dependencies.