diff --git a/docs/migration/v8-to-v9.md b/docs/migration/v8-to-v9.md index 487dbee7cf4c..94fd64683c69 100644 --- a/docs/migration/v8-to-v9.md +++ b/docs/migration/v8-to-v9.md @@ -1,18 +1,14 @@ # Upgrading from 8.x to 9.x -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). +Version 9 of the Sentry JavaScript SDK concerns API cleanup and version support changes. +This update contains behavioral changes that will not be caught by type checkers, linters or tests, so we recommend carefully reading through the entire migration guide instead of purely relying on automatic tooling. -Before updating to version `9.x` of the SDK, we recommend upgrading to the latest version of `8.x`. -You can then go through the [Deprecations in 8.x](#deprecations-in-8x) and remove and migrate usages of deprecated APIs in your code before upgrading to `9.x`. - -Version 9 of the JavaScript SDK is compatible with Sentry self-hosted versions 24.4.2 or higher (unchanged from last major). +`v9` of the SDK is compatible with Sentry self-hosted versions 24.4.2 or higher (unchanged from v8). 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 the reliability and quality of APIs and instrumentation data. ### General Runtime Support Changes @@ -23,7 +19,6 @@ If you observe failures due to syntax or features listed above, it may indicate 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 (`@sentry/astro`, `@sentry/nuxt`, `@sentry/sveltekit`) which require Node.js version **18.19.1** or higher. -We no longer test against Node 14 and Node 16 and cannot guarantee that the SDK will work as expected on these versions. **Browsers:** Due to SDK code now including ES2020 features, the minimum supported browser list now looks as follows: @@ -34,7 +29,7 @@ We no longer test against Node 14 and Node 16 and cannot guarantee that the SDK - Opera 67 - Samsung Internet 13.0 -If you need to support older browsers, we recommend transpiling your code using Babel or similar tooling. +If you need to support older browsers, we recommend transpiling your code using SWC, Babel or similar tooling. **Deno:** The minimum supported Deno version is now **2.0.0**. @@ -50,40 +45,33 @@ Support for the following frameworks and library versions are dropped: ### TypeScript Version Policy -In preparation for the OpenTelemetry SDK v2, which will raise the minimum required TypeScript version, the minimum required TypeScript version is increased to version `5.0.4`. +In preparation for v2 of the OpenTelemetry SDK, which will raise the minimum required TypeScript version, the minimum required TypeScript version is increased to version `5.0.4`. Additionally, like the OpenTelemetry SDK, the Sentry JavaScript SDK will follow [DefinitelyType's version support policy](https://github.com/DefinitelyTyped/DefinitelyTyped#support-window) which has a support time frame of 2 years for any released version of TypeScript. -Older Typescript versions _may_ still work, but we will not test them anymore and no more guarantees apply. +Older Typescript versions _may_ continue to be compatible, but no guarantees apply. ## 2. Behavior Changes ### `@sentry/core` / All SDKs -- 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, - }); - ``` +- Dropping spans in the `beforeSendSpan` hook is no longer possible. + This means you can no longer return `null` from the `beforeSendSpan` hook. + This hook is intended to be used to add additional data to spans or remove unwanted attributes (for example for PII stripping). + To control which spans are recorded, we recommend configuring [integrations](https://docs.sentry.io/platforms/javascript/configuration/integrations/) instead. -- Dropping spans in the `beforeSendSpan` hook is no longer possible. This means you cannot return `null` from the `beforeSendSpan` hook anymore. - 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): + We recommend checking your `beforeSendSpan` to account for this change. - ```js - Sentry.init({ - tracesSampleRate: undefined, - }); - ``` +- The `request` property on the `samplingContext` argument passed to the `tracesSampler` and `profilesSampler` options has been removed. + `samplingContext.normalizedRequest` can be used instead. + Note that the type of `normalizedRequest` differs from `request`. - 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. +- The `startSpan` behavior was changed if you pass a custom `scope`: + 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, span hierarchy should be more accurate. + However, modifying the scope (e.g. set tags) within the `startSpan` callback behaves a bit differently now. ```js startSpan({ name: 'example', scope: customScope }, () => { @@ -93,17 +81,44 @@ Older Typescript versions _may_ still work, but we will not test them anymore an }); ``` -### `@sentry/node` +- Passing `undefined` as a `tracesSampleRate` option value will now be treated the same as if the attribute was not defined at all. + In previous versions, it was checked whether the `tracesSampleRate` property existed in the SDK options to determine whether to propagate trace data for distributed tracing. + Consequentially, this sometimes caused the SDK to propagate negative sampling decisions when `tracesSampleRate: undefined` was passed. + This is no longer the case and sampling decisions will be deferred to downstream SDKs for distributed tracing. + This is more of a bugfix rather than a breaking change, however, depending on the setup of your SDKs, an increase in sampled traces may be observed. -- When `skipOpenTelemetrySetup: true` is configured, `httpIntegration({ spans: false })` will be configured by default. +- 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, + }); + ``` + +### `@sentry/browser` / All SDKs running in the browser - 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 SDK no longer instructs the Sentry backend to automatically infer IP addresses by default. + Depending on the version of the Sentry backend (self-hosted), this may lead to IP addresses no longer showing up in Sentry, and events being grouped to "anonymous users". + At the time of writing, the Sentry SaaS solution will still continue to infer IP addresses, but this will change in the near future. + Set `sendDefaultPii: true` in `Sentry.init()` to instruct the Sentry backend to always infer IP addresses. -- 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. +### `@sentry/node` / All SDKs running in Node.js -- The `tracesSampler` hook will no longer be called for _every_ span. Instead, it will only be called for "root spans". Root spans are spans that have no local parent span. Root spans may however have incoming trace data from a different service, for example when using distributed tracing. +- The `tracesSampler` hook will no longer be called for _every_ span. + Root spans may however have incoming trace data from a different service, for example when using distributed tracing. -- The `childProcessIntegration`'s (previously `processThreadBreadcrumbIntegration`) `name` value has been changed from `"ProcessAndThreadBreadcrumbs"` to `"ChildProcess"`. This is relevant if you were filtering integrations by name. +- The `requestDataIntegration` will no longer automatically set the user from `request.user` when `express` is used. + Starting in v9, you'll need to manually call `Sentry.setUser()` e.g. in a middleware to set the user on Sentry events. + +- The `processThreadBreadcrumbIntegration` was renamed to `childProcessIntegration`. + +- The `childProcessIntegration`'s (previously `processThreadBreadcrumbIntegration`) `name` value has been changed from `"ProcessAndThreadBreadcrumbs"` to `"ChildProcess"`. + Any filtering logic for registered integrations should be updated to account for the changed name. + +- The `vercelAIIntegration`'s `name` value has been changed from `"vercelAI"` to `"VercelAI"` (capitalized). + Any filtering logic for registered integrations should be updated to account for the changed name. - The Prisma integration no longer supports Prisma v5 and supports Prisma v6 by default. As per Prisma v6, the `previewFeatures = ["tracing"]` client generator option in your Prisma Schema is no longer required to use tracing with the Prisma integration. @@ -135,56 +150,51 @@ Older Typescript versions _may_ still work, but we will not test them anymore an } ``` -### `@sentry/browser` +- When `skipOpenTelemetrySetup: true` is configured, `httpIntegration({ spans: false })` will be configured by default. + You no longer have to specify this manually. + With this change, no spans are emitted once `skipOpenTelemetrySetup: true` is configured, without any further configuration being needed. -- The SDK no longer instructs the Sentry backend to automatically infer IP addresses by default. This means that places where you previously saw IP addresses in Sentry may now be grouped to anonymous users. Set the `sendDefaultPii` option in `Sentry.init()` to true to instruct the Sentry backend to infer IP addresses. -- The `captureUserFeedback` method has been removed. Use the `captureFeedback` method instead and update the `comments` field to `message`. +### All Meta-Framework SDKs (`@sentry/nextjs`, `@sentry/nuxt`, `@sentry/sveltekit`, `@sentry/astro`, `@sentry/solidstart`) -### `@sentry/nextjs` +- SDKs no longer transform user-provided values for source map generation in build configurations (like Vite config, Rollup config, or `next.config.js`). -- The Sentry Next.js SDK will no longer use the Next.js Build ID as fallback identifier for releases. The SDK will continue to attempt to read CI-provider-specific environment variables and the current git SHA to automatically determine a release name. If you examine that you no longer see releases created in Sentry, it is recommended to manually provide a release name to `withSentryConfig` via the `release.name` option. + If source maps are explicitly disabled, the SDK will not enable them. If source maps are explicitly enabled, the SDK will not change how they are emitted. **However,** the SDK will also _not_ delete source maps after uploading them. If source map generation is not configured, the SDK will turn it on and delete them after the upload. - This behavior was changed because the Next.js Build ID is non-deterministic and the release name is injected into client bundles, causing build artifacts to be non-deterministic. This caused issues for some users. Additionally, because it is uncertain whether it will be possible to rely on a Build ID when Turbopack becomes stable, we decided to pull the plug now instead of introducing confusing behavior in the future. - -- Source maps are now automatically enabled for both client and server builds unless explicitly disabled via `sourcemaps.disable`. Client builds use `hidden-source-map` while server builds use `source-map` as their webpack `devtool` setting unless any other value than `false` or `undefined` has been assigned already. + To customize which files are deleted after upload, define the `filesToDeleteAfterUpload` array with globs. -- By default, source maps will now be automatically deleted after being uploaded to Sentry for client-side builds. You can opt out of this behavior by explicitly setting `sourcemaps.deleteSourcemapsAfterUpload` to `false` in your Sentry config. +### `@sentry/react` -- The `sentry` property on the Next.js config object has officially been discontinued. Pass options to `withSentryConfig` directly. +- The `componentStack` field in the `ErrorBoundary` component is now typed as `string` instead of `string | null | undefined` for the `onError` and `onReset` lifecycle methods. This more closely matches the actual behavior of React, which always returns a `string` whenever a component stack is available. -### All Meta-Framework SDKs (`@sentry/astro`, `@sentry/nextjs`, `@sentry/nuxt`, `@sentry/sveltekit`, `@sentry/solidstart`) + In the `onUnmount` lifecycle method, the `componentStack` field is now typed as `string | null`. The `componentStack` is `null` when no error has been thrown at time of unmount. -- Updated source map generation to respect the user-provided value of your build config, such as `vite.build.sourcemap`: +### `@sentry/nextjs` - - Explicitly disabled (false): Emit warning, no source map upload. - - Explicitly enabled (true, 'hidden', 'inline'): No changes, source maps are uploaded and not automatically deleted. - - Unset: Enable 'hidden', delete `.map` files after uploading them to Sentry. +- By default, client-side source maps will now be automatically deleted after being uploaded to Sentry during the build. + You can opt out of this behavior by explicitly setting `sourcemaps.deleteSourcemapsAfterUpload` to `false` in your Sentry config. - To customize which files are deleted after upload, define the `filesToDeleteAfterUpload` array with globs. +- The Sentry Next.js SDK will no longer use the Next.js Build ID as fallback identifier for releases. + The SDK will continue to attempt to read CI-provider-specific environment variables and the current git SHA to automatically determine a release name. + If you examine that you no longer see releases created in Sentry, it is recommended to manually provide a release name to `withSentryConfig` via the `release.name` option. -### `@sentry/react` + This behavior was changed because the Next.js Build ID is non-deterministic, causing build artifacts to be non-deterministic, because the release name is injected into client bundles. -The `componentStack` field in the `ErrorBoundary` component is now typed as `string` instead of `string | null | undefined` for the `onError` and `onReset` lifecycle methods. This more closely matches the actual behavior of React, which always returns a `string` whenever a component stack is available. +- Source maps are now automatically enabled for both client and server builds unless explicitly disabled via `sourcemaps.disable`. + Client builds use `hidden-source-map` while server builds use `source-map` as their webpack `devtool` setting unless any other value than `false` or `undefined` has been assigned already. -In the `onUnmount` lifecycle method, the `componentStack` field is now typed as `string | null`. The `componentStack` is `null` when no error has been thrown at time of unmount. +- The `sentry` property on the Next.js config object has officially been discontinued. + Pass options to `withSentryConfig` directly. ## 3. Package Removals -As part of an architectural cleanup, we deprecated the following packages: - -- `@sentry/utils` -- `@sentry/types` - -All of these packages exports and APIs have been moved into the `@sentry/core` package. - 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. -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. +The `@sentry/types` package will continue to be published, however, it is deprecated and its API will not be extended. +It will not be published as part of future major versions. + +All exports and APIs of `@sentry/utils` and `@sentry/types` (except for the ones that are explicitly called out in this migration guide to be removed) have been moved into the `@sentry/core` package. -## 4. Removal of Deprecated APIs +## 4. Removed APIs ### `@sentry/core` / All SDKs @@ -192,9 +202,44 @@ It will be removed in a future major version. The Sentry metrics beta has ended and the metrics API has been removed from the SDK. Learn more in the Sentry [help center docs](https://sentry.zendesk.com/hc/en-us/articles/26369339769883-Metrics-Beta-Ended-on-October-7th). -- The `debugIntegration` has been removed. To log outgoing events, use [Hook Options](https://docs.sentry.io/platforms/javascript/configuration/options/#hooks) (`beforeSend`, `beforeSendTransaction`, ...). +- The `transactionContext` property on the `samplingContext` argument passed to the `tracesSampler` and `profilesSampler` options has been removed. + All object attributes are available in the top-level of `samplingContext`: -- The `sessionTimingIntegration` has been removed. To capture session durations alongside events, use [Context](https://docs.sentry.io/platforms/javascript/enriching-events/context/) (`Sentry.setContext()`). + ```diff + Sentry.init({ + // Custom traces sampler + tracesSampler: samplingContext => { + - if (samplingContext.transactionContext.name === '/health-check') { + + if (samplingContext.name === '/health-check') { + return 0; + } else { + return 0.5; + } + }, + + // Custom profiles sampler + profilesSampler: samplingContext => { + - if (samplingContext.transactionContext.name === '/health-check') { + + if (samplingContext.name === '/health-check') { + return 0; + } else { + return 0.5; + } + }, + }) + ``` + +- The `enableTracing` option was removed. + Instead, set `tracesSampleRate: 1` or `tracesSampleRate: 0`. + +- The `autoSessionTracking` option was removed. + + To enable session tracking, ensure that either, in browser environments the `browserSessionIntegration` is added, or in server environments the `httpIntegration` is added. (both are added by default) + + To disable session tracking, remove the `browserSessionIntegration` in browser environments, or in server environments configure the `httpIntegration` with the `trackIncomingRequestsAsSessions` option set to `false`. + Additionally, in Node.js environments, a session was automatically created for every node process when `autoSessionTracking` was set to `true`. This behavior has been replaced by the `processSessionIntegration` which is configured by default. + +- The `getCurrentHub()`, `Hub` and `getCurrentHubShim()` APIs have been removed. They were on compatibility life support since the release of v8 and have now been fully removed from the SDK. - The `addOpenTelemetryInstrumentation` method has been removed. Use the `openTelemetryInstrumentations` option in `Sentry.init()` or your custom Sentry Client instead. @@ -210,30 +255,33 @@ It will be removed in a future major version. }); ``` -- The `DEFAULT_USER_INCLUDES` constant has been removed. +- The `debugIntegration` has been removed. To log outgoing events, use [Hook Options](https://docs.sentry.io/platforms/javascript/configuration/options/#hooks) (`beforeSend`, `beforeSendTransaction`, ...). + +- The `sessionTimingIntegration` has been removed. To capture session durations alongside events, use [Context](https://docs.sentry.io/platforms/javascript/enriching-events/context/) (`Sentry.setContext()`). -- The `getCurrentHub()`, `Hub` and `getCurrentHubShim()` APIs have been removed. They were on compatibility life support since the release of v8 and have now been fully removed from the SDK. +### Server-side SDKs (`@sentry/node` and all dependents) + +- The `addOpenTelemetryInstrumentation` method was removed. + Use the `openTelemetryInstrumentations` option in `Sentry.init()` or your custom Sentry Client instead. + +- `registerEsmLoaderHooks` now only accepts `true | false | undefined`. + The SDK will default to wrapping modules that are used as part of OpenTelemetry Instrumentation. + +- The `nestIntegration` was removed. + Use the NestJS SDK (`@sentry/nestjs`) instead. + +- The `setupNestErrorHandler` was removed. + Use the NestJS SDK (`@sentry/nestjs`) instead. ### `@sentry/browser` -- The `captureUserFeedback` method has been removed. Use the `captureFeedback` method 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/core` +### `@sentry/nextjs` -- The `getNumberOfUrlSegments` method has been removed. There is no replacement. -- 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 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. -- The `memoBuilder` method has been removed. There is no replacement. -- The `extractRequestData` method has been removed. Manually extract relevant data off request instead. -- The `addRequestDataToEvent` method has been removed. Use `httpRequestToRequestData` instead and put the resulting object directly on `event.request`. -- The `extractPathForTransaction` method has been removed. There is no replacement. -- The `addNormalizedRequestDataToEvent` method has been removed. Use `httpRequestToRequestData` instead and put the resulting object directly on `event.request`. -- A `sampleRand` field on `PropagationContext` is now required. This is relevant if you used `scope.setPropagationContext(...)` +- The `hideSourceMaps` option was removed without replacements. + The SDK emits hidden sourcemaps by default. ### `@sentry/solidstart` @@ -259,30 +307,38 @@ It will be removed in a future major version. ### `@sentry/nestjs` -- Removed `WithSentry` decorator. Use the `SentryExceptionCaptured` decorator instead. +- Removed `@WithSentry` decorator. + Use the `@SentryExceptionCaptured` decorator as a drop-in replacement. + - 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` 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` afterward. + - Removed `SentryGlobalGenericFilter`. - - Use the `SentryGlobalFilter` instead. - - The `SentryGlobalFilter` is a drop-in replacement. + Use the `SentryGlobalFilter` as a drop-in replacement. + - Removed `SentryGlobalGraphQLFilter`. - - Use the `SentryGlobalFilter` instead. - - The `SentryGlobalFilter` is a drop-in replacement. + Use the `SentryGlobalFilter` as 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. +- The `wrapUseRoutes` method has been removed. + Depending on what version of react router you are using, use the `wrapUseRoutesV6` or `wrapUseRoutesV7` methods instead. + +- The `wrapCreateBrowserRouter` method has been removed. + Depending on what version of react router you are using, use the `wrapCreateBrowserRouterV6` or `wrapCreateBrowserRouterV7` methods instead. ### `@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: + These options should now be configured as follows: ```js import * as Sentry from '@sentry/vue'; @@ -300,261 +356,147 @@ It will be removed in a future major version. }); ``` -- The option `logErrors` in the `vueIntegration` has been removed. 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). - -### `@sentry/opentelemetry` - -- Removed `getPropagationContextFromSpan`. - This function was primarily internally used. - It's functionality was misleading and should not be used. - -### `@sentry/sveltekit` - -- The `fetchProxyScriptNonce` option in `sentryHandle()` was removed due to security concerns. If you previously specified this option for your CSP policy, specify a [script hash](https://docs.sentry.io/platforms/javascript/guides/sveltekit/manual-setup/#configure-csp-for-client-side-fetch-instrumentation) in your CSP config or [disable](https://docs.sentry.io/platforms/javascript/guides/sveltekit/manual-setup/#disable-client-side-fetch-proxy-script) the injection of the script entirely. - -#### Other/Internal Changes - -The following changes are unlikely to affect users of the SDK. They are listed here only for completion sake, and to alert users that may be relying on internal behavior. - -- `client._prepareEvent()` now requires a currentScope & isolationScope to be passed as last arugments -- `client.recordDroppedEvent()` no longer accepts an `event` as third argument. The event was no longer used for some time, instead you can (optionally) pass a count of dropped events as third argument. - -## 5. Build Changes - -Previously the CJS versions of the SDK code (wrongfully) contained compatibility statements for default exports in ESM: +- The option `logErrors` in the `vueIntegration` has been removed. The Sentry Vue error handler will always propagate the error to a user-defined error handler or re-throw the error (which will log the error without modifying). -```js -Object.defineProperty(exports, '__esModule', { value: true }); -``` +### `@sentry/nuxt` -The SDK no longer contains these statements. -Let us know if this is causing issues in your setup by opening an issue on GitHub. +- The `tracingOptions` option in `Sentry.init()` was removed in favor of passing the `vueIntegration()` to `Sentry.init({ integrations: [...] })` and setting `tracingOptions` there. -### `@sentry/deno` +### `@sentry/vue` and `@sentry/nuxt` -- The minimum supported Deno version for the Deno SDK (`@sentry/deno`) is now **2.0.0**. - -- `@sentry/deno` is no longer published on the `deno.land` registry so you'll need to import the SDK from npm: +- When component tracking is enabled, "update" spans are no longer created by default. - ```javascript - import * as Sentry from 'npm:@sentry/deno'; + Add an `"update"` item to the `tracingOptions.hooks` option via the `vueIntegration()` to restore this behavior. + ```ts Sentry.init({ - dsn: '__DSN__', - // ... + integrations: [ + Sentry.vueIntegration({ + tracingOptions: { + trackComponents: true, + hooks: [ + 'mount', + 'update', // add this line to re-enable update spans + 'unmount', + ], + }, + }), + ], }); ``` -## 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: - -- `Scope` now always expects the `Scope` class -- The `TransactionNamingScheme` type has been removed. There is no replacement. -- The `Request` type has been removed. Use `RequestEventData` type instead. -- The `IntegrationClass` type is no longer exported - it was not used anymore. Instead, use `Integration` or `IntegrationFn`. -- The `samplingContext.request` attribute in the `tracesSampler` has been removed. Use `samplingContext.normalizedRequest` instead. Note that the type of `normalizedRequest` differs from `request`. -- The `samplingContext.transactionContext` object in the `tracesSampler` and `profilesSampler` has been removed. All object attributes are available in the top-level of `samplingContext`. -- `Client` now always expects the `BaseClient` class - there is no more abstract `Client` that can be implemented! Any `Client` class has to extend from `BaseClient`. -- `ReportDialogOptions` now extends `Record` instead of `Record` - this should not affect most users. -- The `RequestDataIntegrationOptions` type has been removed. There is no replacement. - -# No Version Support Timeline +### `@sentry/remix` -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. +- The `autoInstrumentRemix` option was removed. + The SDK now always behaves as if the option were set to `true`. -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. -If you need a fix or feature in a previous version of the SDK, feel free to reach out via a GitHub issue. - -# Deprecations in 8.x - -The following outlines deprecations that were introduced in version 8 of the SDK. - -## General - -- **Returning `null` from `beforeSendSpan` span is deprecated.** - - Returning `null` from `beforeSendSpan` will now result in a warning being logged. - In v9, dropping spans is not possible anymore within this hook. - -- **Passing `undefined` to `tracesSampleRate` / `tracesSampler` / `enableTracing` will be handled differently in v9** - - In v8, explicitly setting `tracesSampleRate` (even if it is set to `undefined`) resulted in tracing being _enabled_, although no spans were generated. - - ```ts - Sentry.init({ - tracesSampleRate: undefined, - }); - ``` - - 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. +### `@sentry/sveltekit` - 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 `fetchProxyScriptNonce` option in `sentryHandle()` was removed due to security concerns. If you previously specified this option for your CSP policy, specify a [script hash](https://docs.sentry.io/platforms/javascript/guides/sveltekit/manual-setup/#configure-csp-for-client-side-fetch-instrumentation) in your CSP config or [disable](https://docs.sentry.io/platforms/javascript/guides/sveltekit/manual-setup/#disable-client-side-fetch-proxy-script) the injection of the script entirely. - The `enableTracing` option was removed. In v9, to emulate `enableTracing: true`, set `tracesSampleRate: 1`. To emulate `enableTracing: false`, remove the `tracesSampleRate` and `tracesSampler` options (if configured). +### `@sentry/core` -- **The `autoSessionTracking` option is deprecated.** +- A `sampleRand` field on `PropagationContext` is now required. This is relevant if you used `scope.setPropagationContext(...)` - 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. +- The `DEFAULT_USER_INCLUDES` constant has been removed. There is no replacement. - 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`. - Additionally, in Node.js environments, a session was automatically created for every node process when `autoSessionTracking` was set to `true`. This behavior has been replaced by the `processSessionIntegration` which is configured by default. +- The `BAGGAGE_HEADER_NAME` export has been removed. Use a `"baggage"` string constant directly instead. -- **The metrics API is deprecated.** +- The `extractRequestData` method has been removed. Manually extract relevant data of request objects instead. - The Sentry metrics beta has ended and the metrics API has been deprecated in `8.x`. The entire API will be removed in `9.x` of the SDK. Learn more in the Sentry [help center docs](https://sentry.zendesk.com/hc/en-us/articles/26369339769883-Metrics-Beta-Ended-on-October-7th). +- The `addRequestDataToEvent` method has been removed. Use `httpRequestToRequestData` instead and put the resulting object directly on `event.request`. -## `@sentry/utils` +- The `addNormalizedRequestDataToEvent` method has been removed. Use `httpRequestToRequestData` instead and put the resulting object directly on `event.request`. -- **The `@sentry/utils` package has been deprecated. Import everything from `@sentry/core` instead.** +- The `generatePropagationContext()` method was removed. + Use `generateTraceId()` directly. - - 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. - - Deprecated `addRequestDataToEvent`. Use `httpRequestToRequestData` instead and put the resulting object directly on `event.request`. - - Deprecated `extractRequestData`. Instead manually extract relevant data off request. - - Deprecated `arrayify`. No replacements. - - Deprecated `memoBuilder`. No replacements. - - Deprecated `getNumberOfUrlSegments`. No replacements. - - Deprecated `BAGGAGE_HEADER_NAME`. Use the `"baggage"` string constant directly instead. - - Deprecated `makeFifoCache`. No replacements. - - Deprecated `dynamicRequire`. No replacements. - - Deprecated `flatten`. No replacements. - - Deprecated `_browserPerformanceTimeOriginMode`. No replacements. +- The `spanId` field on `propagationContext` was removed. + It was replaced with an **optional** field `propagationSpanId` having the same semantics but only being defined when a unit of execution should be associated with a particular span ID. -## `@sentry/core` +- The `initSessionFlusher` method on the `ServerRuntimeClient` was removed without replacements. + Any mechanisms creating sessions will flush themselves. -- Deprecated `transactionNamingScheme` option in `requestDataIntegration`. -- Deprecated `debugIntegration`. To log outgoing events, use [Hook Options](https://docs.sentry.io/platforms/javascript/configuration/options/#hooks) (`beforeSend`, `beforeSendTransaction`, ...). -- Deprecated `sessionTimingIntegration`. To capture session durations alongside events, use [Context](https://docs.sentry.io/platforms/javascript/enriching-events/context/) (`Sentry.setContext()`). -- Deprecated `addTracingHeadersToFetchRequest` method - this was only meant for internal use and is not needed anymore. -- Deprecated `generatePropagationContext()` in favor of using `generateTraceId()` directly. -- Deprecated `spanId` field on `propagationContext` - this field will be removed in v9, and should neither be read or set anymore. -- Deprecated `RequestSession` type. No replacements. -- Deprecated `RequestSessionStatus` type. No replacements. -- Deprecated `SessionFlusherLike` type. No replacements. -- Deprecated `SessionFlusher`. No replacements. -- Deprecated `initSessionFlusher` on `ServerRuntimeClient`. No replacements. The `httpIntegration` will flush sessions by itself. +- The `IntegrationClass` type was removed. + Instead, use `Integration` or `IntegrationFn`. -## `@sentry/nestjs` +- The following exports have been removed without replacement: -- 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` 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` afterward. -- Deprecated `SentryGlobalGenericFilter`. - Use the `SentryGlobalFilter` instead. - The `SentryGlobalFilter` is a drop-in replacement. -- Deprecated `SentryGlobalGraphQLFilter`. - Use the `SentryGlobalFilter` instead. - The `SentryGlobalFilter` is a drop-in replacement. + - `getNumberOfUrlSegments` + - `validSeverityLevels` + - `makeFifoCache` + - `arrayify` + - `flatten` + - `urlEncode` + - `getDomElement` + - `memoBuilder` + - `extractPathForTransaction` + - `_browserPerformanceTimeOriginMode` + - `addTracingHeadersToFetchRequest` + - `SessionFlusher` -## `@sentry/types` +- The following types have been removed without replacement: -- **The `@sentry/types` package has been deprecated. Import everything from `@sentry/core` instead.** + - `Request` + `RequestEventData` + - `TransactionNamingScheme` + - `RequestDataIntegrationOptions` + - `SessionFlusherLike` + - `RequestSession` + - `RequestSessionStatus` - - Deprecated `Request` in favor of `RequestEventData`. - - Deprecated `RequestSession`. No replacements. - - Deprecated `RequestSessionStatus`. No replacements. - - Deprecated `SessionFlusherLike`. No replacements. +### `@sentry/opentelemetry` -## `@sentry/nuxt` +- Removed `getPropagationContextFromSpan` without replacement. +- Removed `generateSpanContextForPropagationContext` without replacement. -- Deprecated `tracingOptions` in `Sentry.init()` in favor of passing the `vueIntegration()` to `Sentry.init({ integrations: [...] })` and setting `tracingOptions` there. +#### Other/Internal Changes -## `@sentry/vue` +The following changes are unlikely to affect users of the SDK. They are listed here only for completion sake, and to alert users that may be relying on internal behavior. -- Deprecated `tracingOptions`, `trackComponents`, `timeout`, `hooks` options everywhere other than in the `tracingOptions` option of the `vueIntegration()`. +- `client._prepareEvent()` now requires both `currentScope` and `isolationScope` to be passed as arguments. +- `client.recordDroppedEvent()` no longer accepts an `event` as third argument. + The event was no longer used for some time, instead you can (optionally) pass a count of dropped events as third argument. - These options should now be set as follows: +## 5. Build Changes - ```ts - import * as Sentry from '@sentry/vue'; +- The CJS code for the SDK now only contains compatibility statements for CJS/ESM in modules that have default exports: - Sentry.init({ - integrations: [ - Sentry.vueIntegration({ - tracingOptions: { - trackComponents: true, - timeout: 1000, - hooks: ['mount', 'update', 'unmount'], - }, - }), - ], - }); + ```js + Object.defineProperty(exports, '__esModule', { value: true }); ``` -- 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). - -## `@sentry/nuxt` and `@sentry/vue` + Let us know if this is causing issues in your setup by opening an issue on GitHub. -- When component tracking is enabled, "update" spans are no longer created by default. +- `@sentry/deno` is no longer published on the `deno.land` registry so you'll need to import the SDK from npm: - Add an `"update"` item to the `tracingOptions.hooks` option via the `vueIntegration()` to restore this behavior. + ```javascript + import * as Sentry from 'npm:@sentry/deno'; - ```ts Sentry.init({ - integrations: [ - Sentry.vueIntegration({ - tracingOptions: { - trackComponents: true, - hooks: [ - 'mount', - 'update', // add this line to re-enable update spans - 'unmount', - ], - }, - }), - ], + dsn: '__DSN__', + // ... }); ``` -## `@sentry/astro` - -- Deprecated passing `dsn`, `release`, `environment`, `sampleRate`, `tracesSampleRate`, `replaysSessionSampleRate` to the integration. Use the runtime-specific `Sentry.init()` calls for passing these options instead. - -## `@sentry/remix` - -- Deprecated `autoInstrumentRemix: false`. The next major version will default to behaving as if this option were `true` and the option itself will be removed. - -## `@sentry/react` - -- Deprecated `wrapUseRoutes`. Use the `wrapUseRoutesV6` or `wrapUseRoutesV7` methods instead. -- Deprecated `wrapCreateBrowserRouter`. Use the `wrapCreateBrowserRouterV6` or `wrapCreateBrowserRouterV7` methods instead. +## 6. Type Changes -## `@sentry/nextjs` +- `Scope` usages now always expect `Scope` instances -- Deprecated the `hideSourceMaps` option. There are no replacements for this option. The SDK emits hidden sourcemaps by default. +- `Client` usages now always expect `BaseClient` instances. + The abstract `Client` class was removed. + Client classes now have to extend from `BaseClient`. -### `@sentry/sveltekit` +These changes should not affect most users unless you relied on passing things with a similar shape to internal methods. -- The `fetchProxyScriptNonce` option in `sentryHandle()` was deprecated due to security concerns. If you previously specified this option for your CSP policy, specify a [script hash](https://docs.sentry.io/platforms/javascript/guides/sveltekit/manual-setup/#configure-csp-for-client-side-fetch-instrumentation) in your CSP config or [disable](https://docs.sentry.io/platforms/javascript/guides/sveltekit/manual-setup/#disable-client-side-fetch-proxy-script) the injection of the script entirely. +In v8, interfaces have been exported from `@sentry/types`, while implementations have been exported from other packages. -## `@sentry/opentelemetry` +## No Version Support Timeline -- Deprecated the `generateSpanContextForPropagationContext` method. There are no replacements for this method. +Version support timelines are stressful for everybody 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. -## Server-side SDKs (`@sentry/node` and all dependents) +Additionally, we hold ourselves accountable to any security issues, meaning that if any vulnerabilities are found, we will in almost all cases backport them. -- Deprecated `processThreadBreadcrumbIntegration` in favor of `childProcessIntegration`. Functionally they are the same. -- Deprecated `nestIntegration`. Use the NestJS SDK (`@sentry/nestjs`) instead. -- Deprecated `setupNestErrorHandler`. Use the NestJS SDK (`@sentry/nestjs`) instead. -- Deprecated `addOpenTelemetryInstrumentation`. Use the `openTelemetryInstrumentations` option in `Sentry.init()` or your custom Sentry Client instead. -- Deprecated `registerEsmLoaderHooks.include` and `registerEsmLoaderHooks.exclude`. Set `onlyIncludeInstrumentedModules: true` instead. -- `registerEsmLoaderHooks` will only accept `true | false | undefined` in the future. The SDK will default to wrapping modules that are used as part of OpenTelemetry Instrumentation. -- `httpIntegration({ spans: false })` is configured by default if `skipOpenTelemetrySetup: true` is set. You can still overwrite this if desired. +Note, that it is decided on a case-per-case basis, what gets backported or not. +If you need a fix or feature in a previous version of the SDK, please reach out via a GitHub Issue.