diff --git a/docs/migration/v8-to-v9.md b/docs/migration/v8-to-v9.md index 5a8e2f6f1806..b49a3e8f161e 100644 --- a/docs/migration/v8-to-v9.md +++ b/docs/migration/v8-to-v9.md @@ -2,7 +2,7 @@ **DISCLAIMER: THIS MIGRATION GUIDE IS WORK IN PROGRESS** -Version 9 of the Sentry SDK concerns itself with API cleanup and compatibility updates. +Version 9 of the Sentry SDK concerns API cleanup and compatibility updates. This update contains behavioral changes that will not be caught by TypeScript or linters, so we recommend carefully reading the section on [Behavioral Changes](#2-behavior-changes). Before updating to version `9.x` of the SDK, we recommend upgrading to the latest version of `8.x`. @@ -14,14 +14,14 @@ Lower versions may continue to work, but may not support all features. ## 1. Version Support Changes: Version 9 of the Sentry SDK has new compatibility ranges for runtimes and frameworks. -We periodically update the compatibility ranges in major versions to increase reliability and quality of APIs and instrumentation data. +We periodically update the compatibility ranges in major versions to increase the reliability and quality of APIs and instrumentation data. ### General Runtime Support Changes -**ECMAScript Version:** All of the JavaScript code in the Sentry SDK packages may now contain ECMAScript 2020 features. +**ECMAScript Version:** All the JavaScript code in the Sentry SDK packages may now contain ECMAScript 2020 features. This includes features like Nullish Coalescing (`??`), Optional Chaining (`?.`), `String.matchAll()`, Logical Assignment Operators (`&&=`, `||=`, `??=`), and `Promise.allSettled()`. -If you observe failures due to syntax or features listed above, it may be an indicator that your current runtime does not support ES2020. +If you observe failures due to syntax or features listed above, it may indicate that your current runtime does not support ES2020. If your runtime does not support ES2020, we recommend transpiling the SDK using Babel or similar tooling. **Node.js:** The minimum supported Node.js version is **18.0.0**, except for ESM-only SDKs (nuxt, solidstart, astro) which require Node **18.19.1** or up. @@ -61,40 +61,42 @@ Older Typescript versions _may_ still work, but we will not test them anymore an - If you use the optional `captureConsoleIntegration` and set `attachStackTrace: true` in your `Sentry.init` call, console messages will no longer be marked as unhandled (i.e. `handled: false`) but as handled (i.e. `handled: true`). If you want to keep sending them as unhandled, configure the `handled` option when adding the integration: -```js -Sentry.init({ - integrations: [Sentry.captureConsoleIntegration({ handled: false })], - attachStackTrace: true, -}); -``` + ```js + Sentry.init({ + integrations: [Sentry.captureConsoleIntegration({ handled: false })], + attachStackTrace: true, + }); + ``` - Dropping spans in the `beforeSendSpan` hook is no longer possible. - The `beforeSendSpan` hook now receives the root span as well as the child spans. - In previous versions, we determined if tracing is enabled (for Tracing Without Performance) by checking if either `tracesSampleRate` or `traceSampler` are _defined_ at all, in `Sentry.init()`. This means that e.g. the following config would lead to tracing without performance (=tracing being enabled, even if no spans would be started): -```js -Sentry.init({ - tracesSampleRate: undefined, -}); -``` + ```js + Sentry.init({ + tracesSampleRate: undefined, + }); + ``` -In v9, an `undefined` value will be treated the same as if the value is not defined at all. You'll need to set `tracesSampleRate: 0` if you want to enable tracing without performance. + In v9, an `undefined` value will be treated the same as if the value is not defined at all. You'll need to set `tracesSampleRate: 0` if you want to enable tracing without performance. - The `getCurrentHub().getIntegration(IntegrationClass)` method will always return `null` in v9. This has already stopped working mostly in v8, because we stopped exposing integration classes. In v9, the fallback behavior has been removed. Note that this does not change the type signature and is thus not technically breaking, but still worth pointing out. - The `startSpan` behavior was slightly changed if you pass a custom `scope` to the span start options: While in v8, the passed scope was set active directly on the passed scope, in v9, the scope is cloned. This behavior change does not apply to `@sentry/node` where the scope was already cloned. This change was made to ensure that the span only remains active within the callback and to align behavior between `@sentry/node` and all other SDKs. As a result of the change, your span hierarchy should be more accurate. However, be aware that modifying the scope (e.g. set tags) within the `startSpan` callback behaves a bit differently now. -```js -startSpan({ name: 'example', scope: customScope }, () => { - getCurrentScope().setTag('tag-a', 'a'); // this tag will only remain within the callback - // set the tag directly on customScope in addition, if you want to to persist the tag outside of the callback - customScope.setTag('tag-a', 'a'); -}); -``` + ```js + startSpan({ name: 'example', scope: customScope }, () => { + getCurrentScope().setTag('tag-a', 'a'); // this tag will only remain within the callback + // set the tag directly on customScope in addition, if you want to to persist the tag outside of the callback + customScope.setTag('tag-a', 'a'); + }); + ``` ### `@sentry/node` -- When `skipOpenTelemetrySetup: true` is configured, `httpIntegration({ spans: false })` will be configured by default. This means that you no longer have to specify this yourself in this scenario. With this change, no spans are emitted once `skipOpenTelemetrySetup: true` is configured, without any further configuration being needed. +- When `skipOpenTelemetrySetup: true` is configured, `httpIntegration({ spans: false })` will be configured by default. + + This means that you no longer have to specify this yourself in this scenario. With this change, no spans are emitted once `skipOpenTelemetrySetup: true` is configured, without any further configuration being needed. - The `requestDataIntegration` will no longer automatically set the user from `request.user`. This is an express-specific, undocumented behavior, and also conflicts with our privacy-by-default strategy. Starting in v9, you'll need to manually call `Sentry.setUser()` e.g. in a middleware to set the user on Sentry events. @@ -102,7 +104,7 @@ startSpan({ name: 'example', scope: customScope }, () => { ### `@sentry/browser` -- The `captureUserFeedback` method has been removed. Use `captureFeedback` instead and update the `comments` field to `message`. +- The `captureUserFeedback` method has been removed. Use the `captureFeedback` method instead and update the `comments` field to `message`. ### `@sentry/nextjs` @@ -130,7 +132,7 @@ TODO ## 3. Package Removals -As part of an architectural cleanup we deprecated the following packages: +As part of an architectural cleanup, we deprecated the following packages: - `@sentry/utils` - `@sentry/types` @@ -139,7 +141,7 @@ All of these packages exports and APIs have been moved into the `@sentry/core` p The `@sentry/utils` package will no longer be published. -The `@sentry/types` package will continue to be published but it is deprecated and we don't plan on extending its APi. +The `@sentry/types` package will continue to be published but it is deprecated and we don't plan on extending its API. You may experience slight compatibility issues in the future by using it. We decided to keep this package around to temporarily lessen the upgrade burden. It will be removed in a future major version. @@ -166,10 +168,9 @@ Sentry.init({ - The `DEFAULT_USER_INCLUDES` constant has been removed. -### `@sentry/react` +### `@sentry/browser` -- The `wrapUseRoutes` method has been removed. Use `wrapUseRoutesV6` or `wrapUseRoutesV7` instead depending on what version of react router you are using. -- The `wrapCreateBrowserRouter` method has been removed. Use `wrapCreateBrowserRouterV6` or `wrapCreateBrowserRouterV7` depending on what version of react router you are using. +- The `captureUserFeedback` method has been removed. Use the `captureFeedback` method instead and update the `comments` field to `message`. ### `@sentry/core` @@ -177,7 +178,7 @@ Sentry.init({ - The `validSeverityLevels` export has been removed. There is no replacement. - The `makeFifoCache` method has been removed. There is no replacement. - The `arrayify` export has been removed. There is no replacement. -- The `BAGGAGE_HEADER_NAME` export has been removed. Use `"baggage"` string constant directly instead. +- The `BAGGAGE_HEADER_NAME` export has been removed. Use the `"baggage"` string constant directly instead. - The `flatten` export has been removed. There is no replacement. - The `urlEncode` method has been removed. There is no replacement. - The `getDomElement` method has been removed. There is no replacement. @@ -193,32 +194,34 @@ The following changes are unlikely to affect users of the SDK. They are listed h - `client._prepareEvent()` now requires a currentScope & isolationScope to be passed as last arugments -### `@sentry/browser` - -- The `captureUserFeedback` method has been removed. Use `captureFeedback` instead and update the `comments` field to `message`. - ### `@sentry/nestjs` -- Removed `WithSentry` decorator. Use `SentryExceptionCaptured` instead. +- Removed `WithSentry` decorator. Use the `SentryExceptionCaptured` decorator instead. - Removed `SentryService`. - If you are using `@sentry/nestjs` you can safely remove any references to the `SentryService`. - If you are using another package migrate to `@sentry/nestjs` and remove the `SentryService` afterwards. + - If you are using `@sentry/nestjs` you can safely remove any references to the `SentryService`. + - If you are using another package migrate to `@sentry/nestjs` and remove the `SentryService` afterward. - Removed `SentryTracingInterceptor`. - If you are using `@sentry/nestjs` you can safely remove any references to the `SentryTracingInterceptor`. - If you are using another package migrate to `@sentry/nestjs` and remove the `SentryTracingInterceptor` afterwards. + - If you are using `@sentry/nestjs` you can safely remove any references to the `SentryTracingInterceptor`. + - If you are using another package migrate to `@sentry/nestjs` and remove the `SentryTracingInterceptor` afterward. - Removed `SentryGlobalGenericFilter`. - Use the `SentryGlobalFilter` instead. - The `SentryGlobalFilter` is a drop-in replacement. + - Use the `SentryGlobalFilter` instead. + - The `SentryGlobalFilter` is a drop-in replacement. - Removed `SentryGlobalGraphQLFilter`. - Use the `SentryGlobalFilter` instead. - The `SentryGlobalFilter` is a drop-in replacement. + - Use the `SentryGlobalFilter` instead. + - The `SentryGlobalFilter` is a drop-in replacement. + +### `@sentry/react` + +- The `wrapUseRoutes` method has been removed. Use the `wrapUseRoutesV6` or `wrapUseRoutesV7` methods instead depending on what version of react router you are using. +- The `wrapCreateBrowserRouter` method has been removed. Use the `wrapCreateBrowserRouterV6` or `wrapCreateBrowserRouterV7` methods depending on what version of react router you are using. ## `@sentry/vue` - The options `tracingOptions`, `trackComponents`, `timeout`, `hooks` have been removed everywhere except in the `tracingOptions` option of `vueIntegration()`. + These options should now be set as follows: - ```ts + ```js import * as Sentry from '@sentry/vue'; Sentry.init({ @@ -250,13 +253,25 @@ Let us know if this is causing issues in your setup by opening an issue on GitHu ### `@sentry/deno` -- The import of Sentry from the deno registry has changed. Use `import * as Sentry from 'https://deno.land/x/sentry/build/index.mjs'` instead. +- The import of Sentry from the deno registry has changed. Use the `import * as Sentry from 'https://deno.land/x/sentry/build/index.mjs'` import instead. + + ```js + // before + import * as Sentry from 'https://deno.land/x/sentry/index.mjs'; + + // after + import * as Sentry from 'https://deno.land/x/sentry/build/index.mjs'; + ``` ## 6. Type Changes In v8, types have been exported from `@sentry/types`, while implementations have been exported from other classes. + This led to some duplication, where we had to keep an interface in `@sentry/types`, while the implementation mirroring that interface was kept e.g. in `@sentry/core`. -Since v9, the types have been merged into `@sentry/core`, which removed some of this duplication. This means that certain things that used to be a separate interface, will not expect an actual instance of the class/concrete implementation. This should not affect most users, unless you relied on passing things with a similar shape to internal methods. The following types are affected: + +Since v9, the types have been merged into `@sentry/core`, which removed some of this duplication. This means that certain things that used to be a separate interface, will not expect an actual instance of the class/concrete implementation. + +This should not affect most users unless you relied on passing things with a similar shape to internal methods. The following types are affected: - `Scope` now always expects the `Scope` class - The `TransactionNamingScheme` type has been removed. There is no replacement. @@ -272,6 +287,7 @@ Since v9, the types have been merged into `@sentry/core`, which removed some of Version support timelines are stressful for anybody using the SDK, so we won't be defining one. Instead, we will be applying bug fixes and features to older versions as long as there is demand for them. + We also hold ourselves to high standards security-wise, meaning that if any vulnerabilities are found, we will in almost all cases backport them. Note, that we will decide on a case-per-case basis, what gets backported or not. @@ -290,22 +306,23 @@ The following outlines deprecations that were introduced in version 8 of the SDK - **Passing `undefined` to `tracesSampleRate` / `tracesSampler` / `enableTracing` will be handled differently in v9** - In v8, a setup like the following: +In v8, explicitly setting `tracesSampleRate` (even if it is set to `undefined`) will result in tracing being _enabled_, although no spans will be generated. - ```ts - Sentry.init({ - tracesSampleRate: undefined, - }); - ``` +```ts +Sentry.init({ + tracesSampleRate: undefined, +}); +``` - Will result in tracing being _enabled_, although no spans will be generated. - In v9, we will streamline this behavior so that passing `undefined` will result in tracing being disabled, the same as not passing the option at all. - If you are relying on `undefined` being passed in and having tracing enabled because of this, you should update your config to set e.g. `tracesSampleRate: 0` instead, which will also enable tracing in v9. +In v9, we will streamline this behavior so that passing `undefined` will result in tracing being disabled, the same as not passing the option at all. + +If you are relying on `undefined` being passed in and having tracing enabled because of this, you should update your config to set e.g. `tracesSampleRate: 0` instead, which will also enable tracing in v9. - **The `autoSessionTracking` option is deprecated.** - To enable session tracking, it is recommended to unset `autoSessionTracking` and ensure that either, in browser environments the `browserSessionIntegration` is added, or in server environments the `httpIntegration` is added. - To disable session tracking, it is recommended unset `autoSessionTracking` and to remove the `browserSessionIntegration` in browser environments, or in server environments configure the `httpIntegration` with the `trackIncomingRequestsAsSessions` option set to `false`. +To enable session tracking, it is recommended to unset `autoSessionTracking` and ensure that either, in browser environments the `browserSessionIntegration` is added, or in server environments the `httpIntegration` is added. + +To disable session tracking, it is recommended unset `autoSessionTracking` and to remove the `browserSessionIntegration` in browser environments, or in server environments configure the `httpIntegration` with the `trackIncomingRequestsAsSessions` option set to `false`. - **The metrics API has been removed from the SDK.** @@ -315,8 +332,7 @@ The Sentry metrics beta has ended and the metrics API has been removed from the - **The `@sentry/utils` package has been deprecated. Import everything from `@sentry/core` instead.** -- Deprecated `AddRequestDataToEventOptions.transaction`. This option effectively doesn't do anything anymore, and will - be removed in v9. +- Deprecated `AddRequestDataToEventOptions.transaction`. This option effectively doesn't do anything anymore, and will be removed in v9. - Deprecated `TransactionNamingScheme` type. - Deprecated `validSeverityLevels`. Will not be replaced. - Deprecated `urlEncode`. No replacements. @@ -325,7 +341,7 @@ The Sentry metrics beta has ended and the metrics API has been removed from the - Deprecated `arrayify`. No replacements. - Deprecated `memoBuilder`. No replacements. - Deprecated `getNumberOfUrlSegments`. No replacements. -- Deprecated `BAGGAGE_HEADER_NAME`. Use `"baggage"` string constant directly instead. +- Deprecated `BAGGAGE_HEADER_NAME`. Use the `"baggage"` string constant directly instead. - Deprecated `makeFifoCache`. No replacements. - Deprecated `dynamicRequire`. No replacements. - Deprecated `flatten`. No replacements. @@ -347,13 +363,13 @@ The Sentry metrics beta has ended and the metrics API has been removed from the ## `@sentry/nestjs` -- Deprecated `@WithSentry`. Use `@SentryExceptionCaptured` instead. -- Deprecated `SentryTracingInterceptor`. +- Deprecated the `@WithSentry` decorator. Use the `@SentryExceptionCaptured` decorator instead. +- Deprecated the `SentryTracingInterceptor` method. If you are using `@sentry/nestjs` you can safely remove any references to the `SentryTracingInterceptor`. - If you are using another package migrate to `@sentry/nestjs` and remove the `SentryTracingInterceptor` afterwards. + If you are using another package migrate to `@sentry/nestjs` and remove the `SentryTracingInterceptor` afterward. - Deprecated `SentryService`. If you are using `@sentry/nestjs` you can safely remove any references to the `SentryService`. - If you are using another package migrate to `@sentry/nestjs` and remove the `SentryService` afterwards. + If you are using another package migrate to `@sentry/nestjs` and remove the `SentryService` afterward. - Deprecated `SentryGlobalGenericFilter`. Use the `SentryGlobalFilter` instead. The `SentryGlobalFilter` is a drop-in replacement. @@ -377,23 +393,24 @@ The Sentry metrics beta has ended and the metrics API has been removed from the ## `@sentry/vue` - Deprecated `tracingOptions`, `trackComponents`, `timeout`, `hooks` options everywhere other than in the `tracingOptions` option of the `vueIntegration()`. - These options should now be set as follows: - ```ts - import * as Sentry from '@sentry/vue'; +These options should now be set as follows: - Sentry.init({ - integrations: [ - Sentry.vueIntegration({ - tracingOptions: { - trackComponents: true, - timeout: 1000, - hooks: ['mount', 'update', 'unmount'], - }, - }), - ], - }); - ``` +```ts +import * as Sentry from '@sentry/vue'; + +Sentry.init({ + integrations: [ + Sentry.vueIntegration({ + tracingOptions: { + trackComponents: true, + timeout: 1000, + hooks: ['mount', 'update', 'unmount'], + }, + }), + ], +}); +``` - Deprecated `logErrors` in the `vueIntegration`. The Sentry Vue error handler will propagate the error to a user-defined error handler or just re-throw the error (which will log the error without modifying). @@ -401,24 +418,25 @@ The Sentry metrics beta has ended and the metrics API has been removed from the ## `@sentry/nuxt` and `@sentry/vue` - When component tracking is enabled, "update" spans are no longer created by default. - Add an `"update"` item to the `tracingOptions.hooks` option via the `vueIntegration()` to restore this behavior. - ```ts - Sentry.init({ - integrations: [ - Sentry.vueIntegration({ - tracingOptions: { - trackComponents: true, - hooks: [ - 'mount', - 'update', // <-- - 'unmount', - ], - }, - }), - ], - }); - ``` +Add an `"update"` item to the `tracingOptions.hooks` option via the `vueIntegration()` to restore this behavior. + +```ts +Sentry.init({ + integrations: [ + Sentry.vueIntegration({ + tracingOptions: { + trackComponents: true, + hooks: [ + 'mount', + 'update', // <-- + 'unmount', + ], + }, + }), + ], +}); +``` ## `@sentry/astro` @@ -430,16 +448,16 @@ The Sentry metrics beta has ended and the metrics API has been removed from the ## `@sentry/react` -- Deprecated `wrapUseRoutes`. Use `wrapUseRoutesV6` or `wrapUseRoutesV7` instead. -- Deprecated `wrapCreateBrowserRouter`. Use `wrapCreateBrowserRouterV6` or `wrapCreateBrowserRouterV7` instead. +- Deprecated `wrapUseRoutes`. Use the `wrapUseRoutesV6` or `wrapUseRoutesV7` methods instead. +- Deprecated `wrapCreateBrowserRouter`. Use the `wrapCreateBrowserRouterV6` or `wrapCreateBrowserRouterV7` methods instead. ## `@sentry/nextjs` -- Deprecated `hideSourceMaps`. No replacements. The SDK emits hidden sourcemaps by default. +- Deprecated the `hideSourceMaps` option. There are no replacements for this option. The SDK emits hidden sourcemaps by default. ## `@sentry/opentelemetry` -- Deprecated `generateSpanContextForPropagationContext` in favor of doing this manually - we do not need this export anymore. +- Deprecated the `generateSpanContextForPropagationContext` method. There are no replacements for this method. ## Server-side SDKs (`@sentry/node` and all dependents)