From 1b9f31a6ada5951613078445f2103791d3f13f3d Mon Sep 17 00:00:00 2001 From: Alex Krawiec Date: Tue, 24 Mar 2026 13:23:09 -0700 Subject: [PATCH] Breakout migration guides for Apple and Android --- .../migration/gradle-plugin-v1-to-v2.mdx | 86 ++ .../migration/gradle-plugin-v2-to-v3.mdx | 75 ++ .../migration/gradle-plugin-v3-to-v4.mdx | 24 + docs/platforms/android/migration/index.mdx | 767 +----------------- .../android/migration/timber-v5-6-2.mdx | 13 + docs/platforms/android/migration/v1-to-v2.mdx | 263 ++++++ docs/platforms/android/migration/v2-to-v3.mdx | 17 + .../android/migration/v4-1-to-v4-2.mdx | 11 + .../android/migration/v4-3-to-v5.mdx | 81 ++ docs/platforms/android/migration/v5-to-v6.mdx | 57 ++ .../android/migration/v6-14-to-v6-15.mdx | 7 + .../android/migration/v6-2-to-v6-3.mdx | 7 + .../android/migration/v6-to-v6-2.mdx | 15 + docs/platforms/android/migration/v6-to-v7.mdx | 57 ++ docs/platforms/android/migration/v7-to-v8.mdx | 94 +++ .../apple/common/migration/index.mdx | 580 +------------ .../apple/common/migration/v4-to-v5.mdx | 142 ++++ .../apple/common/migration/v5-to-v6.mdx | 145 ++++ .../apple/common/migration/v6-to-v7.mdx | 70 ++ .../apple/common/migration/v7-to-v8.mdx | 97 +++ .../apple/common/migration/v8-to-v9.mdx | 138 ++++ 21 files changed, 1405 insertions(+), 1341 deletions(-) create mode 100644 docs/platforms/android/migration/gradle-plugin-v1-to-v2.mdx create mode 100644 docs/platforms/android/migration/gradle-plugin-v2-to-v3.mdx create mode 100644 docs/platforms/android/migration/gradle-plugin-v3-to-v4.mdx create mode 100644 docs/platforms/android/migration/timber-v5-6-2.mdx create mode 100644 docs/platforms/android/migration/v1-to-v2.mdx create mode 100644 docs/platforms/android/migration/v2-to-v3.mdx create mode 100644 docs/platforms/android/migration/v4-1-to-v4-2.mdx create mode 100644 docs/platforms/android/migration/v4-3-to-v5.mdx create mode 100644 docs/platforms/android/migration/v5-to-v6.mdx create mode 100644 docs/platforms/android/migration/v6-14-to-v6-15.mdx create mode 100644 docs/platforms/android/migration/v6-2-to-v6-3.mdx create mode 100644 docs/platforms/android/migration/v6-to-v6-2.mdx create mode 100644 docs/platforms/android/migration/v6-to-v7.mdx create mode 100644 docs/platforms/android/migration/v7-to-v8.mdx create mode 100644 docs/platforms/apple/common/migration/v4-to-v5.mdx create mode 100644 docs/platforms/apple/common/migration/v5-to-v6.mdx create mode 100644 docs/platforms/apple/common/migration/v6-to-v7.mdx create mode 100644 docs/platforms/apple/common/migration/v7-to-v8.mdx create mode 100644 docs/platforms/apple/common/migration/v8-to-v9.mdx diff --git a/docs/platforms/android/migration/gradle-plugin-v1-to-v2.mdx b/docs/platforms/android/migration/gradle-plugin-v1-to-v2.mdx new file mode 100644 index 0000000000000..182dbb3ed1684 --- /dev/null +++ b/docs/platforms/android/migration/gradle-plugin-v1-to-v2.mdx @@ -0,0 +1,86 @@ +--- +title: Migrate from sentry-android-gradle-plugin 1.x to 2.0.0 +sidebar_order: 8930 +description: "Learn about migrating from Sentry Android Gradle Plugin 1.x to 2.0.0." +--- + +The `io.sentry.android.gradle` >= `2.0.0` requires [Android Gradle Plugin >= 4.0.0](https://developer.android.com/studio/releases/gradle-plugin#4-0-0). + +The `io.sentry.android.gradle` >= `2.0.0` must be applied to the `app/build.gradle` module (or the module that has `com.android.application` plugin applied). + +The `io.sentry.android.gradle` >= `2.0.0` publishes the Gradle Plugin Marker to Maven Central. As a result, you no longer need to set the `classpath`. + +_Old_: + +```groovy +buildscript { + repositories { + mavenCentral() + } + + dependencies { + classpath 'io.sentry:sentry-android-gradle-plugin:{version}' + } +} + +apply plugin: 'io.sentry.android.gradle' +``` + +_New_: + +```groovy +plugins { + id "io.sentry.android.gradle" version "{version}" +} + +buildscript { + repositories { + mavenCentral() + } +} +``` + +```kotlin +plugins { + id("io.sentry.android.gradle") version "{version}" +} + +buildscript { + repositories { + mavenCentral() + } +} +``` + +The `io.sentry.android.gradle` has been rewritten in Kotlin. As a result, the Groovy or Kotlin DSL syntax has slightly changed. + +The `autoProguardConfig` flag has been removed, the Android SDK >= `2.0.0` version already merges the ProGuard rules automatically. + +_Old_: + +```groovy +sentry { + autoProguardConfig false + autoUpload true + uploadNativeSymbols false + includeNativeSources false +} +``` + +_New_: + +```groovy +sentry { + autoUpload = true + uploadNativeSymbols = false + includeNativeSources = false +} +``` + +```kotlin +sentry { + autoUpload.set(true) + uploadNativeSymbols.set(false) + includeNativeSources.set(false) +} +``` diff --git a/docs/platforms/android/migration/gradle-plugin-v2-to-v3.mdx b/docs/platforms/android/migration/gradle-plugin-v2-to-v3.mdx new file mode 100644 index 0000000000000..9750b289f7b9e --- /dev/null +++ b/docs/platforms/android/migration/gradle-plugin-v2-to-v3.mdx @@ -0,0 +1,75 @@ +--- +title: Migrate from sentry-android-gradle-plugin 2.x to 3.0.0 +sidebar_order: 8925 +description: "Learn about migrating from Sentry Android Gradle Plugin 2.x to 3.0.0." +--- + +The `io.sentry.android.gradle` >= `3.0.0` requires [Android Gradle Plugin >= 7.0.0](https://developer.android.com/studio/releases/gradle-plugin#7-0-0). For older versions of the Android Gradle Plugin, use `io.sentry.android.gradle:2.+`. + +## includeProguardMapping + +The `autoUpload` flag has been deprecated in favor of two new options: + +- `includeProguardMapping` - Disables/enables Proguard mapping functionality. When enabled, generates a UUID and attempts to upload a Proguard mapping associated with that UUID to Sentry. When `autoUploadProguardMapping` is disabled, the plugin will only generate a `sentry-debug-meta.properties` file containing UUID, which can later be used to manually upload the mapping using, for example [sentry-cli](/cli/dif/#proguard-mapping-upload). +- `autoUploadProguardMapping` - Defines whether the gradle plugin should attempt to auto-upload the mapping file to Sentry. + When `includeProguardMapping` is disabled, this flag has no effect. + +_Old_: + +```groovy +sentry { + autoUpload = false +} +``` + +```kotlin +sentry { + autoUpload.set(false) +} +``` + +_New_: + +```groovy +sentry { + includeProguardMapping = true + autoUploadProguardMapping = false +} +``` + +```kotlin +sentry { + includeProguardMapping.set(true) + autoUploadProguardMapping.set(false) +} +``` + +## tracingInstrumentation + +The `io.sentry.android.gradle` enables the tracing instrumentation (via bytecode manipulation) for `androidx.sqlite` and `androidx.room` libraries by default, to disable it, see the code snippet below. + +```groovy +sentry { + // Enable or disable the tracing instrumentation. + // Does auto instrumentation for 'androidx.sqlite' and 'androidx.room' libraries. + // It starts and finishes a Span within any CRUD operation. + // Default is enabled. + // Only available v3.0.0 and above. + tracingInstrumentation { + enabled = false + } +} +``` + +```kotlin +sentry { + // Enable or disable the tracing instrumentation. + // Does auto instrumentation for 'androidx.sqlite' and 'androidx.room' libraries. + // It starts and finishes a Span within any CRUD operation. + // Default is enabled. + // Only available v3.0.0 and above. + tracingInstrumentation { + enabled.set(false) + } +} +``` diff --git a/docs/platforms/android/migration/gradle-plugin-v3-to-v4.mdx b/docs/platforms/android/migration/gradle-plugin-v3-to-v4.mdx new file mode 100644 index 0000000000000..86341ebab5e41 --- /dev/null +++ b/docs/platforms/android/migration/gradle-plugin-v3-to-v4.mdx @@ -0,0 +1,24 @@ +--- +title: Migrate from sentry-android-gradle-plugin 3.x to 4.0.0 +sidebar_order: 8905 +description: "Learn about migrating from Sentry Android Gradle Plugin 3.x to 4.0.0." +--- + +## Breaking Changes + +- Bumped Sentry Android SDK to `7.0.0`. Refer to the [migration guide for sentry-android 6.x to 7.0.0](/platforms/android/migration/v6-to-v7/) for details about changes to the SDK. +- Renamed `experimentalGuardsquareSupport` flag to `dexguardEnabled`. + +## Sentry Android SDK Compatibility + +You must use Sentry Gradle plugin 4.+ together with the Sentry Android SDK 7.+ otherwise, it might crash at runtime due to binary incompatibility. If you can't do that for some reason, you can specify the Sentry version via the plugin config block: + +```kotlin +sentry { + autoInstallation { + sentryVersion.set("7.0.0") + } +} +``` + +Similarly, if you have a Sentry SDK (e.g. `sentry-android-core`) dependency on one of your Gradle modules and you're updating it to 7.+, make sure the Gradle plugin is at 4.+, or specify the SDK version as shown in the snippet above. diff --git a/docs/platforms/android/migration/index.mdx b/docs/platforms/android/migration/index.mdx index ce3e6d2827f5c..6add7b6f3f18d 100644 --- a/docs/platforms/android/migration/index.mdx +++ b/docs/platforms/android/migration/index.mdx @@ -2,770 +2,9 @@ title: Migration Guide sidebar_order: 8000 sidebar_section: configuration -description: "Migrating between versions of Sentry's SDK for Android." +description: "Migrate from an older version of Sentry's SDK for Android." --- -## Migrating from `io.sentry:sentry` `7.x` to `io.sentry:sentry` `8.0.0` +Here's a list of guides on migrating to a newer version of the Sentry Android SDK. -### 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](https://github.com/getsentry/sentry-java/pull/3510)) -- Calling `Sentry.init()` on Android now throws a `IllegalArgumentException`, please use `SentryAndroid.init()` instead ([#3596](https://github.com/getsentry/sentry-java/pull/3596)) -- The previous metrics API has been removed from the SDK ([#3774](https://github.com/getsentry/sentry-java/pull/3774)) - - A new Metrics feature is now available. See the [Metrics documentation](/platforms/android/metrics/) for setup instructions. -- `enableTracing` option (a.k.a `enable-tracing`) has been removed from the SDK ([#3776](https://github.com/getsentry/sentry-java/pull/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](https://github.com/getsentry/sentry-java/pull/3556)) - - This will reduce the number of spans created by the SDK -- Replace `synchronized` methods and blocks with `ReentrantLock` (`AutoClosableReentrantLock`) ([#3715](https://github.com/getsentry/sentry-java/pull/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](https://github.com/getsentry/sentry-java/pull/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](https://github.com/getsentry/sentry-java/pull/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](https://github.com/getsentry/sentry-java/pull/3780)) -- `profilingTracesIntervalMillis` option for Android has been removed ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) -- `io.sentry.session-tracking.enable` manifest option has been removed ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) -- `Sentry.traceHeaders()` method has been removed, please use `Sentry.getTraceparent()` instead ([#3718](https://github.com/getsentry/sentry-java/pull/3718)) -- `Sentry.reportFullDisplayed()` method has been removed, please use `Sentry.reportFullyDisplayed()` instead ([#3717](https://github.com/getsentry/sentry-java/pull/3717)) -- `User.other` has been removed, please use `data` instead ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) -- `SdkVersion.getIntegrations()` has been removed, please use `getIntegrationSet` instead ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) -- `SdkVersion.getPackages()` has been removed, please use `getPackageSet()` instead ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) -- `Device.language` has been removed, please use `locale` instead ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) -- `TraceContext.user` and `TraceContextUser` class have been removed, please use `userId` on `TraceContext` instead ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) -- `TransactionContext.fromSentryTrace()` has been removed, please use `Sentry.continueTrace()` instead ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) -- `SentryDataFetcherExceptionHandler` has been removed, please use `SentryGenericDataFetcherExceptionHandler` in combination with `SentryInstrumentation` instead ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) -- One of the `AndroidTransactionProfiler` constructors has been removed, please use a different one ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) -- Use String instead of UUID for SessionId ([#3834](https://github.com/getsentry/sentry-java/pull/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](https://github.com/getsentry/sentry-java/pull/3852)) ([#3851](https://github.com/getsentry/sentry-java/pull/3851)) -- All status codes below 400 are now mapped to `SpanStatus.OK` ([#3869](https://github.com/getsentry/sentry-java/pull/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](https://github.com/getsentry/sentry-java/pull/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](https://github.com/getsentry/sentry-java/pull/3706)) -- (Android) Enable Performance V2 by default ([#3824](https://github.com/getsentry/sentry-java/pull/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](https://github.com/getsentry/self-hosted/releases) is required. This only applies to self-hosted Sentry. If you are using [sentry.io](https://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. - -## Migration from `io.sentry:sentry-android-gradle-plugin:3.x.x` to `io.sentry:sentry-android-gradle-plugin:4.0.0` - -### Breaking Changes - -- Bumped Sentry Android SDK to `7.0.0`. Refer to the [section below](#migrating-from-iosentrysentry-android-6x-to-iosentrysentry-android-700) for details about changes to the SDK. -- Renamed `experimentalGuardsquareSupport` flag to `dexguardEnabled`. - -### Sentry Android SDK Compatibility - -You must use Sentry Gradle plugin 4.+ together with the Sentry Android SDK 7.+ otherwise, it might crash at runtime due to binary incompatibility. If you can't do that for some reason, you can specify the Sentry version via the plugin config block: - -```kotlin -sentry { - autoInstallation { - sentryVersion.set("7.0.0") - } -} -``` - -Similarly, if you have a Sentry SDK (e.g. `sentry-android-core`) dependency on one of your Gradle modules and you're updating it to 7.+, make sure the Gradle plugin is at 4.+, or specify the SDK version as shown in the snippet above. - -## Migrating from `io.sentry:sentry-android 6.x` to `io.sentry:sentry-android 7.0.0` - -### Breaking Changes - -- The minimum supported API level was updated to 19 (`minSdk`). -- The `sentry-android-okhttp` classes were deprecated in favor of `sentry-okhttp`, which is a pure Java module and can be used in non-Android projects. - - The `SentryOkHttpUtils` class was removed from the public API. If you were using it, consider filing a [feature request](https://github.com/getsentry/sentry-java/issues). -- If you're using `sentry-kotlin-extensions`, it now requires `kotlinx-coroutines-core` version `1.6.1` or higher. -- Moved `enableNdk` and `enableScopeSync` from `SentryOptions` to `SentryAndroidOptions`. -- Changed the return type of `SentryApolloInterceptor.BeforeSpanCallback` from `ISpan` to `ISpan?`. -- `Scope` now implements the `IScope` interface, therefore some methods like `ScopeCallback.run` accept `IScope` now. -- Some `Sentry.startTransaction` overloads do not exist anymore, and instead, you can set old options by passing a `TransactionOptions` object in. - -For example: - -```kotlin -// old -val transaction = Sentry.startTransaction("name", "op", bindToScope = true) -// new -val transaction = Sentry.startTransaction("name", "op", TransactionOptions().apply { isBindToScope = true }) -``` - -### Behavioral Changes - -- `Sentry.getSpan()` now returns the root span/transaction instead of the latest span. - - This will make the span hierarchy leaner and more readable. -- The SDK now captures failed HTTP and GraphQL (Apollo) requests by default. - - This can increase your event consumption and may affect your quota, because we will report failed network requests as Sentry events if you're using the `sentry-android-okhttp` or `sentry-apollo-3` integrations by default. You can customize what errors you want/don't want to have reported for [OkHttp](/platforms/android/integrations/okhttp/#http-client-errors) and [Apollo3](/platforms/android/integrations/apollo3/#graphql-client-errors) respectively. -- Added a deadline timeout for automatic transactions. - - This affects all automatically generated transactions on Android (UI, clicks). The default timeout is 30s, meaning the automatic transaction will be force-finished with the status `deadline_exceeded` when it reaches the deadline. -- The SDK now sets `ip_address` to \{\{auto}} by default, even if sendDefaultPII is disabled. - - We recommend you instead use the "Prevent Storing of IP Addresses" option in the "Security & Privacy" project settings on [sentry.io](https://sentry.io/). -- The `maxSpans` setting (defaults to 1000) is now enforced for nested child spans. This means a single transaction can have `maxSpans` number of children (nested or not) at most. - -### Sentry Integrations Version Compatibility - -Make sure to align _all_ Sentry dependencies (like `-timber`, `-okhttp` or other packages) to the same version when bumping the SDK to 7.+, otherwise, it will crash at runtime due to binary incompatibility. - -For example, if you're using the [Sentry Android Gradle plugin](https://github.com/getsentry/sentry-android-gradle-plugin) with the `autoInstallation` [feature](/platforms/android/configuration/gradle/#auto-installation) (enabled by default), make sure to use version 4.+ of the Gradle plugin together with version 7.+ of the SDK. If you can't do that for some reason, you can specify the Sentry version via the plugin config block: - -```kotlin -sentry { - autoInstallation { - sentryVersion.set("7.0.0") - } -} -``` - -Similarly, if you have a Sentry SDK (e.g. `sentry-android-core`) dependency on one of your Gradle modules and you're updating it to 7.+, make sure the Gradle plugin is at 4.+ or specify the SDK version as shown in the snippet above. - -### Sentry Self-hosted Compatibility - -- Starting with version `7.0.0` of `sentry`, [Sentry's version >= v22.12.0](https://github.com/getsentry/self-hosted/releases) is required to properly ingest transactions with unfinished spans. This only applies to self-hosted Sentry. If you are using [sentry.io](https://sentry.io), no action is needed. - -## Migrating from `io.sentry:sentry-android 6.14.x` to `io.sentry:sentry-android 6.15.0` - -The `sentry-compose-android` and `sentry-compose` integrations now declare their upstream dependencies as `compileOnly`. Make sure to have the `androidx.navigation:navigation-compose`, `androidx.compose.runtime:runtime`, and `androidx.compose.ui:ui` dependencies on the classpath if you're using those integrations. Otherwise, the application will crash with a `NoClassDefFoundError` exception. - -## Migrating from `io.sentry:sentry-android 6.2.x` to `io.sentry:sentry-android 6.3.0` - -The `sentry-android-okhttp`, `sentry-android-fragment`, and `sentry-android-timber` integrations now declare their upstream dependencies as `compileOnly`. Make sure to have the `okhttp`, `fragment`, and `timber` dependencies on the classpath if you're using those integrations or the application will crash with a `NoClassDefFoundError` exception. - -## Migrating from `io.sentry:sentry-android 6.x` to `io.sentry:sentry-android 6.2.0` - -- Kotlin plugin is upgraded to `1.6.10`. - -This version is still compatible with Kotlin `1.4`. - - - -This only affects integrations that are written in Kotlin, such as `timber`, `fragment`, `okhttp`, `navigation` and `compose`. - - - -## Migrating from `io.sentry:sentry-android 5.x` to `io.sentry:sentry-android 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. -- `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` -- Removed unnecessary abstractions - - `IBuildInfoProvider` is now `BuildInfoProvider` only. - - `IHandler` is now `MainLooperHandler` only. -- `ISpan` now has higher precision using the `System#nanoTime` instead of milliseconds. - -- Hints changed its type from `Object` to `io.sentry.Hint` - -_Old_: - -```kotlin -Sentry.captureException(RuntimeException("exception"), "myStringHint") -``` - -_New_: - -```kotlin -val hints = mutableMapOf("myHint" to "myStringHint") -Sentry.captureException(RuntimeException("exception"), hints) -``` - -- `SentryOptions#enableScopeSync` is now enabled by default, to disable it, see the code snippet below. - -```xml {filename:AndroidManifest.xml} - -``` - -- `SentryOptions#sendClientReports` is now enabled by default. To disable it, use the code snippet below: - -```xml {filename:AndroidManifest.xml} - -``` - -### Sentry Self-hosted Compatibility - -- Starting with version `6.0.0` of `sentry`, [Sentry's version >= v21.9.0](https://github.com/getsentry/self-hosted/releases) 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](https://sentry.io), no action is needed. - -There are more changes and refactors, but they are not user breaking changes. - -## Migrating to `io.sentry:sentry-android-timber 5.6.2` - -Starting from version `5.6.2`, the `Timber.tag` usage is no longer supported by our SDK (the tag will not be captured and reflected on Sentry). Please, vote on this [GitHub issue](https://github.com/getsentry/sentry-java/issues/1900) to let us know if we should provide support for that. - - - -Support for `Timber.tag` has been brought back in version `5.7.2`. - - - -## Migrating from `io.sentry:sentry-android-gradle-plugin 2.x` to `io.sentry:sentry-android-gradle-plugin 3.0.0` - -The `io.sentry.android.gradle` >= `3.0.0` requires [Android Gradle Plugin >= 7.0.0](https://developer.android.com/studio/releases/gradle-plugin#7-0-0). For older versions of the Android Gradle Plugin, use `io.sentry.android.gradle:2.+`. - -### includeProguardMapping - -The `autoUpload` flag has been deprecated in favor of two new options: - -- `includeProguardMapping` - Disables/enables Proguard mapping functionality. When enabled, generates a UUID and attempts to upload a Proguard mapping associated with that UUID to Sentry. When `autoUploadProguardMapping` is disabled, the plugin will only generate a `sentry-debug-meta.properties` file containing UUID, which can later be used to manually upload the mapping using, for example [sentry-cli](/cli/dif/#proguard-mapping-upload). -- `autoUploadProguardMapping` - Defines whether the gradle plugin should attempt to auto-upload the mapping file to Sentry. - When `includeProguardMapping` is disabled, this flag has no effect. - -_Old_: - -```groovy -sentry { - autoUpload = false -} -``` - -```kotlin -sentry { - autoUpload.set(false) -} -``` - -_New_: - -```groovy -sentry { - includeProguardMapping = true - autoUploadProguardMapping = false -} -``` - -```kotlin -sentry { - includeProguardMapping.set(true) - autoUploadProguardMapping.set(false) -} -``` - -### tracingInstrumentation - -The `io.sentry.android.gradle` enables the tracing instrumentation (via bytecode manipulation) for `androidx.sqlite` and `androidx.room` libraries by default, to disable it, see the code snippet below. - -```groovy -sentry { - // Enable or disable the tracing instrumentation. - // Does auto instrumentation for 'androidx.sqlite' and 'androidx.room' libraries. - // It starts and finishes a Span within any CRUD operation. - // Default is enabled. - // Only available v3.0.0 and above. - tracingInstrumentation { - enabled = false - } -} -``` - -```kotlin -sentry { - // Enable or disable the tracing instrumentation. - // Does auto instrumentation for 'androidx.sqlite' and 'androidx.room' libraries. - // It starts and finishes a Span within any CRUD operation. - // Default is enabled. - // Only available v3.0.0 and above. - tracingInstrumentation { - enabled.set(false) - } -} -``` - -## Migrating from `io.sentry:sentry-android-gradle-plugin 1.x` to `io.sentry:sentry-android-gradle-plugin 2.0.0` - -The `io.sentry.android.gradle` >= `2.0.0` requires [Android Gradle Plugin >= 4.0.0](https://developer.android.com/studio/releases/gradle-plugin#4-0-0). - -The `io.sentry.android.gradle` >= `2.0.0` must be applied to the `app/build.gradle` module (or the module that has `com.android.application` plugin applied). - -The `io.sentry.android.gradle` >= `2.0.0` publishes the Gradle Plugin Marker to Maven Central. As a result, you no longer need to set the `classpath`. - -_Old_: - -```groovy -buildscript { - repositories { - mavenCentral() - } - - dependencies { - classpath 'io.sentry:sentry-android-gradle-plugin:{version}' - } -} - -apply plugin: 'io.sentry.android.gradle' -``` - -_New_: - -```groovy -plugins { - id "io.sentry.android.gradle" version "{version}" -} - -buildscript { - repositories { - mavenCentral() - } -} -``` - -```kotlin -plugins { - id("io.sentry.android.gradle") version "{version}" -} - -buildscript { - repositories { - mavenCentral() - } -} -``` - -The `io.sentry.android.gradle` has been rewritten in Kotlin. As a result, the Groovy or Kotlin DSL syntax has slightly changed. - -The `autoProguardConfig` flag has been removed, the Android SDK >= `2.0.0` version already merges the ProGuard rules automatically. - -_Old_: - -```groovy -sentry { - autoProguardConfig false - autoUpload true - uploadNativeSymbols false - includeNativeSources false -} -``` - -_New_: - -```groovy -sentry { - autoUpload = true - uploadNativeSymbols = false - includeNativeSources = false -} -``` - -```kotlin -sentry { - autoUpload.set(true) - uploadNativeSymbols.set(false) - includeNativeSources.set(false) -} -``` - -## Migrating from `io.sentry:sentry-android 4.3.0` to `io.sentry:sentry-android 5.0.0` - -You may remove `android:extractNativeLibs="true"` meta-data in the `AndroidManifest` file or `android.bundle.enableUncompressedNativeLibs=false` in the `gradle.properties` file if you're using the [Android Native Development Kit](/platforms/android/configuration/using-ndk/). Sentry can now symbolicate events with the default value of [extractNativeLibs](https://developer.android.com/studio/releases/gradle-plugin#extractNativeLibs) and [android.bundle.enableUncompressedNativeLibs](https://developer.android.com/studio/releases/gradle-plugin#behavior-changes). - -`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](https://github.com/JetBrains/java-annotations): `@Nullable` and `@NotNull`. Kotlin compiler respects these annotations, so 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. - -`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_: - -```kotlin -SentryOptions#addEventProcessor { event, _ -> event } -``` - -_New_: - -```kotlin -SentryOptions#addEventProcessor(object : EventProcessor { - override fun process(event: SentryEvent, hint: Hint): SentryEvent? { - return event - } -}) -``` - -A random generated `installationId` replaces `Settings.Secure.ANDROID_ID`, which has been removed. This may affect the number of unique users displayed on the Issues page and Alerts. -If you always set a custom user using `Sentry.setUser(customUser)`, the behavior has not changed. While you don't have to make any update, if you want to maintain the old behavior, use the following code snippet: - -```java -User user = new User(); -user.setId(Settings.Secure.ANDROID_ID); - -Sentry.setUser(user); -``` - -`SentryOptions#setEnableSessionTracking(boolean)` is deprecated in favor of `SentryOptions#setEnableAutoSessionTracking(boolean)`. It will be removed in future. - -_Old_: - -```java -SentryAndroid.init(this, options -> { - options.setEnableSessionTracking(false); -}); -``` - -_New_: - -```java -SentryAndroid.init(this, options -> { - options.setEnableAutoSessionTracking(false); -}); -``` - -`io.sentry.session-tracking.enable` AndroidManifest meta-data is deprecated in favor of `io.sentry.auto-session-tracking.enable`. It will be removed in future. - -_Old_: - -```xml {filename:AndroidManifest.xml} - - - -``` - -_New_: - -```xml {filename:AndroidManifest.xml} - - - -``` - -## Migrating from `io.sentry:sentry-android 4.1.0` to `io.sentry:sentry-android 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: - -```java -Sentry.startTransaction("transaction-name", "operation-name"); -``` - -## Migrating from `io.sentry:sentry-android 2.x` to `io.sentry:sentry-android 3.x` - -### Package changes - -The package `io.sentry.core` has been renamed to `io.sentry`. To compile correctly, replace the strings on all the usages from `io.sentry.core.` to `io.sentry.` - -Other than that, the APIs didn't change. Release Heath sets by default. If you prefer not to track the health of your releases, disable it with: - -```xml - - - -``` - -## Migrating from `io.sentry:sentry-android 1.x` to `io.sentry:sentry-android 2.x` - -With Sentry Android, we've updated the API to resemble the [Unified API](https://develop.sentry.dev/sdk/miscellaneous/unified-api/) more closely. And now that the SDK isn't built on top of `io.sentry:sentry-java`, Sentry Android has more Android-specific features. - -If you want to upgrade from the previous version of the SDK, please check the following sections of changes that may need updating in your code. - -### Configuration - -The file `sentry.properties` used by the previous version of the SDK has been discontinued. Configurations for the new SDK are in `AndroidManifest.xml` or directly in the code. - -Example of the configuration in the Manifest: - -```xml - - - - -``` - -If you want to set the configuration manually in the code, you need to initialize the SDK with `SentryAndroid.init()` --- described in [Installation](#installation) --- in the same file as `SentryAndroidOptions`, which holds configuration items. - -### Installation - -The new SDK can initialize automatically, all you need to do is provide the DSN in your Manifest file, as shown in the previous example in [Configuration](#configuration). - -#### Manual Installation - -If you want to register any callback to filter and modify events and/or breadcrumbs, or if you want to provide the configuration values via code, you need to initialize the SDK using the `SentryAndroid.init()`. - -To initialize the SDK manually: - -- Disable the `auto-init` feature by providing the following line in the manifest: - - ```xml - - - - ``` - -- Initialize the SDK directly in your application: - -```java -SentryAndroid.init(this, options -> { - options.setDsn("___PUBLIC_DSN___"); -}); -``` - -```kotlin -SentryAndroid.init(this) { options -> - options.dsn = "___PUBLIC_DSN___" -} -``` - -### Releases - -Please note that the new SDK will send with each event a release version in a different format than the previous SDK. - -If you are using the [GitHub](/organization/integrations/source-code-mgmt/github/) or [GitLab](/organization/integrations/source-code-mgmt/gitlab/) integrations, you need to do one of the following: - -- [Use the new format](/platforms/android/configuration/releases/) -- Set the release in your `AndroidManifest.xml` -- Change your code as described in the configuration section - -### API - -#### Set tag - -_Old_: - -```java -Sentry.getContext().addTag("tagName", "tagValue"); -``` - -```kotlin -Sentry.getContext().addTag("tagName", "tagValue") -``` - -_New_: - -```java -Sentry.setTag("tagName", "tagValue"); -``` - -```kotlin -Sentry.setTag("tagName", "tagValue") -``` - -#### Capture custom exception - -_Old_: - -```java -try { - int x = 1 / 0; -} catch (Exception e) { - Sentry.capture(e); -} -``` - -```kotlin -try { - val x = 1 / 0 -} catch (e: Exception) { - Sentry.capture(e) -} -``` - -_New_: - -```java -try { - int x = 1 / 0; -} catch (Exception e) { - Sentry.captureException(e); -} -``` - -```kotlin -try { - val x = 1 / 0 -} catch (e: Exception) { - Sentry.captureException(e) -} -``` - -#### Capture a message - -_Old_: - -```java -Sentry.capture("This is a test"); -``` - -```kotlin -Sentry.capture("This is a test") -``` - -_New_: - -```java -Sentry.captureMessage("This is a test"); // SentryLevel.INFO by default -Sentry.captureMessage("This is a test", SentryLevel.WARNING); // or specific level -``` - -```kotlin -Sentry.captureMessage("This is a test") // SentryLevel.INFO by default -Sentry.captureMessage("This is a test", SentryLevel.WARNING) // or specific level -``` - -#### Breadcrumbs - -_Old_: - -```java -Sentry.getContext().recordBreadcrumb( - new BreadcrumbBuilder().setMessage("User made an action").build() -); -``` - -```kotlin -Sentry.getContext().recordBreadcrumb( - BreadcrumbBuilder().setMessage("User made an action").build() -) -``` - -_New_: - -```java -Sentry.addBreadcrumb("User made an action"); -``` - -```kotlin -Sentry.addBreadcrumb("User made an action") -``` - -#### User - -_Old_: - -```java -Sentry.getContext().setUser( - new UserBuilder().setEmail("hello@sentry.io").build() -); -``` - -```kotlin -Sentry.getContext().setUser( - UserBuilder().setEmail("hello@sentry.io").build() -) -``` - -_New_: - -```java -User user = new User(); -user.setEmail("hello@sentry.io"); -Sentry.setUser(user); -``` - -```kotlin -val user = User().apply { - email = "hello@sentry.io" -} -Sentry.setUser(user) -``` - -#### Set extra - -_Old_: - -```java -Sentry.getContext().addExtra("extra", "thing"); -``` - -```kotlin -Sentry.getContext().addExtra("extra", "thing") -``` - -_New_: - -```java -Sentry.setExtra("extra", "thing"); -``` - -```kotlin -Sentry.setExtra("extra", "thing") -``` - -#### Clear the Context/Scope - -_Old_: - -```java -Sentry.clearContext(); -``` - -```kotlin -Sentry.clearContext() -``` - -_New_: - -```java -Sentry.configureScope(s -> s.clear()); -``` - -```kotlin -Sentry.configureScope { it.clear() } -``` - -### Sentry Gradle Plugin - -Disable the `autoProguardConfig` flag from the Sentry Gradle Plugin since `io.sentry:sentry-android` >= `2.0.0` does this automatically. - -```groovy -sentry { - autoProguardConfig false -} -``` + diff --git a/docs/platforms/android/migration/timber-v5-6-2.mdx b/docs/platforms/android/migration/timber-v5-6-2.mdx new file mode 100644 index 0000000000000..41ae24dff35c0 --- /dev/null +++ b/docs/platforms/android/migration/timber-v5-6-2.mdx @@ -0,0 +1,13 @@ +--- +title: Migrate to sentry-android-timber 5.6.2 +sidebar_order: 8923 +description: "Learn about migrating to Sentry Android Timber integration 5.6.2." +--- + +Starting from version `5.6.2`, the `Timber.tag` usage is no longer supported by our SDK (the tag will not be captured and reflected on Sentry). Please, vote on this [GitHub issue](https://github.com/getsentry/sentry-java/issues/1900) to let us know if we should provide support for that. + + + +Support for `Timber.tag` has been brought back in version `5.7.2`. + + diff --git a/docs/platforms/android/migration/v1-to-v2.mdx b/docs/platforms/android/migration/v1-to-v2.mdx new file mode 100644 index 0000000000000..61b6bc2c3a755 --- /dev/null +++ b/docs/platforms/android/migration/v1-to-v2.mdx @@ -0,0 +1,263 @@ +--- +title: Migrate from sentry-android 1.x to 2.x +sidebar_order: 8950 +description: "Learn about migrating from Sentry Android SDK 1.x to 2.x." +--- + +With Sentry Android, we've updated the API to resemble the [Unified API](https://develop.sentry.dev/sdk/miscellaneous/unified-api/) more closely. And now that the SDK isn't built on top of `io.sentry:sentry-java`, Sentry Android has more Android-specific features. + +If you want to upgrade from the previous version of the SDK, please check the following sections of changes that may need updating in your code. + +## Configuration + +The file `sentry.properties` used by the previous version of the SDK has been discontinued. Configurations for the new SDK are in `AndroidManifest.xml` or directly in the code. + +Example of the configuration in the Manifest: + +```xml + + + + +``` + +If you want to set the configuration manually in the code, you need to initialize the SDK with `SentryAndroid.init()` --- described in [Installation](#installation) --- in the same file as `SentryAndroidOptions`, which holds configuration items. + +## Installation + +The new SDK can initialize automatically, all you need to do is provide the DSN in your Manifest file, as shown in the previous example in [Configuration](#configuration). + +### Manual Installation + +If you want to register any callback to filter and modify events and/or breadcrumbs, or if you want to provide the configuration values via code, you need to initialize the SDK using the `SentryAndroid.init()`. + +To initialize the SDK manually: + +- Disable the `auto-init` feature by providing the following line in the manifest: + + ```xml + + + + ``` + +- Initialize the SDK directly in your application: + +```java +SentryAndroid.init(this, options -> { + options.setDsn("___PUBLIC_DSN___"); +}); +``` + +```kotlin +SentryAndroid.init(this) { options -> + options.dsn = "___PUBLIC_DSN___" +} +``` + +## Releases + +Please note that the new SDK will send with each event a release version in a different format than the previous SDK. + +If you are using the [GitHub](/organization/integrations/source-code-mgmt/github/) or [GitLab](/organization/integrations/source-code-mgmt/gitlab/) integrations, you need to do one of the following: + +- [Use the new format](/platforms/android/configuration/releases/) +- Set the release in your `AndroidManifest.xml` +- Change your code as described in the configuration section + +## API + +### Set tag + +_Old_: + +```java +Sentry.getContext().addTag("tagName", "tagValue"); +``` + +```kotlin +Sentry.getContext().addTag("tagName", "tagValue") +``` + +_New_: + +```java +Sentry.setTag("tagName", "tagValue"); +``` + +```kotlin +Sentry.setTag("tagName", "tagValue") +``` + +### Capture custom exception + +_Old_: + +```java +try { + int x = 1 / 0; +} catch (Exception e) { + Sentry.capture(e); +} +``` + +```kotlin +try { + val x = 1 / 0 +} catch (e: Exception) { + Sentry.capture(e) +} +``` + +_New_: + +```java +try { + int x = 1 / 0; +} catch (Exception e) { + Sentry.captureException(e); +} +``` + +```kotlin +try { + val x = 1 / 0 +} catch (e: Exception) { + Sentry.captureException(e) +} +``` + +### Capture a message + +_Old_: + +```java +Sentry.capture("This is a test"); +``` + +```kotlin +Sentry.capture("This is a test") +``` + +_New_: + +```java +Sentry.captureMessage("This is a test"); // SentryLevel.INFO by default +Sentry.captureMessage("This is a test", SentryLevel.WARNING); // or specific level +``` + +```kotlin +Sentry.captureMessage("This is a test") // SentryLevel.INFO by default +Sentry.captureMessage("This is a test", SentryLevel.WARNING) // or specific level +``` + +### Breadcrumbs + +_Old_: + +```java +Sentry.getContext().recordBreadcrumb( + new BreadcrumbBuilder().setMessage("User made an action").build() +); +``` + +```kotlin +Sentry.getContext().recordBreadcrumb( + BreadcrumbBuilder().setMessage("User made an action").build() +) +``` + +_New_: + +```java +Sentry.addBreadcrumb("User made an action"); +``` + +```kotlin +Sentry.addBreadcrumb("User made an action") +``` + +### User + +_Old_: + +```java +Sentry.getContext().setUser( + new UserBuilder().setEmail("hello@sentry.io").build() +); +``` + +```kotlin +Sentry.getContext().setUser( + UserBuilder().setEmail("hello@sentry.io").build() +) +``` + +_New_: + +```java +User user = new User(); +user.setEmail("hello@sentry.io"); +Sentry.setUser(user); +``` + +```kotlin +val user = User().apply { + email = "hello@sentry.io" +} +Sentry.setUser(user) +``` + +### Set extra + +_Old_: + +```java +Sentry.getContext().addExtra("extra", "thing"); +``` + +```kotlin +Sentry.getContext().addExtra("extra", "thing") +``` + +_New_: + +```java +Sentry.setExtra("extra", "thing"); +``` + +```kotlin +Sentry.setExtra("extra", "thing") +``` + +### Clear the Context/Scope + +_Old_: + +```java +Sentry.clearContext(); +``` + +```kotlin +Sentry.clearContext() +``` + +_New_: + +```java +Sentry.configureScope(s -> s.clear()); +``` + +```kotlin +Sentry.configureScope { it.clear() } +``` + +## Sentry Gradle Plugin + +Disable the `autoProguardConfig` flag from the Sentry Gradle Plugin since `io.sentry:sentry-android` >= `2.0.0` does this automatically. + +```groovy +sentry { + autoProguardConfig false +} +``` diff --git a/docs/platforms/android/migration/v2-to-v3.mdx b/docs/platforms/android/migration/v2-to-v3.mdx new file mode 100644 index 0000000000000..4f99b251af339 --- /dev/null +++ b/docs/platforms/android/migration/v2-to-v3.mdx @@ -0,0 +1,17 @@ +--- +title: Migrate from sentry-android 2.x to 3.x +sidebar_order: 8945 +description: "Learn about migrating from Sentry Android SDK 2.x to 3.x." +--- + +## Package Changes + +The package `io.sentry.core` has been renamed to `io.sentry`. To compile correctly, replace the strings on all the usages from `io.sentry.core.` to `io.sentry.` + +Other than that, the APIs didn't change. Release Heath sets by default. If you prefer not to track the health of your releases, disable it with: + +```xml + + + +``` diff --git a/docs/platforms/android/migration/v4-1-to-v4-2.mdx b/docs/platforms/android/migration/v4-1-to-v4-2.mdx new file mode 100644 index 0000000000000..11b068d59df52 --- /dev/null +++ b/docs/platforms/android/migration/v4-1-to-v4-2.mdx @@ -0,0 +1,11 @@ +--- +title: Migrate from sentry-android 4.1.0 to 4.2.0 +sidebar_order: 8940 +description: "Learn about migrating from Sentry Android SDK 4.1.0 to 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: + +```java +Sentry.startTransaction("transaction-name", "operation-name"); +``` diff --git a/docs/platforms/android/migration/v4-3-to-v5.mdx b/docs/platforms/android/migration/v4-3-to-v5.mdx new file mode 100644 index 0000000000000..3405bb9e13419 --- /dev/null +++ b/docs/platforms/android/migration/v4-3-to-v5.mdx @@ -0,0 +1,81 @@ +--- +title: Migrate from sentry-android 4.3.0 to 5.0.0 +sidebar_order: 8935 +description: "Learn about migrating from Sentry Android SDK 4.3.0 to 5.0.0." +--- + +You may remove `android:extractNativeLibs="true"` meta-data in the `AndroidManifest` file or `android.bundle.enableUncompressedNativeLibs=false` in the `gradle.properties` file if you're using the [Android Native Development Kit](/platforms/android/configuration/using-ndk/). Sentry can now symbolicate events with the default value of [extractNativeLibs](https://developer.android.com/studio/releases/gradle-plugin#extractNativeLibs) and [android.bundle.enableUncompressedNativeLibs](https://developer.android.com/studio/releases/gradle-plugin#behavior-changes). + +`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](https://github.com/JetBrains/java-annotations): `@Nullable` and `@NotNull`. Kotlin compiler respects these annotations, so 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. + +`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_: + +```kotlin +SentryOptions#addEventProcessor { event, _ -> event } +``` + +_New_: + +```kotlin +SentryOptions#addEventProcessor(object : EventProcessor { + override fun process(event: SentryEvent, hint: Hint): SentryEvent? { + return event + } +}) +``` + +A random generated `installationId` replaces `Settings.Secure.ANDROID_ID`, which has been removed. This may affect the number of unique users displayed on the Issues page and Alerts. +If you always set a custom user using `Sentry.setUser(customUser)`, the behavior has not changed. While you don't have to make any update, if you want to maintain the old behavior, use the following code snippet: + +```java +User user = new User(); +user.setId(Settings.Secure.ANDROID_ID); + +Sentry.setUser(user); +``` + +`SentryOptions#setEnableSessionTracking(boolean)` is deprecated in favor of `SentryOptions#setEnableAutoSessionTracking(boolean)`. It will be removed in future. + +_Old_: + +```java +SentryAndroid.init(this, options -> { + options.setEnableSessionTracking(false); +}); +``` + +_New_: + +```java +SentryAndroid.init(this, options -> { + options.setEnableAutoSessionTracking(false); +}); +``` + +`io.sentry.session-tracking.enable` AndroidManifest meta-data is deprecated in favor of `io.sentry.auto-session-tracking.enable`. It will be removed in future. + +_Old_: + +```xml {filename:AndroidManifest.xml} + + + +``` + +_New_: + +```xml {filename:AndroidManifest.xml} + + + +``` diff --git a/docs/platforms/android/migration/v5-to-v6.mdx b/docs/platforms/android/migration/v5-to-v6.mdx new file mode 100644 index 0000000000000..8bfe1b814ba97 --- /dev/null +++ b/docs/platforms/android/migration/v5-to-v6.mdx @@ -0,0 +1,57 @@ +--- +title: Migrate from sentry-android 5.x to 6.0.0 +sidebar_order: 8920 +description: "Learn about migrating from Sentry Android SDK 5.x to 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. +- `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` +- Removed unnecessary abstractions + - `IBuildInfoProvider` is now `BuildInfoProvider` only. + - `IHandler` is now `MainLooperHandler` only. +- `ISpan` now has higher precision using the `System#nanoTime` instead of milliseconds. + +- Hints changed its type from `Object` to `io.sentry.Hint` + +_Old_: + +```kotlin +Sentry.captureException(RuntimeException("exception"), "myStringHint") +``` + +_New_: + +```kotlin +val hints = mutableMapOf("myHint" to "myStringHint") +Sentry.captureException(RuntimeException("exception"), hints) +``` + +- `SentryOptions#enableScopeSync` is now enabled by default, to disable it, see the code snippet below. + +```xml {filename:AndroidManifest.xml} + +``` + +- `SentryOptions#sendClientReports` is now enabled by default. To disable it, use the code snippet below: + +```xml {filename:AndroidManifest.xml} + +``` + +## Sentry Self-hosted Compatibility + +- Starting with version `6.0.0` of `sentry`, [Sentry's version >= v21.9.0](https://github.com/getsentry/self-hosted/releases) 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](https://sentry.io), no action is needed. + +There are more changes and refactors, but they are not user breaking changes. diff --git a/docs/platforms/android/migration/v6-14-to-v6-15.mdx b/docs/platforms/android/migration/v6-14-to-v6-15.mdx new file mode 100644 index 0000000000000..63042a470f241 --- /dev/null +++ b/docs/platforms/android/migration/v6-14-to-v6-15.mdx @@ -0,0 +1,7 @@ +--- +title: Migrate from sentry-android 6.14.x to 6.15.0 +sidebar_order: 8913 +description: "Learn about migrating from Sentry Android SDK 6.14.x to 6.15.0." +--- + +The `sentry-compose-android` and `sentry-compose` integrations now declare their upstream dependencies as `compileOnly`. Make sure to have the `androidx.navigation:navigation-compose`, `androidx.compose.runtime:runtime`, and `androidx.compose.ui:ui` dependencies on the classpath if you're using those integrations. Otherwise, the application will crash with a `NoClassDefFoundError` exception. diff --git a/docs/platforms/android/migration/v6-2-to-v6-3.mdx b/docs/platforms/android/migration/v6-2-to-v6-3.mdx new file mode 100644 index 0000000000000..0f815210b854e --- /dev/null +++ b/docs/platforms/android/migration/v6-2-to-v6-3.mdx @@ -0,0 +1,7 @@ +--- +title: Migrate from sentry-android 6.2.x to 6.3.0 +sidebar_order: 8915 +description: "Learn about migrating from Sentry Android SDK 6.2.x to 6.3.0." +--- + +The `sentry-android-okhttp`, `sentry-android-fragment`, and `sentry-android-timber` integrations now declare their upstream dependencies as `compileOnly`. Make sure to have the `okhttp`, `fragment`, and `timber` dependencies on the classpath if you're using those integrations or the application will crash with a `NoClassDefFoundError` exception. diff --git a/docs/platforms/android/migration/v6-to-v6-2.mdx b/docs/platforms/android/migration/v6-to-v6-2.mdx new file mode 100644 index 0000000000000..04effd986320e --- /dev/null +++ b/docs/platforms/android/migration/v6-to-v6-2.mdx @@ -0,0 +1,15 @@ +--- +title: Migrate from sentry-android 6.x to 6.2.0 +sidebar_order: 8918 +description: "Learn about migrating from Sentry Android SDK 6.x to 6.2.0." +--- + +- Kotlin plugin is upgraded to `1.6.10`. + +This version is still compatible with Kotlin `1.4`. + + + +This only affects integrations that are written in Kotlin, such as `timber`, `fragment`, `okhttp`, `navigation` and `compose`. + + diff --git a/docs/platforms/android/migration/v6-to-v7.mdx b/docs/platforms/android/migration/v6-to-v7.mdx new file mode 100644 index 0000000000000..8a9b3787c6cbe --- /dev/null +++ b/docs/platforms/android/migration/v6-to-v7.mdx @@ -0,0 +1,57 @@ +--- +title: Migrate from sentry-android 6.x to 7.0.0 +sidebar_order: 8910 +description: "Learn about migrating from Sentry Android SDK 6.x to 7.0.0." +--- + +## Breaking Changes + +- The minimum supported API level was updated to 19 (`minSdk`). +- The `sentry-android-okhttp` classes were deprecated in favor of `sentry-okhttp`, which is a pure Java module and can be used in non-Android projects. + - The `SentryOkHttpUtils` class was removed from the public API. If you were using it, consider filing a [feature request](https://github.com/getsentry/sentry-java/issues). +- If you're using `sentry-kotlin-extensions`, it now requires `kotlinx-coroutines-core` version `1.6.1` or higher. +- Moved `enableNdk` and `enableScopeSync` from `SentryOptions` to `SentryAndroidOptions`. +- Changed the return type of `SentryApolloInterceptor.BeforeSpanCallback` from `ISpan` to `ISpan?`. +- `Scope` now implements the `IScope` interface, therefore some methods like `ScopeCallback.run` accept `IScope` now. +- Some `Sentry.startTransaction` overloads do not exist anymore, and instead, you can set old options by passing a `TransactionOptions` object in. + +For example: + +```kotlin +// old +val transaction = Sentry.startTransaction("name", "op", bindToScope = true) +// new +val transaction = Sentry.startTransaction("name", "op", TransactionOptions().apply { isBindToScope = true }) +``` + +## Behavioral Changes + +- `Sentry.getSpan()` now returns the root span/transaction instead of the latest span. + - This will make the span hierarchy leaner and more readable. +- The SDK now captures failed HTTP and GraphQL (Apollo) requests by default. + - This can increase your event consumption and may affect your quota, because we will report failed network requests as Sentry events if you're using the `sentry-android-okhttp` or `sentry-apollo-3` integrations by default. You can customize what errors you want/don't want to have reported for [OkHttp](/platforms/android/integrations/okhttp/#http-client-errors) and [Apollo3](/platforms/android/integrations/apollo3/#graphql-client-errors) respectively. +- Added a deadline timeout for automatic transactions. + - This affects all automatically generated transactions on Android (UI, clicks). The default timeout is 30s, meaning the automatic transaction will be force-finished with the status `deadline_exceeded` when it reaches the deadline. +- The SDK now sets `ip_address` to \{\{auto}} by default, even if sendDefaultPII is disabled. + - We recommend you instead use the "Prevent Storing of IP Addresses" option in the "Security & Privacy" project settings on [sentry.io](https://sentry.io/). +- The `maxSpans` setting (defaults to 1000) is now enforced for nested child spans. This means a single transaction can have `maxSpans` number of children (nested or not) at most. + +## Sentry Integrations Version Compatibility + +Make sure to align _all_ Sentry dependencies (like `-timber`, `-okhttp` or other packages) to the same version when bumping the SDK to 7.+, otherwise, it will crash at runtime due to binary incompatibility. + +For example, if you're using the [Sentry Android Gradle plugin](https://github.com/getsentry/sentry-android-gradle-plugin) with the `autoInstallation` [feature](/platforms/android/configuration/gradle/#auto-installation) (enabled by default), make sure to use version 4.+ of the Gradle plugin together with version 7.+ of the SDK. If you can't do that for some reason, you can specify the Sentry version via the plugin config block: + +```kotlin +sentry { + autoInstallation { + sentryVersion.set("7.0.0") + } +} +``` + +Similarly, if you have a Sentry SDK (e.g. `sentry-android-core`) dependency on one of your Gradle modules and you're updating it to 7.+, make sure the Gradle plugin is at 4.+ or specify the SDK version as shown in the snippet above. + +## Sentry Self-hosted Compatibility + +- Starting with version `7.0.0` of `sentry`, [Sentry's version >= v22.12.0](https://github.com/getsentry/self-hosted/releases) is required to properly ingest transactions with unfinished spans. This only applies to self-hosted Sentry. If you are using [sentry.io](https://sentry.io), no action is needed. diff --git a/docs/platforms/android/migration/v7-to-v8.mdx b/docs/platforms/android/migration/v7-to-v8.mdx new file mode 100644 index 0000000000000..08bf230d6faa2 --- /dev/null +++ b/docs/platforms/android/migration/v7-to-v8.mdx @@ -0,0 +1,94 @@ +--- +title: Migrate from sentry 7.x to 8.0.0 +sidebar_order: 8900 +description: "Learn about migrating from Sentry Android SDK 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](https://github.com/getsentry/sentry-java/pull/3510)) +- Calling `Sentry.init()` on Android now throws a `IllegalArgumentException`, please use `SentryAndroid.init()` instead ([#3596](https://github.com/getsentry/sentry-java/pull/3596)) +- The previous metrics API has been removed from the SDK ([#3774](https://github.com/getsentry/sentry-java/pull/3774)) + - A new Metrics feature is now available. See the [Metrics documentation](/platforms/android/metrics/) for setup instructions. +- `enableTracing` option (a.k.a `enable-tracing`) has been removed from the SDK ([#3776](https://github.com/getsentry/sentry-java/pull/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](https://github.com/getsentry/sentry-java/pull/3556)) + - This will reduce the number of spans created by the SDK +- Replace `synchronized` methods and blocks with `ReentrantLock` (`AutoClosableReentrantLock`) ([#3715](https://github.com/getsentry/sentry-java/pull/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](https://github.com/getsentry/sentry-java/pull/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](https://github.com/getsentry/sentry-java/pull/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](https://github.com/getsentry/sentry-java/pull/3780)) +- `profilingTracesIntervalMillis` option for Android has been removed ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) +- `io.sentry.session-tracking.enable` manifest option has been removed ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) +- `Sentry.traceHeaders()` method has been removed, please use `Sentry.getTraceparent()` instead ([#3718](https://github.com/getsentry/sentry-java/pull/3718)) +- `Sentry.reportFullDisplayed()` method has been removed, please use `Sentry.reportFullyDisplayed()` instead ([#3717](https://github.com/getsentry/sentry-java/pull/3717)) +- `User.other` has been removed, please use `data` instead ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) +- `SdkVersion.getIntegrations()` has been removed, please use `getIntegrationSet` instead ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) +- `SdkVersion.getPackages()` has been removed, please use `getPackageSet()` instead ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) +- `Device.language` has been removed, please use `locale` instead ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) +- `TraceContext.user` and `TraceContextUser` class have been removed, please use `userId` on `TraceContext` instead ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) +- `TransactionContext.fromSentryTrace()` has been removed, please use `Sentry.continueTrace()` instead ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) +- `SentryDataFetcherExceptionHandler` has been removed, please use `SentryGenericDataFetcherExceptionHandler` in combination with `SentryInstrumentation` instead ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) +- One of the `AndroidTransactionProfiler` constructors has been removed, please use a different one ([#3780](https://github.com/getsentry/sentry-java/pull/3780)) +- Use String instead of UUID for SessionId ([#3834](https://github.com/getsentry/sentry-java/pull/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](https://github.com/getsentry/sentry-java/pull/3852)) ([#3851](https://github.com/getsentry/sentry-java/pull/3851)) +- All status codes below 400 are now mapped to `SpanStatus.OK` ([#3869](https://github.com/getsentry/sentry-java/pull/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](https://github.com/getsentry/sentry-java/pull/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](https://github.com/getsentry/sentry-java/pull/3706)) +- (Android) Enable Performance V2 by default ([#3824](https://github.com/getsentry/sentry-java/pull/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](https://github.com/getsentry/self-hosted/releases) is required. This only applies to self-hosted Sentry. If you are using [sentry.io](https://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. diff --git a/docs/platforms/apple/common/migration/index.mdx b/docs/platforms/apple/common/migration/index.mdx index 63cdb96f5e52a..8b81b903d90e1 100644 --- a/docs/platforms/apple/common/migration/index.mdx +++ b/docs/platforms/apple/common/migration/index.mdx @@ -2,583 +2,9 @@ title: Migration Guide sidebar_order: 8000 sidebar_section: configuration +description: "Migrate from an older version of Sentry's SDK for Apple platforms." --- -To upgrade from version 4.x of the SDK to version 9.x of the SDK, you must first migrate from 4.x to 5.x, then 5.x to 6.x, then 6.x to 7.x, 7.x to 8.x, and finally from 8.x to 9.x. +Here's a list of guides on migrating to a newer version of the Sentry Cocoa SDK. -## Migrating From 8.x to 9.x - -Migrating to 9.x from 8.x includes several breaking changes. We provide this guide to help you update your SDK. - -### Changes to Minimum OS Versions and Xcode - -We bumped the minimum supported OS versions to: -- **iOS**: 15.0 (previously 11.0) -- **macOS**: 10.14 (previously 10.13) -- **tvOS**: 15.0 (previously 11.0) -- **visionOS**: 1.0 (unchanged) -- **watchOS**: 8.0 (previously 4.0) - -We now build the precompiled XCFramework with **Xcode 16**. To submit to the App Store, Apple now requires Xcode 16. If you need a precompiled XCFramework built with Xcode 15, continue using Sentry SDK 8.x.x. - -Additionally, the Package.swift sets `swift-tools-version` to 6.0. - -### Carthage Support Dropped - -We dropped official support for Carthage in v9. If you're using Carthage, please migrate to Swift Package Manager (SPM) or manually install the [pre-built XCFramework from GitHub releases](https://github.com/getsentry/sentry-cocoa/releases). - -### Features Enabled by Default - -We now enabled the following features by default: - -- **Performance V2 is enabled by default**: The app start duration now finishes when the first frame is drawn instead of when the OS posts the `UIWindowDidBecomeVisibleNotification`. We removed the `enablePerformanceV2` option. -- **Pre-warmed app start tracking**: The SDK now collects pre-warmed app starts by default via `enablePreWarmedAppStartTracing`. -- App hang tracking V2: This is now the default only on **iOS and **tvOS** and we removed the option to enable/disable it. macOS still uses V1. - -### Disable App Hang Tracking for Extensions - -We now automatically disable app hang tracking for: Widgets, Live Activities, Action Extensions, (Siri) Intent Extensions, Share Extensions. These components run in separate processes or sandboxes with different execution characteristics, which can cause false positive app hang reports. - -### Structured Logging - -We moved structured logging out of experimental and made it part of the stable API. The `enableLogs` option moved from `options.experimental.enableLogs` to `options.enableLogs`. We added log APIs to `Hub` and `Client`, and logs now include a `sentry.replay_id` attribute. - -**Migration required:** Update your code from `options.experimental.enableLogs = true` to `options.enableLogs = true`. Logging is not enabled by default; you must explicitly set this option. - -#### HTTP Client Errors - -HTTP client errors now mark sessions as errored. This provides better visibility into failed network requests in your release health data. - -### Profiling Changes - -We removed all deprecated profiling APIs in version [9.0.0](https://github.com/getsentry/sentry-cocoa/releases/tag/9.0.0). - - - -The only supported profiling method is now UI Profiling (also known as continuous V2 profiling), which was introduced in [version 8.49.0](https://github.com/getsentry/sentry-cocoa/releases/tag/8.49.0). - -**Removed deprecated profiling options from `SentryOptions`:** -- `profilesSampleRate` - used for transaction-based profiling (deprecated) -- `profilesSampler` - used for transaction-based profiling (deprecated) -- `enableAppLaunchProfiling` - used for launch profiling (deprecated) - -**Migration to UI Profiling:** - -If you were using any of the deprecated profiling options, you need to migrate to UI Profiling. Configure profiling by assigning a closure to `SentryOptions.configureProfiling`: - -```swift -import Sentry - -SentrySDK.start { options in - options.dsn = "___PUBLIC_DSN___" - options.configureProfiling = { - $0.sessionSampleRate = 1 - $0.lifecycle = .manual // or .trace for trace-based lifecycle - } -} -``` - -For more information, see the UI Profiling documentation. - - - -### Breaking Changes - -#### Option Changes - -- `enableFileManagerSwizzling` is now a top-level non-experimental option and remains disabled by default. -- `enableDataSwizzling` is now a top-level option and is enabled by default. -- `enableLogs` is now a top-level non-experimental option and remains disabled by default (you must set it to `true` to enable logging). -- We increased the maximum attachment size to 200MB (previously 20MB) -- We removed the following methods and properties: - - `inAppExclude` (it had no effect) - - `integrations` - - `defaultIntegrations()` - - `enableTracing` (use `tracesSampleRate` or `tracesSampler` instead) - - `getStoreEndpoint()` - - `enablePerformanceV2` the behavior of this option is now enabled by default. - -#### Behavioral Breaking Changes - -- The default trace context status is now `ok` instead of `undefined`. -- The `function` property on `SentryFrame` now defaults to `nil` instead of `""` -- The `value` and `type` properties on `SentryException` are now nullable; when `NSException` has no reason, `type` is set to `nil` -- We changed the type of the `http.response.status_code` attribute for spans to int -- We converted `SentryDsn` to Swift and removed the public header file `SentryDsn.h` - -#### Renamed APIs - -- We renamed `SentryStructuredLogLevel` to `SentryLogLevel` -- We renamed `SentryStructuredLogAttribute` to `SentryLogAttribute` - -#### Removed APIs - -- We removed the `segment` property from `SentryTraceContext`, `SentryUser`, and `SentryBaggage` -- We removed the initializers from `SentryTraceContext` -- We removed `SentryDsn.getHash()` -- We removed `SentryFrame.instruction` - -We removed the following deprecated APIs: - -- `SentrySpan.setExtraValue(_:forKey:)` -- User feedback API (use the new feedback API instead) -- `Scope.useSpan()` (use `Scope.span` instead) -- `SentryDebugMeta.uuid` (use `debugID` instead) -- `SentryDebugMeta.name` (use `codeFile` instead) - -We made the following classes and APIs private: - -- `SentryEventDecoder` and `SentryEventDecodable` -- `SentryEnvelopeItemHeader` -- `SentryIntegrationProtocol` -- `SentrySession` -- `SentrySDKInfo` -- `SentryDebugImageProvider` - -#### Other breaking changes - -- We made the following classes `final`: `PreviewRedactOptions`, `SentryProfileOptions`, `SentryRedactViewHelper`, `SentryViewScreenshotOptions`, `SentryReplayOptions`, `SentryUserFeedbackConfiguration`, `SentryUserFeedbackFormConfiguration`, `SentryUserFeedbackThemeConfiguration`, `SentryUserFeedbackWidgetConfiguration`, `SentryFeedback`, and `SentryExperimentalOptions` - -For a complete list of changes, see the [Changelog of version 9.0.0](https://github.com/getsentry/sentry-cocoa/releases/tag/9.0.0) - -## Migrating From 7.x to 8.x - -Migrating to 8.x from 7.x includes a few breaking changes. We provide this guide to help you update your SDK. It's important to note that this version adds a dependency to Swift, and that we renamed the default branch on the [sentry-cocoa repository](https://github.com/getsentry/sentry-cocoa) from `master` to `main`. - -### Changes to Minimum OS Versions and Xcode - -The minimum supported OS versions have been bumped to macOS 10.13, iOS 11, tvOS 11, and watchOS 4. We bumped the minimum Xcode version to 13. - -### Features Enabled by Default - -The following features are now enabled by default: - -- The user interaction tracing integration -- The File I/O tracing integration -- Core Data tracing integration -- Capture failed requests -- App Hangs (not available - for watchOS) - -### Changes to Grouping - -App Hang events might group differently as we now set the event stack trace snapshot property to `true`. - -### Rename OOM to Watchdog Termination - -The OOM (out of memory integration) actually tracks [watchdog terminations](https://developer.apple.com/documentation/xcode/addressing-watchdog-terminations) based on heuristics. We renamed the integration to better reflect what it does. - -### Breaking Changes - -#### Configuration Changes - -This version includes the following configuration changes: - -- Rename `SentryOptions.enableAutoPerformanceTracking` to `SentryOptions.enableAutoPerformanceTracing` -- Rename `SentryOptions.enableUIViewControllerTracking` to `SentryOptions.enableUIViewControllerTracing` -- Rename `SentryOptions.enablePreWarmedAppStartTracking` to `SentryOptions.enablePreWarmedAppStartTracing` -- Rename `SentryOptions.enableFileIOTracking` to `SentryOptions.enableFileIOTracing` -- Rename `SentryOptions.enableCoreDataTracking` to `SentryOptions.enableCoreDataTracing` -- Rename `SentryOptions.enableOutOfMemoryTracking` to `SentryOptions.enableWatchdogTerminationTracking` - -#### Swift API Improvements - -We made some changes to make the API more ergonomic in Swift: - -- Rename `SentrySDK.addBreadcrumb(crumb:)` to `SentrySDK.addBreadcrumb(_ crumb:)` -- Rename `SentryScope.add(_ crumb:)` to `SentryScope.addBreadcrumb(_ crumb:)` -- Rename `SentryScope.add(_ attachment:)` to `SentryScope.addAttachment(_ attachment:)` -- Rename `Client` to `SentryClient` - -#### Cleanup Public Classes - -We cleaned up our public classes by removing a few functions and properties, that shouldn't be public, to make the API cleaner. In case we removed something you need, please [open an issue](https://github.com/getsentry/sentry-cocoa/issues/new/choose) on GitHub. - -- Make `SpanProtocol.data` non nullable -- Mark `[SpanProtocol setExtraValue:forKey:]` as deprecated -- Make `SpanContext` immutable - - Remove tags from `SpanContext` - - Remove context property from `SentrySpan` -- Remove `SentryScope.apply(to:)` -- Remove `SentryScope.apply(to:maxBreadcrumb:)` -- Remove `[SentryOptions initWithDict:didFailWithError:]` -- Remove `[SentryOptions sdkInfo]` -- Make `SentrySession` and `SentrySDKInfo` internal -- Remove default attachment content type -- Remove `captureEnvelope` from `SentryHub` and `SentryClient` -- Remove confusing transaction tag - -#### SDK Inits - -We removed the version of `SentrySDK.startWithOptions` that took a dictionary, and renamed `SentrySDK.startWithOptionsObject` to `SentrySDK.startWithOptions`. The recommended way to initialize Sentry has not changed: - - -```swift {tabTitle:Swift} -import Sentry - -SentrySDK.start { options in - options.dsn = "___PUBLIC_DSN___" - // ... -} -``` - -```objc {tabTitle:Objective-C} -@import Sentry; - -[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { - options.dsn = @"___PUBLIC_DSN___"; - // ... -}]; -``` - -#### SentrySDK.close Is Now Blocking - -`SentrySDK.close` now calls flush, which is a blocking call. - -## Migrating From 6.x to 7.x - - - -We recommend updating to at least [7.5.3](https://github.com/getsentry/sentry-cocoa/releases/tag/7.5.3), because the HTTP instrumentation can lead to crashes. Alternatively, you can also disable the feature. - - - -Migrating to 7.x from 6.x includes a few breaking changes. We provide this guide to help you to update your SDK. - -### Configuration Changes - -This version includes the following configuration changes: - -- Change the default maximum number of cached envelopes from 100 to 30. You can now configure this number with `SentryOptions.maxCacheItems`. -- When setting a value `SentryOptions.sampleRate` that is not >= 0.0 and <= 1.0 the SDK sets it to the default of 1.0 instead of keeping the set value. - -### Breaking Changes - -#### Issue Grouping - -This version introduces a change to the grouping of issues. The SDK now sets the `inApp` -flag for frames originating from only the main executable using [CFBundleExecutable](https://developer.apple.com/documentation/bundleresources/information_property_list/cfbundleexecutable). -In previous versions, all frames originating from the application bundle were marked as `inApp`. This had the -downside of marking frames of private frameworks inside the bundle as `inApp`. This problem is fixed now. -Applications using static frameworks shouldn't be affected by this change. -For more information read [mark in-app frames](/concepts/data-management/event-grouping/stack-trace-rules/#mark-in-app-frames). - -#### Cleanup Public Classes - -We cleaned up our public classes by removing a few functions and properties, that shouldn't be public, to make the API cleaner. In case we removed something you need, please [open an issue](https://github.com/getsentry/sentry-cocoa/issues/new/choose) on GitHub. - -- Remove `SentrySDK.currentHub` and `SentrySDK.setCurrentHub`. -- Remove `SentryClient.storeEnvelope`, which is reserved for Hybrid SDKs. -- Make `closeCachedSessionWithTimestamp` private, which is reserved for internal use. -- Remove deprecated `SentryHub.getScope`. Use `SentryHub.scope` instead. -- Replace `SentryException.thread` with `SentryException.threadId` and `SentryException.stacktrace` to align with the [unified API](https://develop.sentry.dev/sdk/miscellaneous/unified-api/). -- Replace dict `SentryMechanism.meta` with new class `SentryMechanismMeta` and move `SenryNSError` to `SentryMechanismMeta` to align with the [unified API](https://develop.sentry.dev/sdk/miscellaneous/unified-api/). -- Change `SentryEvent.timestamp` to `nullable`. - -### SentryLogLevel - -We replaced the `SentryLogLevel` with `SentryLevel`, renamed `logLevel` to `diagnosticLevel` -on `SentryOptions` to align with other Sentry SDKs, and set the default `diagnosticLevel` to -`SentryLevel.debug`. Furthermore, we removed setting the `logLevel` statically on the `SentrySDK`. -Please use the `SentryOptions` to set the `diagnosticLevel` instead. - -6.x - -```swift -SentrySDK.start { options in - options.logLevel = SentryLogLevel.verbose -} - -// Or - -SentrySDK.logLevel = SentryLogLevel.verbose -``` - -7.x - -```swift -SentrySDK.start { options in - options.diagnosticLevel = SentryLevel.debug -} -``` - -## Migrating From 5.x to 6.x - -Migrating to 6.x from 5.x includes a few breaking changes. We provide this guide to help you to update your SDK. - -### Configuration Changes - -This version includes the following configuration changes: - -- [Auto Session Tracking](https://github.com/getsentry/sentry-cocoa/blob/7876949ca78aebfe7883432e35727993c5c30829/Sources/Sentry/include/SentryOptions.h#L101) is enabled by default. [This feature](/product/releases/health/) is collecting and sending health data about the usage of your - application. -- [Attach stack traces](https://github.com/getsentry/sentry-cocoa/blob/b5bf9769a158c66a34352556ade243e55f163a27/Sources/Sentry/Public/SentryOptions.h#L109) 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 had previously removed the [enabled](https://github.com/getsentry/sentry-cocoa/blob/5.2.2/Sources/Sentry/include/SentryOptions.h#L63) option from SentryOptions, but we brought it back in version 6.0.7 with slightly changed functionality. Previously setting an empty or incorrect DSN also set `enabled` to `false`. This side effect is removed. Setting the DSN has no impact on `enabled`. If the DSN is nil or empty or `enabled` is set to `false` and the client won't send any data to Sentry. - -### Breaking Changes - -#### Store Endpoint - -This version uses the [envelope endpoint](https://develop.sentry.dev/sdk/data-model/envelopes/). If you are using self-hosted Sentry, you must use Sentry version `>= v20.6.0` or higher. If you are using sentry.io, there is no impact. For this change, we also now cache events in envelopes on the disk. We decided not to migrate the few cached events from 5.x to 6.x into envelopes. Instead, we remove them from the disk. As a result, you might lose a few cached events when upgrading. - -#### SDK Inits - -We removed the [deprecated SDK inits](https://github.com/getsentry/sentry-cocoa/blob/5.2.2/Sources/Sentry/include/SentrySDK.h#L35-L47). The recommended way to initialize Sentry is now: - - -```swift {tabTitle:Swift} -import Sentry - -SentrySDK.start { options in - options.dsn = "___PUBLIC_DSN___" - // ... -} -``` - -```objc {tabTitle:Objective-C} -@import Sentry; - -[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](https://github.com/getsentry/sentry-cocoa/issues/new/choose) and tell us your use case so we can evaluates whether to either make the class public again or provide another API for you. - -#### New type SentryId for eventId - -In 5.x, we used a nullable NSString to represent an event ID. The SDK, Hub, and Client returned this nullable NSString for the event ID to capture messages, events, errors, and so forth. In 6.x, we have a new type SentryId, which is not nullable, to represent an event ID. Instead of returning `nil` when an event couldn't be queued for submission we return `SentryId.empty`. - -Example in 5.x: - -```swift {tabTitle:Swift} -import Sentry - -let eventId = SentrySDK.capture(message: "A message") -if (nil != eventId) { - // event was queued for submission -} else { - // event wasn't queued for submission -} -``` - -```objc {tabTitle:Objective-C} -@import Sentry; - -SentryId *eventId = [SentrySDK captureMessage:@"A message"]; -if (nil != eventId) { - // event was queued for submission -} else { - // event wasn't queued for submission -} -``` - -Example in 6.x: - -```swift {tabTitle:Swift} -import Sentry - -let eventId = SentrySDK.capture(message: "A message") -if (eventId != SentryId.empty) { - // event was queued for submission -} else { - // event wasn't queued for submission -} -``` - -```objc {tabTitle:Objective-C} -@import Sentry; - -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](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/message/) for `event.message`. SentryMessage provides you the ability to pass a format string with parameters to Sentry, which can help group similar messages into the same issue. - -Example in 5.x: - -```swift {tabTitle:Swift} -import Sentry - -let event = Event() -event.message = "Hello World" -``` - -```objc {tabTitle:Objective-C} -@import Sentry; - -SentryEvent *event = [[SentryEvent alloc] init]; -event.message = "Hello World"; -``` - -Example in 6.x: - -```swift {tabTitle:Swift} -import Sentry - -let event = Event() -event.message = SentryMessage(formatted: "Hello World") -``` - -```objc {tabTitle:Objective-C} -@import Sentry; - -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 see the [Changelog](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md) for a complete list of changes. - -## Upgrading From 4.x to 5.x - -The samples below illustrate how the SDK works: - -### Initialization - -Example in 4.x: - - -```swift {tabTitle:Swift} -do { - Client.shared = try Client(dsn: "___PUBLIC_DSN___") - try Client.shared?.startCrashHandler() -} catch let error { - print("\(error)") -} -``` - -```objc {tabTitle:Objective-C} -NSError *error = nil; -SentryClient *client = [[SentryClient alloc] initWithDsn:@"___PUBLIC_DSN___" didFailWithError:&error]; -SentryClient.sharedClient = client; -[SentryClient.sharedClient startCrashHandlerWithError:&error]; -if (nil != error) { - NSLog(@"%@", error); -} -``` - -Example in 5.x: - - -```swift {tabTitle:Swift} -SentrySDK.start(options: [ - "dsn": "___PUBLIC_DSN___", - "debug": true -]) -``` - -```objc {tabTitle:Objective-C} -[SentrySDK startWithOptions:@{ - @"dsn": @"___PUBLIC_DSN___", - @"debug": @(YES) -}]; -``` - -### Add Breadcrumb - -Example in 4.x:` - -```swift {tabTitle:Swift} -Client.shared?.breadcrumbs.add(Breadcrumb(level: .info, category: "test")) -``` - -```objc {tabTitle:Objective-C} -[SentryClient.sharedClient.breadcrumbs addBreadcrumb:[[SentryBreadcrumb alloc] initWithLevel:kSentrySeverityInfo category:@"test"]]; -``` - -Example in 5.x: - -```swift {tabTitle:Swift} -SentrySDK.addBreadcrumb(Breadcrumb(level: .info, category: "test")) -``` - -```objc {tabTitle:Objective-C} -[SentrySDK addBreadcrumb:[[SentryBreadcrumb alloc] initWithLevel:kSentrySeverityInfo category:@"test"]]; -``` - -### CaptureMessage with tags/environment/extra - -Example in 4.x: - -```swift {tabTitle:Swift} -let event = Event(level: .debug) -event.message = "Test Message" -event.environment = "staging" -event.extra = ["ios": true] -Client.shared?.send(event: event) -``` - -```objc {tabTitle:Objective-C} -SentryEvent *event = [[SentryEvent alloc] initWithLevel:kSentrySeverityDebug]; -event.message = @"Test Message"; -event.environment = @"staging"; -event.extra = @{@"ios": @(YES)}; -[SentryClient.sharedClient sendEvent:event withCompletionHandler:nil]; -``` - -Example in 5.x: - -```swift {tabTitle:Swift} -SentrySDK.capture(message: "Test Message") { (scope) in - scope.setEnvironment("staging") - scope.setExtras(["ios": true]) - let u = Sentry.User(userId: "1") - u.email = "tony@example.com" - scope.setUser(u) -} -``` - -```objc {tabTitle:Objective-C} -[SentrySDK captureMessage:@"Test Message" withScopeBlock:^(SentryScope * _Nonnull scope) { - [scope setEnvironment:@"staging"]; - [scope setExtras:@{@"ios": @(YES)}]; - SentryUser *user = [[SentryUser alloc] initWithUserId:@"1"]; - user.email = @"tony@example.com"; - [scope setUser:user]; -}]; -``` - -### setUser - -Example in 4.x: - -```swift {tabTitle:Swift} -let u = User(userId: "1") -u.email = "tony@example.com" -Client.shared?.user = user -``` - -```objc {tabTitle:Objective-C} -SentryUser *user = [[SentryUser alloc] initWithUserId:@"1"]; -user.email = @"tony@example.com"; -SentryClient.sharedClient.user = user; -``` - -Example in 5.x: - -```swift {tabTitle:Swift} -let u = Sentry.User(userId: "1") -u.email = "tony@example.com" -SentrySDK.setUser(u) -``` - -```objc {tabTitle:Objective-C} -SentryUser *user = [[SentryUser alloc] initWithUserId:@"1"]; -user.email = @"tony@example.com"; -[SentrySDK setUser:user]; -``` + diff --git a/docs/platforms/apple/common/migration/v4-to-v5.mdx b/docs/platforms/apple/common/migration/v4-to-v5.mdx new file mode 100644 index 0000000000000..2a1c9fe3cde94 --- /dev/null +++ b/docs/platforms/apple/common/migration/v4-to-v5.mdx @@ -0,0 +1,142 @@ +--- +title: Upgrade from 4.x to 5.x +sidebar_order: 8940 +description: "Learn about migrating from Sentry Cocoa SDK 4.x to 5.x." +--- + +The samples below illustrate how the SDK works: + +## Initialization + +Example in 4.x: + + +```swift {tabTitle:Swift} +do { + Client.shared = try Client(dsn: "___PUBLIC_DSN___") + try Client.shared?.startCrashHandler() +} catch let error { + print("\(error)") +} +``` + +```objc {tabTitle:Objective-C} +NSError *error = nil; +SentryClient *client = [[SentryClient alloc] initWithDsn:@"___PUBLIC_DSN___" didFailWithError:&error]; +SentryClient.sharedClient = client; +[SentryClient.sharedClient startCrashHandlerWithError:&error]; +if (nil != error) { + NSLog(@"%@", error); +} +``` + +Example in 5.x: + + +```swift {tabTitle:Swift} +SentrySDK.start(options: [ + "dsn": "___PUBLIC_DSN___", + "debug": true +]) +``` + +```objc {tabTitle:Objective-C} +[SentrySDK startWithOptions:@{ + @"dsn": @"___PUBLIC_DSN___", + @"debug": @(YES) +}]; +``` + +## Add Breadcrumb + +Example in 4.x:` + +```swift {tabTitle:Swift} +Client.shared?.breadcrumbs.add(Breadcrumb(level: .info, category: "test")) +``` + +```objc {tabTitle:Objective-C} +[SentryClient.sharedClient.breadcrumbs addBreadcrumb:[[SentryBreadcrumb alloc] initWithLevel:kSentrySeverityInfo category:@"test"]]; +``` + +Example in 5.x: + +```swift {tabTitle:Swift} +SentrySDK.addBreadcrumb(Breadcrumb(level: .info, category: "test")) +``` + +```objc {tabTitle:Objective-C} +[SentrySDK addBreadcrumb:[[SentryBreadcrumb alloc] initWithLevel:kSentrySeverityInfo category:@"test"]]; +``` + +## CaptureMessage with tags/environment/extra + +Example in 4.x: + +```swift {tabTitle:Swift} +let event = Event(level: .debug) +event.message = "Test Message" +event.environment = "staging" +event.extra = ["ios": true] +Client.shared?.send(event: event) +``` + +```objc {tabTitle:Objective-C} +SentryEvent *event = [[SentryEvent alloc] initWithLevel:kSentrySeverityDebug]; +event.message = @"Test Message"; +event.environment = @"staging"; +event.extra = @{@"ios": @(YES)}; +[SentryClient.sharedClient sendEvent:event withCompletionHandler:nil]; +``` + +Example in 5.x: + +```swift {tabTitle:Swift} +SentrySDK.capture(message: "Test Message") { (scope) in + scope.setEnvironment("staging") + scope.setExtras(["ios": true]) + let u = Sentry.User(userId: "1") + u.email = "tony@example.com" + scope.setUser(u) +} +``` + +```objc {tabTitle:Objective-C} +[SentrySDK captureMessage:@"Test Message" withScopeBlock:^(SentryScope * _Nonnull scope) { + [scope setEnvironment:@"staging"]; + [scope setExtras:@{@"ios": @(YES)}]; + SentryUser *user = [[SentryUser alloc] initWithUserId:@"1"]; + user.email = @"tony@example.com"; + [scope setUser:user]; +}]; +``` + +## setUser + +Example in 4.x: + +```swift {tabTitle:Swift} +let u = User(userId: "1") +u.email = "tony@example.com" +Client.shared?.user = user +``` + +```objc {tabTitle:Objective-C} +SentryUser *user = [[SentryUser alloc] initWithUserId:@"1"]; +user.email = @"tony@example.com"; +SentryClient.sharedClient.user = user; +``` + +Example in 5.x: + +```swift {tabTitle:Swift} +let u = Sentry.User(userId: "1") +u.email = "tony@example.com" +SentrySDK.setUser(u) +``` + +```objc {tabTitle:Objective-C} +SentryUser *user = [[SentryUser alloc] initWithUserId:@"1"]; +user.email = @"tony@example.com"; +[SentrySDK setUser:user]; +``` diff --git a/docs/platforms/apple/common/migration/v5-to-v6.mdx b/docs/platforms/apple/common/migration/v5-to-v6.mdx new file mode 100644 index 0000000000000..5fedf29780334 --- /dev/null +++ b/docs/platforms/apple/common/migration/v5-to-v6.mdx @@ -0,0 +1,145 @@ +--- +title: Migrate from 5.x to 6.x +sidebar_order: 8930 +description: "Learn about migrating from Sentry Cocoa SDK 5.x to 6.x." +--- + +Migrating to 6.x from 5.x includes a few breaking changes. We provide this guide to help you to update your SDK. + +## Configuration Changes + +This version includes the following configuration changes: + +- [Auto Session Tracking](https://github.com/getsentry/sentry-cocoa/blob/7876949ca78aebfe7883432e35727993c5c30829/Sources/Sentry/include/SentryOptions.h#L101) is enabled by default. [This feature](/product/releases/health/) is collecting and sending health data about the usage of your + application. +- [Attach stack traces](https://github.com/getsentry/sentry-cocoa/blob/b5bf9769a158c66a34352556ade243e55f163a27/Sources/Sentry/Public/SentryOptions.h#L109) 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 had previously removed the [enabled](https://github.com/getsentry/sentry-cocoa/blob/5.2.2/Sources/Sentry/include/SentryOptions.h#L63) option from SentryOptions, but we brought it back in version 6.0.7 with slightly changed functionality. Previously setting an empty or incorrect DSN also set `enabled` to `false`. This side effect is removed. Setting the DSN has no impact on `enabled`. If the DSN is nil or empty or `enabled` is set to `false` and the client won't send any data to Sentry. + +## Breaking Changes + +### Store Endpoint + +This version uses the [envelope endpoint](https://develop.sentry.dev/sdk/data-model/envelopes/). If you are using self-hosted Sentry, you must use Sentry version `>= v20.6.0` or higher. If you are using sentry.io, there is no impact. For this change, we also now cache events in envelopes on the disk. We decided not to migrate the few cached events from 5.x to 6.x into envelopes. Instead, we remove them from the disk. As a result, you might lose a few cached events when upgrading. + +### SDK Inits + +We removed the [deprecated SDK inits](https://github.com/getsentry/sentry-cocoa/blob/5.2.2/Sources/Sentry/include/SentrySDK.h#L35-L47). The recommended way to initialize Sentry is now: + + +```swift {tabTitle:Swift} +import Sentry + +SentrySDK.start { options in + options.dsn = "___PUBLIC_DSN___" + // ... +} +``` + +```objc {tabTitle:Objective-C} +@import Sentry; + +[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](https://github.com/getsentry/sentry-cocoa/issues/new/choose) and tell us your use case so we can evaluates whether to either make the class public again or provide another API for you. + +### New type SentryId for eventId + +In 5.x, we used a nullable NSString to represent an event ID. The SDK, Hub, and Client returned this nullable NSString for the event ID to capture messages, events, errors, and so forth. In 6.x, we have a new type SentryId, which is not nullable, to represent an event ID. Instead of returning `nil` when an event couldn't be queued for submission we return `SentryId.empty`. + +Example in 5.x: + +```swift {tabTitle:Swift} +import Sentry + +let eventId = SentrySDK.capture(message: "A message") +if (nil != eventId) { + // event was queued for submission +} else { + // event wasn't queued for submission +} +``` + +```objc {tabTitle:Objective-C} +@import Sentry; + +SentryId *eventId = [SentrySDK captureMessage:@"A message"]; +if (nil != eventId) { + // event was queued for submission +} else { + // event wasn't queued for submission +} +``` + +Example in 6.x: + +```swift {tabTitle:Swift} +import Sentry + +let eventId = SentrySDK.capture(message: "A message") +if (eventId != SentryId.empty) { + // event was queued for submission +} else { + // event wasn't queued for submission +} +``` + +```objc {tabTitle:Objective-C} +@import Sentry; + +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](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/message/) for `event.message`. SentryMessage provides you the ability to pass a format string with parameters to Sentry, which can help group similar messages into the same issue. + +Example in 5.x: + +```swift {tabTitle:Swift} +import Sentry + +let event = Event() +event.message = "Hello World" +``` + +```objc {tabTitle:Objective-C} +@import Sentry; + +SentryEvent *event = [[SentryEvent alloc] init]; +event.message = "Hello World"; +``` + +Example in 6.x: + +```swift {tabTitle:Swift} +import Sentry + +let event = Event() +event.message = SentryMessage(formatted: "Hello World") +``` + +```objc {tabTitle:Objective-C} +@import Sentry; + +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 see the [Changelog](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md) for a complete list of changes. diff --git a/docs/platforms/apple/common/migration/v6-to-v7.mdx b/docs/platforms/apple/common/migration/v6-to-v7.mdx new file mode 100644 index 0000000000000..8058ab558055c --- /dev/null +++ b/docs/platforms/apple/common/migration/v6-to-v7.mdx @@ -0,0 +1,70 @@ +--- +title: Migrate from 6.x to 7.x +sidebar_order: 8920 +description: "Learn about migrating from Sentry Cocoa SDK 6.x to 7.x." +--- + + + +We recommend updating to at least [7.5.3](https://github.com/getsentry/sentry-cocoa/releases/tag/7.5.3), because the HTTP instrumentation can lead to crashes. Alternatively, you can also disable the feature. + + + +Migrating to 7.x from 6.x includes a few breaking changes. We provide this guide to help you to update your SDK. + +## Configuration Changes + +This version includes the following configuration changes: + +- Change the default maximum number of cached envelopes from 100 to 30. You can now configure this number with `SentryOptions.maxCacheItems`. +- When setting a value `SentryOptions.sampleRate` that is not >= 0.0 and <= 1.0 the SDK sets it to the default of 1.0 instead of keeping the set value. + +## Breaking Changes + +### Issue Grouping + +This version introduces a change to the grouping of issues. The SDK now sets the `inApp` +flag for frames originating from only the main executable using [CFBundleExecutable](https://developer.apple.com/documentation/bundleresources/information_property_list/cfbundleexecutable). +In previous versions, all frames originating from the application bundle were marked as `inApp`. This had the +downside of marking frames of private frameworks inside the bundle as `inApp`. This problem is fixed now. +Applications using static frameworks shouldn't be affected by this change. +For more information read [mark in-app frames](/concepts/data-management/event-grouping/stack-trace-rules/#mark-in-app-frames). + +### Cleanup Public Classes + +We cleaned up our public classes by removing a few functions and properties, that shouldn't be public, to make the API cleaner. In case we removed something you need, please [open an issue](https://github.com/getsentry/sentry-cocoa/issues/new/choose) on GitHub. + +- Remove `SentrySDK.currentHub` and `SentrySDK.setCurrentHub`. +- Remove `SentryClient.storeEnvelope`, which is reserved for Hybrid SDKs. +- Make `closeCachedSessionWithTimestamp` private, which is reserved for internal use. +- Remove deprecated `SentryHub.getScope`. Use `SentryHub.scope` instead. +- Replace `SentryException.thread` with `SentryException.threadId` and `SentryException.stacktrace` to align with the [unified API](https://develop.sentry.dev/sdk/miscellaneous/unified-api/). +- Replace dict `SentryMechanism.meta` with new class `SentryMechanismMeta` and move `SenryNSError` to `SentryMechanismMeta` to align with the [unified API](https://develop.sentry.dev/sdk/miscellaneous/unified-api/). +- Change `SentryEvent.timestamp` to `nullable`. + +## SentryLogLevel + +We replaced the `SentryLogLevel` with `SentryLevel`, renamed `logLevel` to `diagnosticLevel` +on `SentryOptions` to align with other Sentry SDKs, and set the default `diagnosticLevel` to +`SentryLevel.debug`. Furthermore, we removed setting the `logLevel` statically on the `SentrySDK`. +Please use the `SentryOptions` to set the `diagnosticLevel` instead. + +6.x + +```swift +SentrySDK.start { options in + options.logLevel = SentryLogLevel.verbose +} + +// Or + +SentrySDK.logLevel = SentryLogLevel.verbose +``` + +7.x + +```swift +SentrySDK.start { options in + options.diagnosticLevel = SentryLevel.debug +} +``` diff --git a/docs/platforms/apple/common/migration/v7-to-v8.mdx b/docs/platforms/apple/common/migration/v7-to-v8.mdx new file mode 100644 index 0000000000000..92f23fa6e2d47 --- /dev/null +++ b/docs/platforms/apple/common/migration/v7-to-v8.mdx @@ -0,0 +1,97 @@ +--- +title: Migrate from 7.x to 8.x +sidebar_order: 8910 +description: "Learn about migrating from Sentry Cocoa SDK 7.x to 8.x." +--- + +Migrating to 8.x from 7.x includes a few breaking changes. We provide this guide to help you update your SDK. It's important to note that this version adds a dependency to Swift, and that we renamed the default branch on the [sentry-cocoa repository](https://github.com/getsentry/sentry-cocoa) from `master` to `main`. + +## Changes to Minimum OS Versions and Xcode + +The minimum supported OS versions have been bumped to macOS 10.13, iOS 11, tvOS 11, and watchOS 4. We bumped the minimum Xcode version to 13. + +## Features Enabled by Default + +The following features are now enabled by default: + +- The user interaction tracing integration +- The File I/O tracing integration +- Core Data tracing integration +- Capture failed requests +- App Hangs (not available + for watchOS) + +## Changes to Grouping + +App Hang events might group differently as we now set the event stack trace snapshot property to `true`. + +## Rename OOM to Watchdog Termination + +The OOM (out of memory integration) actually tracks [watchdog terminations](https://developer.apple.com/documentation/xcode/addressing-watchdog-terminations) based on heuristics. We renamed the integration to better reflect what it does. + +## Breaking Changes + +### Configuration Changes + +This version includes the following configuration changes: + +- Rename `SentryOptions.enableAutoPerformanceTracking` to `SentryOptions.enableAutoPerformanceTracing` +- Rename `SentryOptions.enableUIViewControllerTracking` to `SentryOptions.enableUIViewControllerTracing` +- Rename `SentryOptions.enablePreWarmedAppStartTracking` to `SentryOptions.enablePreWarmedAppStartTracing` +- Rename `SentryOptions.enableFileIOTracking` to `SentryOptions.enableFileIOTracing` +- Rename `SentryOptions.enableCoreDataTracking` to `SentryOptions.enableCoreDataTracing` +- Rename `SentryOptions.enableOutOfMemoryTracking` to `SentryOptions.enableWatchdogTerminationTracking` + +### Swift API Improvements + +We made some changes to make the API more ergonomic in Swift: + +- Rename `SentrySDK.addBreadcrumb(crumb:)` to `SentrySDK.addBreadcrumb(_ crumb:)` +- Rename `SentryScope.add(_ crumb:)` to `SentryScope.addBreadcrumb(_ crumb:)` +- Rename `SentryScope.add(_ attachment:)` to `SentryScope.addAttachment(_ attachment:)` +- Rename `Client` to `SentryClient` + +### Cleanup Public Classes + +We cleaned up our public classes by removing a few functions and properties, that shouldn't be public, to make the API cleaner. In case we removed something you need, please [open an issue](https://github.com/getsentry/sentry-cocoa/issues/new/choose) on GitHub. + +- Make `SpanProtocol.data` non nullable +- Mark `[SpanProtocol setExtraValue:forKey:]` as deprecated +- Make `SpanContext` immutable + - Remove tags from `SpanContext` + - Remove context property from `SentrySpan` +- Remove `SentryScope.apply(to:)` +- Remove `SentryScope.apply(to:maxBreadcrumb:)` +- Remove `[SentryOptions initWithDict:didFailWithError:]` +- Remove `[SentryOptions sdkInfo]` +- Make `SentrySession` and `SentrySDKInfo` internal +- Remove default attachment content type +- Remove `captureEnvelope` from `SentryHub` and `SentryClient` +- Remove confusing transaction tag + +### SDK Inits + +We removed the version of `SentrySDK.startWithOptions` that took a dictionary, and renamed `SentrySDK.startWithOptionsObject` to `SentrySDK.startWithOptions`. The recommended way to initialize Sentry has not changed: + + +```swift {tabTitle:Swift} +import Sentry + +SentrySDK.start { options in + options.dsn = "___PUBLIC_DSN___" + // ... +} +``` + +```objc {tabTitle:Objective-C} +@import Sentry; + +[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { + options.dsn = @"___PUBLIC_DSN___"; + // ... +}]; +``` + +### SentrySDK.close Is Now Blocking + +`SentrySDK.close` now calls flush, which is a blocking call. diff --git a/docs/platforms/apple/common/migration/v8-to-v9.mdx b/docs/platforms/apple/common/migration/v8-to-v9.mdx new file mode 100644 index 0000000000000..cf8ff3a29f096 --- /dev/null +++ b/docs/platforms/apple/common/migration/v8-to-v9.mdx @@ -0,0 +1,138 @@ +--- +title: Migrate from 8.x to 9.x +sidebar_order: 8900 +description: "Learn about migrating from Sentry Cocoa SDK 8.x to 9.x." +--- + +Migrating to 9.x from 8.x includes several breaking changes. We provide this guide to help you update your SDK. + +## Changes to Minimum OS Versions and Xcode + +We bumped the minimum supported OS versions to: +- **iOS**: 15.0 (previously 11.0) +- **macOS**: 10.14 (previously 10.13) +- **tvOS**: 15.0 (previously 11.0) +- **visionOS**: 1.0 (unchanged) +- **watchOS**: 8.0 (previously 4.0) + +We now build the precompiled XCFramework with **Xcode 16**. To submit to the App Store, Apple now requires Xcode 16. If you need a precompiled XCFramework built with Xcode 15, continue using Sentry SDK 8.x.x. + +Additionally, the Package.swift sets `swift-tools-version` to 6.0. + +## Carthage Support Dropped + +We dropped official support for Carthage in v9. If you're using Carthage, please migrate to Swift Package Manager (SPM) or manually install the [pre-built XCFramework from GitHub releases](https://github.com/getsentry/sentry-cocoa/releases). + +## Features Enabled by Default + +We now enabled the following features by default: + +- **Performance V2 is enabled by default**: The app start duration now finishes when the first frame is drawn instead of when the OS posts the `UIWindowDidBecomeVisibleNotification`. We removed the `enablePerformanceV2` option. +- **Pre-warmed app start tracking**: The SDK now collects pre-warmed app starts by default via `enablePreWarmedAppStartTracing`. +- App hang tracking V2: This is now the default only on **iOS and **tvOS** and we removed the option to enable/disable it. macOS still uses V1. + +## Disable App Hang Tracking for Extensions + +We now automatically disable app hang tracking for: Widgets, Live Activities, Action Extensions, (Siri) Intent Extensions, Share Extensions. These components run in separate processes or sandboxes with different execution characteristics, which can cause false positive app hang reports. + +## Structured Logging + +We moved structured logging out of experimental and made it part of the stable API. The `enableLogs` option moved from `options.experimental.enableLogs` to `options.enableLogs`. We added log APIs to `Hub` and `Client`, and logs now include a `sentry.replay_id` attribute. + +**Migration required:** Update your code from `options.experimental.enableLogs = true` to `options.enableLogs = true`. Logging is not enabled by default; you must explicitly set this option. + +### HTTP Client Errors + +HTTP client errors now mark sessions as errored. This provides better visibility into failed network requests in your release health data. + +## Profiling Changes + +We removed all deprecated profiling APIs in version [9.0.0](https://github.com/getsentry/sentry-cocoa/releases/tag/9.0.0). + + + +The only supported profiling method is now UI Profiling (also known as continuous V2 profiling), which was introduced in [version 8.49.0](https://github.com/getsentry/sentry-cocoa/releases/tag/8.49.0). + +**Removed deprecated profiling options from `SentryOptions`:** +- `profilesSampleRate` - used for transaction-based profiling (deprecated) +- `profilesSampler` - used for transaction-based profiling (deprecated) +- `enableAppLaunchProfiling` - used for launch profiling (deprecated) + +**Migration to UI Profiling:** + +If you were using any of the deprecated profiling options, you need to migrate to UI Profiling. Configure profiling by assigning a closure to `SentryOptions.configureProfiling`: + +```swift +import Sentry + +SentrySDK.start { options in + options.dsn = "___PUBLIC_DSN___" + options.configureProfiling = { + $0.sessionSampleRate = 1 + $0.lifecycle = .manual // or .trace for trace-based lifecycle + } +} +``` + +For more information, see the UI Profiling documentation. + + + +## Breaking Changes + +### Option Changes + +- `enableFileManagerSwizzling` is now a top-level non-experimental option and remains disabled by default. +- `enableDataSwizzling` is now a top-level option and is enabled by default. +- `enableLogs` is now a top-level non-experimental option and remains disabled by default (you must set it to `true` to enable logging). +- We increased the maximum attachment size to 200MB (previously 20MB) +- We removed the following methods and properties: + - `inAppExclude` (it had no effect) + - `integrations` + - `defaultIntegrations()` + - `enableTracing` (use `tracesSampleRate` or `tracesSampler` instead) + - `getStoreEndpoint()` + - `enablePerformanceV2` the behavior of this option is now enabled by default. + +### Behavioral Breaking Changes + +- The default trace context status is now `ok` instead of `undefined`. +- The `function` property on `SentryFrame` now defaults to `nil` instead of `""` +- The `value` and `type` properties on `SentryException` are now nullable; when `NSException` has no reason, `type` is set to `nil` +- We changed the type of the `http.response.status_code` attribute for spans to int +- We converted `SentryDsn` to Swift and removed the public header file `SentryDsn.h` + +### Renamed APIs + +- We renamed `SentryStructuredLogLevel` to `SentryLogLevel` +- We renamed `SentryStructuredLogAttribute` to `SentryLogAttribute` + +### Removed APIs + +- We removed the `segment` property from `SentryTraceContext`, `SentryUser`, and `SentryBaggage` +- We removed the initializers from `SentryTraceContext` +- We removed `SentryDsn.getHash()` +- We removed `SentryFrame.instruction` + +We removed the following deprecated APIs: + +- `SentrySpan.setExtraValue(_:forKey:)` +- User feedback API (use the new feedback API instead) +- `Scope.useSpan()` (use `Scope.span` instead) +- `SentryDebugMeta.uuid` (use `debugID` instead) +- `SentryDebugMeta.name` (use `codeFile` instead) + +We made the following classes and APIs private: + +- `SentryEventDecoder` and `SentryEventDecodable` +- `SentryEnvelopeItemHeader` +- `SentryIntegrationProtocol` +- `SentrySession` +- `SentrySDKInfo` +- `SentryDebugImageProvider` + +### Other Breaking Changes + +- We made the following classes `final`: `PreviewRedactOptions`, `SentryProfileOptions`, `SentryRedactViewHelper`, `SentryViewScreenshotOptions`, `SentryReplayOptions`, `SentryUserFeedbackConfiguration`, `SentryUserFeedbackFormConfiguration`, `SentryUserFeedbackThemeConfiguration`, `SentryUserFeedbackWidgetConfiguration`, `SentryFeedback`, and `SentryExperimentalOptions` + +For a complete list of changes, see the [Changelog of version 9.0.0](https://github.com/getsentry/sentry-cocoa/releases/tag/9.0.0)