From 4cdadc4c88d3915c59e23fde14d4cd493da59d9e Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Tue, 4 Feb 2025 14:23:58 +0000 Subject: [PATCH 01/13] Give a pass --- docs/migration/v8-to-v9.md | 493 ++++++++++++++++--------------------- 1 file changed, 209 insertions(+), 284 deletions(-) diff --git a/docs/migration/v8-to-v9.md b/docs/migration/v8-to-v9.md index 487dbee7cf4c..6cefe3b09c44 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 last major). 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,55 @@ 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: +- Passing `undefined` as a `tracesSampleRate` option value will now be treated the same as if the option was not defined at all. + In previous versions, it was checked whether `tracesSampleRate` or `traceSampler` are _defined_ at all, in `Sentry.init()` to determine whether tracing should be enabled. + Passing `undefined` to `tracesSampleRate` previously would enable tracing without the performance monitoring aspect (=tracing being enabled, though no spans would be started). + If you want to preserve having tracing enabled without creating spans, set `tracesSampleRate: 0`: - ```js + ```diff Sentry.init({ - integrations: [Sentry.captureConsoleIntegration({ handled: false })], - attachStackTrace: true, + - tracesSampleRate: undefined, + + tracesSampleRate: 0, }); ``` -- Dropping spans in the `beforeSendSpan` hook is no longer possible. This means you cannot return `null` from the `beforeSendSpan` hook anymore. +- 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. + - 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. + +- 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({ - tracesSampleRate: undefined, + integrations: [Sentry.captureConsoleIntegration({ handled: false })], + attachStackTrace: true, }); ``` - 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 `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`. -- 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 }, () => { @@ -95,15 +105,16 @@ Older Typescript versions _may_ still work, but we will not test them anymore an ### `@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. +- 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 `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. +- 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 `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 `processThreadBreadcrumbIntegration` was renamed to `childProcessIntegration`. -- 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 `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 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 +146,59 @@ Older Typescript versions _may_ still work, but we will not test them anymore an } ``` +- 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. + ### `@sentry/browser` -- 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`. +- 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`. ### `@sentry/nextjs` -- 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. +- 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. - 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. +- 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. -- 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. + 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. -- 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. +- 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. -- The `sentry` property on the Next.js config object has officially been discontinued. Pass options to `withSentryConfig` directly. +- The `sentry` property on the Next.js config object has officially been discontinued. + Pass options to `withSentryConfig` directly. ### All Meta-Framework SDKs (`@sentry/astro`, `@sentry/nextjs`, `@sentry/nuxt`, `@sentry/sveltekit`, `@sentry/solidstart`) -- Updated source map generation to respect the user-provided value of your build config, such as `vite.build.sourcemap`: +- SDKs no longer transform user-provided values for source map generation in build configurations (like Vite config, Rollup config, or `next.config.js`). - - 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. + 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. To customize which files are deleted after upload, define the `filesToDeleteAfterUpload` array with globs. ### `@sentry/react` -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. +- 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. -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. + 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. ## 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 +206,18 @@ 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 `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). -- 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 `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 +233,34 @@ It will be removed in a future major version. }); ``` -- The `DEFAULT_USER_INCLUDES` constant has been removed. +- 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 `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 `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()`). + +### 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`. -### `@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 +286,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 +335,151 @@ 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: - -```js -Object.defineProperty(exports, '__esModule', { value: true }); -``` +- 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). -The SDK no longer contains these statements. -Let us know if this is causing issues in your setup by opening an issue on GitHub. +### `@sentry/nuxt` -### `@sentry/deno` +- The `tracingOptions` option in `Sentry.init()` was removed in favor of passing the `vueIntegration()` to `Sentry.init({ integrations: [...] })` and setting `tracingOptions` there. -- The minimum supported Deno version for the Deno SDK (`@sentry/deno`) is now **2.0.0**. +### `@sentry/vue` and `@sentry/nuxt` -- `@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 - -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. -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** +### `@sentry/remix` - In v8, explicitly setting `tracesSampleRate` (even if it is set to `undefined`) resulted in tracing being _enabled_, although no spans were generated. +- The `autoInstrumentRemix` option was removed. + The SDK now behaves as if the option were set to `true` as the only and default behavior. - ```ts - Sentry.init({ - tracesSampleRate: undefined, - }); - ``` +### `@sentry/sveltekit` - 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. +- 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. - 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. +### `@sentry/core` - 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). +- A `sampleRand` field on `PropagationContext` is now required. This is relevant if you used `scope.setPropagationContext(...)` -- **The `autoSessionTracking` option is deprecated.** +- The `DEFAULT_USER_INCLUDES` constant has been removed. There is no replacement. - 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 `BAGGAGE_HEADER_NAME` export has been removed. Use a `"baggage"` string constant directly instead. - 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 `extractRequestData` method has been removed. Manually extract relevant data of request objects instead. -- **The metrics API is deprecated.** +- The `addRequestDataToEvent` method has been removed. Use `httpRequestToRequestData` instead and put the resulting object directly on `event.request`. - 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 `addNormalizedRequestDataToEvent` method has been removed. Use `httpRequestToRequestData` instead and put the resulting object directly on `event.request`. -## `@sentry/utils` +- The `generatePropagationContext()` method was removed. + Use `generateTraceId()` directly. -- **The `@sentry/utils` package has been deprecated. Import everything from `@sentry/core` instead.** +- 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. - - 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 `initSessionFlusher` method on the `ServerRuntimeClient` was removed without replacements. + Any mechanisms creating sessions will flush themselves. -## `@sentry/core` +- The `IntegrationClass` type was removed. + Instead, use `Integration` or `IntegrationFn`. -- 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 following exports have been removed without replacement: -## `@sentry/nestjs` + - `getNumberOfUrlSegments` + - `validSeverityLevels` + - `makeFifoCache` + - `arrayify` + - `flatten` + - `urlEncode` + - `getDomElement` + - `memoBuilder` + - `extractPathForTransaction` + - `_browserPerformanceTimeOriginMode` + - `addTracingHeadersToFetchRequest` + - `SessionFlusher` -- 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. +- The following types have been removed without replacement: -## `@sentry/types` + - `Request` + `RequestEventData` + - `TransactionNamingScheme` + - `RequestDataIntegrationOptions` + - `SessionFlusherLike` + - `RequestSession` + - `RequestSessionStatus` -- **The `@sentry/types` package has been deprecated. Import everything from `@sentry/core` instead.** +### `@sentry/opentelemetry` - - Deprecated `Request` in favor of `RequestEventData`. - - Deprecated `RequestSession`. No replacements. - - Deprecated `RequestSessionStatus`. No replacements. - - Deprecated `SessionFlusherLike`. No replacements. +- Removed `getPropagationContextFromSpan` without replacement. +- Removed `generateSpanContextForPropagationContext` without replacement. -## `@sentry/nuxt` +#### Other/Internal Changes -- Deprecated `tracingOptions` in `Sentry.init()` in favor of passing the `vueIntegration()` to `Sentry.init({ integrations: [...] })` and setting `tracingOptions` there. +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. -## `@sentry/vue` +- `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. -- Deprecated `tracingOptions`, `trackComponents`, `timeout`, `hooks` options everywhere other than in the `tracingOptions` option of the `vueIntegration()`. +## 5. Build Changes - These options should now be set as follows: +The CJS code for the SDK now only contains compatibility statements for CJS/ESM in modules that have default exports: - ```ts - import * as Sentry from '@sentry/vue'; +```js +Object.defineProperty(exports, '__esModule', { value: true }); +``` - Sentry.init({ - integrations: [ - Sentry.vueIntegration({ - tracingOptions: { - trackComponents: true, - timeout: 1000, - hooks: ['mount', 'update', 'unmount'], - }, - }), - ], - }); - ``` +Let us know if this is causing issues in your setup by opening an issue on GitHub. -- 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/deno` -## `@sentry/nuxt` and `@sentry/vue` +- The minimum supported Deno version for the Deno SDK (`@sentry/deno`) is now **2.0.0**. -- 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` +## 6. Type Changes -- Deprecated `wrapUseRoutes`. Use the `wrapUseRoutesV6` or `wrapUseRoutesV7` methods instead. -- Deprecated `wrapCreateBrowserRouter`. Use the `wrapCreateBrowserRouterV6` or `wrapCreateBrowserRouterV7` methods instead. +- `Scope` usages now always expect `Scope` instances -## `@sentry/nextjs` +- `Client` usages now always expect `BaseClient` instances. + The abstract `Client` class was removed. + Client classes now have to extend from `BaseClient`. -- Deprecated the `hideSourceMaps` option. There are no replacements for this option. The SDK emits hidden sourcemaps by default. +These changes should not affect most users unless you relied on passing things with a similar shape to internal methods. -### `@sentry/sveltekit` +In v8, interfaces have been exported from `@sentry/types`, while implementations have been exported from other packages. -- 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. - -## `@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. From fe2e0abbd9c67e59adc1f09eb6d6c9be3ab73036 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Tue, 4 Feb 2025 14:28:29 +0000 Subject: [PATCH 02/13] minor yeet --- docs/migration/v8-to-v9.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/docs/migration/v8-to-v9.md b/docs/migration/v8-to-v9.md index 6cefe3b09c44..66cbb6763193 100644 --- a/docs/migration/v8-to-v9.md +++ b/docs/migration/v8-to-v9.md @@ -439,17 +439,13 @@ The following changes are unlikely to affect users of the SDK. They are listed h ## 5. Build Changes -The CJS code for the SDK now only contains compatibility statements for CJS/ESM in modules that have default exports: +- The CJS code for the SDK now only contains compatibility statements for CJS/ESM in modules that have default exports: -```js -Object.defineProperty(exports, '__esModule', { value: true }); -``` - -Let us know if this is causing issues in your setup by opening an issue on GitHub. - -### `@sentry/deno` + ```js + Object.defineProperty(exports, '__esModule', { value: true }); + ``` -- The minimum supported Deno version for the Deno SDK (`@sentry/deno`) is now **2.0.0**. + Let us know if this is causing issues in your setup by opening an issue on GitHub. - `@sentry/deno` is no longer published on the `deno.land` registry so you'll need to import the SDK from npm: From cddb7b62888aa2f3baddd2843474698109005ccd Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 5 Feb 2025 10:17:53 +0100 Subject: [PATCH 03/13] Apply suggestions from code review Co-authored-by: Francesco Gringl-Novy --- docs/migration/v8-to-v9.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/migration/v8-to-v9.md b/docs/migration/v8-to-v9.md index 66cbb6763193..57cb2ce11497 100644 --- a/docs/migration/v8-to-v9.md +++ b/docs/migration/v8-to-v9.md @@ -3,7 +3,7 @@ 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. -`v9` of the 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: @@ -29,7 +29,7 @@ If your runtime does not support ES2020, we recommend transpiling the SDK using - Opera 67 - Samsung Internet 13.0 -If you need to support older browsers, we recommend transpiling your code using, SWC, 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**. @@ -156,7 +156,7 @@ Older Typescript versions _may_ continue to be compatible, but no guarantees app 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`. + Use the `captureFeedback` method instead and set the `message` property instead of `comments`. ### `@sentry/nextjs` @@ -207,8 +207,7 @@ All exports and APIs of `@sentry/utils` and `@sentry/types` (except for the ones 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 `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). + Instead, set `tracesSampleRate: 1` or `tracesSampleRate: 0`. - The `autoSessionTracking` option was removed. @@ -367,7 +366,7 @@ All exports and APIs of `@sentry/utils` and `@sentry/types` (except for the ones ### `@sentry/remix` - The `autoInstrumentRemix` option was removed. - The SDK now behaves as if the option were set to `true` as the only and default behavior. + The SDK now always behaves as if the option were set to `true`. ### `@sentry/sveltekit` From b40c1edce5c39511528387283774aa8a997ff88f Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 5 Feb 2025 09:28:33 +0000 Subject: [PATCH 04/13] Dedupe section --- docs/migration/v8-to-v9.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/migration/v8-to-v9.md b/docs/migration/v8-to-v9.md index 57cb2ce11497..1f61e1437c8d 100644 --- a/docs/migration/v8-to-v9.md +++ b/docs/migration/v8-to-v9.md @@ -155,8 +155,6 @@ Older Typescript versions _may_ continue to be compatible, but no guarantees app - 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 set the `message` property instead of `comments`. ### `@sentry/nextjs` From ff392584db149869078a49a0c606e86a26138e4d Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 5 Feb 2025 09:29:36 +0000 Subject: [PATCH 05/13] Promote important section and add code example --- docs/migration/v8-to-v9.md | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/docs/migration/v8-to-v9.md b/docs/migration/v8-to-v9.md index 1f61e1437c8d..e5ee4b95e795 100644 --- a/docs/migration/v8-to-v9.md +++ b/docs/migration/v8-to-v9.md @@ -204,6 +204,33 @@ All exports and APIs of `@sentry/utils` and `@sentry/types` (except for the ones 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 `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`: + + ```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`. @@ -230,8 +257,6 @@ All exports and APIs of `@sentry/utils` and `@sentry/types` (except for the ones }); ``` -- 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 `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()`). From bb2d64b56ec4a85428f26c2c40082a7c47a4247a Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 5 Feb 2025 09:29:55 +0000 Subject: [PATCH 06/13] Minor formatting --- docs/migration/v8-to-v9.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/migration/v8-to-v9.md b/docs/migration/v8-to-v9.md index e5ee4b95e795..871415d26b2e 100644 --- a/docs/migration/v8-to-v9.md +++ b/docs/migration/v8-to-v9.md @@ -277,7 +277,8 @@ All exports and APIs of `@sentry/utils` and `@sentry/types` (except for the ones ### `@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/nextjs` From 5c4621131d914dbf9cc2e3d73bbb7e9e348544d3 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 5 Feb 2025 09:37:37 +0000 Subject: [PATCH 07/13] Rephrase ip address collecting --- docs/migration/v8-to-v9.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/migration/v8-to-v9.md b/docs/migration/v8-to-v9.md index 871415d26b2e..905c1046014c 100644 --- a/docs/migration/v8-to-v9.md +++ b/docs/migration/v8-to-v9.md @@ -103,7 +103,14 @@ Older Typescript versions _may_ continue to be compatible, but no guarantees app }); ``` -### `@sentry/node` +### `@sentry/browser` / All SDKs running in the browser + +- 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 the `sendDefaultPii` option in `Sentry.init()` to true to instruct the Sentry backend to infer IP addresses. + +### `@sentry/node` / All SDKs running in Node.js - 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. @@ -150,12 +157,6 @@ Older Typescript versions _may_ continue to be compatible, but no guarantees app 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. -### `@sentry/browser` - -- 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. - ### `@sentry/nextjs` - By default, client-side source maps will now be automatically deleted after being uploaded to Sentry during the build. From 573cfbd9b3ffdbd73175e760d53d70eb1641bdbc Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 5 Feb 2025 09:37:42 +0000 Subject: [PATCH 08/13] move section --- docs/migration/v8-to-v9.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/migration/v8-to-v9.md b/docs/migration/v8-to-v9.md index 905c1046014c..cd7901c1b17e 100644 --- a/docs/migration/v8-to-v9.md +++ b/docs/migration/v8-to-v9.md @@ -157,6 +157,20 @@ Older Typescript versions _may_ continue to be compatible, but no guarantees app 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. +### All Meta-Framework SDKs (`@sentry/nextjs`, `@sentry/nuxt`, `@sentry/sveltekit`, `@sentry/astro`, `@sentry/solidstart`) + +- SDKs no longer transform user-provided values for source map generation in build configurations (like Vite config, Rollup config, or `next.config.js`). + + 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. + + To customize which files are deleted after upload, define the `filesToDeleteAfterUpload` array with globs. + +### `@sentry/react` + +- 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. + + 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. + ### `@sentry/nextjs` - By default, client-side source maps will now be automatically deleted after being uploaded to Sentry during the build. @@ -174,20 +188,6 @@ Older Typescript versions _may_ continue to be compatible, but no guarantees app - The `sentry` property on the Next.js config object has officially been discontinued. Pass options to `withSentryConfig` directly. -### All Meta-Framework SDKs (`@sentry/astro`, `@sentry/nextjs`, `@sentry/nuxt`, `@sentry/sveltekit`, `@sentry/solidstart`) - -- SDKs no longer transform user-provided values for source map generation in build configurations (like Vite config, Rollup config, or `next.config.js`). - - 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. - - To customize which files are deleted after upload, define the `filesToDeleteAfterUpload` array with globs. - -### `@sentry/react` - -- 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. - - 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. - ## 3. Package Removals The `@sentry/utils` package will no longer be published. From 1a75c97add924e2433244bd7200acd82f6580afb Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 5 Feb 2025 09:39:06 +0000 Subject: [PATCH 09/13] Move capture console section --- docs/migration/v8-to-v9.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/migration/v8-to-v9.md b/docs/migration/v8-to-v9.md index cd7901c1b17e..5a7c18a32ebb 100644 --- a/docs/migration/v8-to-v9.md +++ b/docs/migration/v8-to-v9.md @@ -75,16 +75,6 @@ Older Typescript versions _may_ continue to be compatible, but no guarantees app - The `beforeSendSpan` hook now receives the root span as well as the child spans. We recommend checking your `beforeSendSpan` to account for this change. -- 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, - }); - ``` - - 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`. @@ -103,6 +93,16 @@ Older Typescript versions _may_ continue to be compatible, but no guarantees app }); ``` +- 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 - The SDK no longer instructs the Sentry backend to automatically infer IP addresses by default. From b8c7ca2811b19e66938d6a054ee9a83143fd8b49 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 5 Feb 2025 09:41:18 +0000 Subject: [PATCH 10/13] minor rewording --- docs/migration/v8-to-v9.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration/v8-to-v9.md b/docs/migration/v8-to-v9.md index 5a7c18a32ebb..5692dc94b260 100644 --- a/docs/migration/v8-to-v9.md +++ b/docs/migration/v8-to-v9.md @@ -108,7 +108,7 @@ Older Typescript versions _may_ continue to be compatible, but no guarantees app - 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 the `sendDefaultPii` option in `Sentry.init()` to true to instruct the Sentry backend to infer IP addresses. + Set `sendDefaultPii: true` in `Sentry.init()` to instruct the Sentry backend to always infer IP addresses. ### `@sentry/node` / All SDKs running in Node.js From a2ca66c98b0b2f430e40c718ad750239a0ec62e8 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 5 Feb 2025 09:42:58 +0000 Subject: [PATCH 11/13] Add vercel AI change --- docs/migration/v8-to-v9.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/migration/v8-to-v9.md b/docs/migration/v8-to-v9.md index 5692dc94b260..4e27e5973c5c 100644 --- a/docs/migration/v8-to-v9.md +++ b/docs/migration/v8-to-v9.md @@ -123,6 +123,9 @@ Older Typescript versions _may_ continue to be compatible, but no guarantees app - 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. For performance instrumentation using other/older Prisma versions: From ceb88b0f4593a0c93669c5c5c342fca55fd55b24 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 5 Feb 2025 10:07:48 +0000 Subject: [PATCH 12/13] Rephrase the tracesSampleRate situation --- docs/migration/v8-to-v9.md | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/docs/migration/v8-to-v9.md b/docs/migration/v8-to-v9.md index 4e27e5973c5c..af86512ee675 100644 --- a/docs/migration/v8-to-v9.md +++ b/docs/migration/v8-to-v9.md @@ -55,18 +55,6 @@ Older Typescript versions _may_ continue to be compatible, but no guarantees app ### `@sentry/core` / All SDKs -- Passing `undefined` as a `tracesSampleRate` option value will now be treated the same as if the option was not defined at all. - In previous versions, it was checked whether `tracesSampleRate` or `traceSampler` are _defined_ at all, in `Sentry.init()` to determine whether tracing should be enabled. - Passing `undefined` to `tracesSampleRate` previously would enable tracing without the performance monitoring aspect (=tracing being enabled, though no spans would be started). - If you want to preserve having tracing enabled without creating spans, set `tracesSampleRate: 0`: - - ```diff - Sentry.init({ - - tracesSampleRate: undefined, - + tracesSampleRate: 0, - }); - ``` - - 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). @@ -93,6 +81,12 @@ Older Typescript versions _may_ continue to be compatible, but no guarantees app }); ``` +- 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. + - 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: From 6d593946550527ba8aeadc627192f3b2bf44ae24 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 5 Feb 2025 12:03:54 +0000 Subject: [PATCH 13/13] Heading --- docs/migration/v8-to-v9.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration/v8-to-v9.md b/docs/migration/v8-to-v9.md index af86512ee675..94fd64683c69 100644 --- a/docs/migration/v8-to-v9.md +++ b/docs/migration/v8-to-v9.md @@ -491,7 +491,7 @@ These changes should not affect most users unless you relied on passing things w In v8, interfaces have been exported from `@sentry/types`, while implementations have been exported from other packages. -# No Version Support Timeline +## No Version Support Timeline 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.