diff --git a/MIGRATION.md b/MIGRATION.md index 277bf2e1c44c..e13e0d1148c0 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -4,1947 +4,514 @@ These docs walk through how to migrate our JavaScript SDKs through different maj - Upgrading from [SDK 4.x to 5.x/6.x](./docs/migration/v4-to-v5_v6.md) - Upgrading from [SDK 6.x to 7.x](./docs/migration/v6-to-v7.md) -- Upgrading from [SDK 7.x to 8.x](./MIGRATION.md#upgrading-from-7x-to-8x) -- Upgrading from [SDK 8.x to 9.x](./docs/migration/v8-to-v9.md) (Work in Progress - v9 is not released yet) +- Upgrading from [SDK 7.x to 8.x](./docs/migration/v7-to-v8.md) +- Upgrading from [SDK 8.x to 9.x](./docs/migration/v8-to-v9.md#upgrading-from-7x-to-8x) -# Upgrading from 7.x to 8.x +# Upgrading from 8.x to 9.x -The main goal of version 8 is to improve our performance monitoring APIs, integrations API, and ESM support. This -version is breaking because we removed deprecated APIs, restructured npm package contents, and introduced new -dependencies on OpenTelemetry. Below we will outline the steps you need to take to tackle to deprecated methods. +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 `8.x` of the SDK, we recommend upgrading to the latest version of `7.x`. You can then follow -[these steps](./MIGRATION.md#deprecations-in-7x) remove deprecated methods in `7.x` before upgrading to `8.x`. +`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. -The v8 version of the JavaScript SDK requires a self-hosted version of Sentry 24.4.2 (for user feedback screenshots) or -higher. Lower versions may continue to work, but may not support all features (e.g. the new user feedback APIs). +## 1. Version Support Changes: -## 1. Version Support changes: +Version 9 of the Sentry SDK has new compatibility ranges for runtimes and frameworks. -**Node.js**: We now officially support Node 14.18+ for our CJS package, and Node 18.19.1+ for our ESM package. This -applies to `@sentry/node` and all of our node-based server-side sdks (`@sentry/nextjs`, `@sentry/serverless`, etc.). We -no longer test against Node 8, 10, or 12 and cannot guarantee that the SDK will work as expected on these versions. +### General Runtime Support Changes -**Browser**: Our browser SDKs (`@sentry/browser`, `@sentry/react`, `@sentry/vue`, etc.) now require ES2018+ -compatibility plus support for -[`globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis). This means -that we no longer support IE11 (end of an era). This also means that the Browser SDK requires the fetch API to be -available in the environment. +**ECMAScript Version:** All the JavaScript code in the Sentry SDK packages may now contain ECMAScript 2020 features. +This includes features like Nullish Coalescing (`??`), Optional Chaining (`?.`), `String.matchAll()`, Logical Assignment Operators (`&&=`, `||=`, `??=`), and `Promise.allSettled()`. -New minimum supported browsers: +If you observe failures due to syntax or features listed above, it may indicate that your current runtime does not support ES2020. +If your runtime does not support ES2020, we recommend transpiling the SDK using Babel or similar tooling. -- Chrome 71 -- Edge 79 -- Safari 12.1, iOS Safari 12.2 -- Firefox 65 -- Opera 58 -- Samsung Internet 10 +**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. -For IE11 support please transpile your code to ES5 using babel or similar and add required polyfills. +**Browsers:** Due to SDK code now including ES2020 features, the minimum supported browser list now looks as follows: -**React**: The Next.js SDK now supports React 16+ +- Chrome 80 +- Edge 80 +- Safari 14, iOS Safari 14.4 +- Firefox 74 +- Opera 67 +- Samsung Internet 13.0 -**Next.js**: The Next.js SDK now supports Next.js 13.2.0+ +If you need to support older browsers, we recommend transpiling your code using SWC, Babel or similar tooling. -**Express**: Complex router setups are only properly parametrized in Node 16+. +**Deno:** The minimum supported Deno version is now **2.0.0**. -## 2. Package removal +### Framework and Library Support Changes -We've removed the following packages: +Support for the following frameworks and library versions are dropped: -- [@sentry/hub](./MIGRATION.md#sentryhub) -- [@sentry/tracing](./MIGRATION.md#sentrytracing) -- [@sentry/integrations](./MIGRATION.md#sentryintegrations) -- [@sentry/serverless](./MIGRATION.md#sentryserverless) -- [@sentry/replay](./MIGRATION.md#sentryreplay) +- **Remix**: Version `1.x` +- **TanStack Router**: Version `1.63.0` and lower (relevant when using `tanstackRouterBrowserTracingIntegration`) +- **SvelteKit**: Version `1.x` +- **Ember.js**: Version `3.x` and lower (minimum supported version is `4.x`) +- **Prisma**: Version `5.x` -#### @sentry/hub +### TypeScript Version Policy -`@sentry/hub` has been removed and will no longer be published. All of the `@sentry/hub` exports have moved to -`@sentry/core`. +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`. -#### @sentry/tracing +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. -`@sentry/tracing` has been removed and will no longer be published. See -[below](./MIGRATION.md/#3-removal-of-deprecated-apis) for more details. +Older Typescript versions _may_ continue to be compatible, but no guarantees apply. -For Browser SDKs you can import `browserTracingIntegration` from the SDK directly: +## 2. Behavior Changes -```js -// v7 -import * as Sentry from '@sentry/browser'; -import { BrowserTracing } from '@sentry/tracing'; +### `@sentry/core` / All SDKs -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, - integrations: [new BrowserTracing()], -}); -``` +- 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. -```js -// v8 -import * as Sentry from '@sentry/browser'; +- The `beforeSendSpan` hook now receives the root span as well as the child spans. + We recommend checking your `beforeSendSpan` to account for this change. -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, - integrations: [Sentry.browserTracingIntegration()], -}); -``` +- 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`. -If you don't want to use `browserTracingIntegration` but still manually start spans, you can now use -`Sentry.registerSpanErrorInstrumentation()` to setup handlers for span instrumentation. -`registerSpanErrorInstrumentation` replaces the `addExtensionMethods` method from `@sentry/tracing`. +- 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 -// v7 -import * as Sentry from '@sentry/browser'; -import '@sentry/tracing'; - -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, -}); -``` - -```js -// v8 -import * as Sentry from '@sentry/browser'; - -Sentry.registerSpanErrorInstrumentation(); - -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, -}); -``` - -For Node SDKs you no longer need the side effect import, you can remove all references to `@sentry/tracing`. - -```js -// v7 -const Sentry = require('@sentry/node'); -require('@sentry/tracing'); - -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, -}); -``` - -```js -// v8 -const Sentry = require('@sentry/node'); - -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, -}); -``` - -#### @sentry/integrations - -`@sentry/integrations` has been removed and will no longer be published. We moved pluggable integrations from their own -package (`@sentry/integrations`) to `@sentry/browser` and `@sentry/node`. in addition they are now functions instead of -classes. - -```js -// v7 -import { RewriteFrames } from '@sentry/integrations'; -``` - -```js -// v8 -import { rewriteFramesIntegration } from '@sentry/browser'; -``` - -Integrations that are now exported from `@sentry/browser` (or framework-specific packages like `@sentry/react`): - -- `httpClientIntegration` (`HTTPClient`) -- `contextLinesIntegration` (`ContextLines`) -- `reportingObserverIntegration` (`ReportingObserver`) - -Integrations that are now exported from `@sentry/node` and `@sentry/browser` (or framework-specific packages like -`@sentry/react`): - -- `captureConsoleIntegration` (`CaptureConsole`) -- `debugIntegration` (`Debug`) -- `extraErrorDataIntegration` (`ExtraErrorData`) -- `rewriteFramesIntegration` (`RewriteFrames`) -- `sessionTimingIntegration` (`SessionTiming`) -- `dedupeIntegration` (`Dedupe`) - _Note: enabled by default, not pluggable_ - -The `Transaction` integration has been removed from `@sentry/integrations`. There is no replacement API. - -#### @sentry/serverless - -`@sentry/serverless` has been removed and will no longer be published. The serverless package has been split into two -different packages, `@sentry/aws-serverless` and `@sentry/google-cloud-serverless`. - -The `@sentry/google-cloud-serverless` package has also been changed to only emit CJS builds because it can only -instrument CJS. ESM support will be re-added at a later date. - -In `@sentry/serverless` you had to use a namespace import to initialize the SDK. This has been removed so that you can -directly import from the SDK instead. - -```js -// v7 -const Sentry = require('@sentry/serverless'); - -Sentry.AWSLambda.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, -}); - -// v8 -const Sentry = require('@sentry/aws-serverless'); - -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, -}); -``` - -```js -// v7 -const Sentry = require('@sentry/serverless'); - -Sentry.GCPFunction.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, -}); - -// v8 -const Sentry = require('@sentry/google-cloud-serverless'); - -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, -}); -``` - -#### @sentry/replay - -`@sentry/replay` has been removed and will no longer be published. You can import replay functionality and the replay -integration directly from the Browser SDK or browser framework-specific packages like `@sentry/react`. - -```js -// v7 -import { Replay } from '@sentry/replay'; -``` - -```js -import { replayIntegration } from '@sentry/browser'; -``` - -## 3. Performance Monitoring Changes - -- [Initializing the SDK in v8](./MIGRATION.md/#initializing-the-node-sdk) -- [Performance Monitoring API](./MIGRATION.md#performance-monitoring-api) -- [Performance Monitoring Integrations](./MIGRATION.md#performance-monitoring-integrations) - -### Initializing the Node SDK - -If you are using `@sentry/node` or `@sentry/bun`, or a package that depends on it (`@sentry/nextjs`, `@sentry/remix`, -`@sentry/sveltekit`, `@sentry/`), you will need to initialize the SDK differently. The primary change is to ensure that -the SDK is initialized as early as possible. See [Initializing the SDK in v8](./docs/v8-initializing.md) on what steps -to follow. - -For example with the Remix SDK, you should initialize the SDK at the top of your `entry.server.tsx` server entrypoint -before you do anything else. - -```js -// first import Sentry and initialize Sentry -import * as Sentry from '@sentry/remix'; - -Sentry.init({ - dsn: 'https://public@dsn.ingest.sentry.io/1337', - tracesSampleRate: 1, - tracePropagationTargets: ['example.org'], - // Disabling to test series of envelopes deterministically. - autoSessionTracking: false, -}); - -// then handle everything else -import type { EntryContext } from '@remix-run/node'; -import { RemixServer } from '@remix-run/react'; -import { renderToString } from 'react-dom/server'; - -export const handleError = Sentry.wrapRemixHandleError; -``` - -### Performance Monitoring API - -The APIs for Performance Monitoring in the SDK have been revamped to align with OpenTelemetry, an open standard for -tracing and metrics. This allows us to provide a more consistent and powerful API for performance monitoring, and adds -support for a variety of new integrations out of the box for our Node SDK. - -Instead of using `startTransaction` and `span.startChild`, you rely on new helper methods to create spans top level -helpers to create spans. - -```js -// Measure how long a callback takes, `startSpan` returns the value of the callback. -// The span will become the "active span" for the duration of the callback. -const value = Sentry.startSpan({ name: 'mySpan' }, span => { - span.setAttribute('key', 'value'); - return expensiveFunction(); -}); - -// `startSpan` works with async callbacks as well - just make sure to return a promise! -const value = await Sentry.startSpan({ name: 'mySpan' }, async span => { - span.setAttribute('key', 'value'); - return await expensiveFunction(); -}); - -// You can nest spans via more `startSpan` calls. -const value = Sentry.startSpan({ name: 'mySpan' }, span => { - span.setAttribute('key1', 'value1'); - - // `nestedSpan` becomes the child of `mySpan`. - return Sentry.startSpan({ name: 'nestedSpan' }, nestedSpan => { - nestedSpan.setAttribute('key2', 'value2'); - return expensiveFunction(); + ```js + startSpan({ name: 'example', scope: customScope }, () => { + getCurrentScope().setTag('tag-a', 'a'); // this tag will only remain within the callback + // set the tag directly on customScope in addition, if you want to to persist the tag outside of the callback + customScope.setTag('tag-a', 'a'); }); -}); - -// You can also create an inactive span that does not take a callback. -// Useful when you need to pass a span reference into another closure (like measuring duration between hooks). -const span = Sentry.startInactiveSpan({ name: 'mySpan' }); - -// Use `startSpanManual` if you want to manually control when to end the span -// Useful when you need to hook into event emitters or similar. -function middleware(res, req, next) { - return Sentry.startSpanManual({ name: 'mySpan' }, span => { - res.on('finish', () => { - span.end(); - }); - return next(); - }); -} -``` - -You can [read more about the new performance APIs here](./docs/v8-new-performance-apis.md). - -To accommodate these changes, we're removed the following APIs: - -- [`startTransaction` and `span.startChild`](./MIGRATION.md#deprecate-starttransaction--spanstartchild) -- [Certain arguments in `startSpan` and `startTransaction`](./MIGRATION.md#deprecate-arguments-for-startspan-apis) -- [`scope.getSpan` and `scope.setSpan`](./MIGRATION.md#deprecate-scopegetspan-and-scopesetspan) -- [Variations of `continueTrace`](./MIGRATION.md#deprecate-variations-of-sentrycontinuetrace) - -We've also removed a variety of [top level fields](./MIGRATION.md#deprecated-fields-on-span-and-transaction) on the -`span` class. - -### Performance Monitoring Integrations - -As we added support for OpenTelemetry, we have expanded the automatic instrumentation for our Node.js SDK. We are adding -support for frameworks like Fastify, Nest.js, and Hapi, and expanding support for databases like Prisma and MongoDB via -Mongoose. - -We now support the following integrations out of the box without extra configuration: - -- `httpIntegration`: Automatically instruments Node `http` and `https` standard libraries -- `nativeNodeFetchIntegration`: Automatically instruments top level fetch and undici -- `expressIntegration`: Automatically instruments Express.js -- `fastifyIntegration`: Automatically instruments Fastify -- `hapiIntegration`: Automatically instruments Hapi -- `graphqlIntegration`: Automatically instruments GraphQL -- `mongoIntegration`: Automatically instruments MongoDB -- `mongooseIntegration`: Automatically instruments Mongoose -- `mysqlIntegration`: Automatically instruments MySQL -- `mysql2Integration`: Automatically instruments MySQL2 -- `redisIntegration`: Automatically instruments Redis (supported clients: ioredis) -- `nestIntegration`: Automatically instruments Nest.js -- `postgresIntegration`: Automatically instruments PostgreSQL -- `prismaIntegration`: Automatically instruments Prisma - -To make sure these integrations work properly you'll have to change how you -[initialize the SDK](./docs/v8-initializing.md) - -## 4. Removal of deprecated APIs - -- [General](./MIGRATION.md#general) -- [Browser SDK](./MIGRATION.md#browser-sdk-browser-react-vue-angular-ember-etc) -- [Server-side SDKs (Node, Deno, Bun)](./MIGRATION.md#server-side-sdks-node-deno-bun-etc) -- [Next.js SDK](./MIGRATION.md#nextjs-sdk) -- [SvelteKit SDK](./MIGRATION.md#sveltekit-sdk) -- [Astro SDK](./MIGRATION.md#astro-sdk) -- [AWS Serverless SDK](./MIGRATION.md#aws-serverless-sdk) -- [Ember SDK](./MIGRATION.md#ember-sdk) -- [Svelte SDK](./MIGRATION.md#svelte-sdk) -- [React SDK](./MIGRATION.md#react-sdk) - -### General - -Removed top-level exports: `tracingOrigins`, `MetricsAggregator`, `metricsAggregatorIntegration`, `Severity`, -`Sentry.configureScope`, `Span`, `spanStatusfromHttpCode`, `makeMain`, `pushScope`, `popScope`, -`addGlobalEventProcessor`, `timestampWithMs`, `addExtensionMethods`, `addGlobalEventProcessor`, `getActiveTransaction` - -Removed `@sentry/utils` exports: `timestampWithMs`, `addOrUpdateIntegration`, `tracingContextFromHeaders`, `walk` - -- [Deprecation of `Hub` and `getCurrentHub()`](./MIGRATION.md#deprecate-hub) -- [Removal of class-based integrations](./MIGRATION.md#removal-of-class-based-integrations) -- [`tracingOrigins` option replaced with `tracePropagationTargets`](./MIGRATION.md#tracingorigins-has-been-replaced-by-tracepropagationtargets) -- [Removal of `MetricsAggregator` and `metricsAggregatorIntegration`](./MIGRATION.md#removal-of-the-metricsaggregator-integration-class-and-metricsaggregatorintegration) -- [Removal of `Severity` Enum](./MIGRATION.md#removal-of-severity-enum) -- [Removal of `Sentry.configureScope` method](./MIGRATION.md#removal-of-sentryconfigurescope-method) -- [Removal of `Span` class export from SDK packages](./MIGRATION.md#removal-of-span-class-export-from-sdk-packages) -- [Removal of `spanStatusfromHttpCode` in favour of `getSpanStatusFromHttpCode`](./MIGRATION.md#removal-of-spanstatusfromhttpcode-in-favour-of-getspanstatusfromhttpcode) -- [Removal of `addGlobalEventProcessor` in favour of `addEventProcessor`](./MIGRATION.md#removal-of-addglobaleventprocessor-in-favour-of-addeventprocessor) -- [Remove `void` from transport return types](./MIGRATION.md#remove-void-from-transport-return-types) -- [Remove `addGlobalEventProcessor` in favor of `addEventProcessor`](./MIGRATION.md#remove-addglobaleventprocessor-in-favor-of-addeventprocessor) - -#### Deprecation of `Hub` and `getCurrentHub()` - -The `Hub` has been a very important part of the Sentry SDK API up until now. Hubs were the SDK's "unit of concurrency" -to keep track of data across threads and to scope data to certain parts of your code. Because it is overly complicated -and confusing to power users, it is going to be replaced by a set of new APIs: the "new Scope API". For now `Hub` and -`getCurrentHub` are still available, but it will be removed in the next major version. - -See [Deprecate Hub](./MIGRATION.md#deprecate-hub) for details on how to replace existing usage of the Hub APIs. - -The `hub.bindClient` and `makeMain` methods have been removed entirely, see -[initializing the SDK in v8](./docs/v8-initializing.md) for details how to work around this. - -#### Removal of class-based integrations - -In v7, integrations are classes and can be added as e.g. `integrations: [new Sentry.Replay()]`. In v8, integrations will -not be classes anymore, but instead functions. Both the use as a class, as well as accessing integrations from the -`Integrations.XXX` hash, is deprecated in favor of using the new functional integrations. For example, -`new Integrations.LinkedErrors()` becomes `linkedErrorsIntegration()`. - -For docs on the new integration interface, see [below](./MIGRATION.md#changed-integration-interface). - -For a list of integrations and their replacements, see -[below](./MIGRATION.md#list-of-integrations-and-their-replacements). - -The `getIntegration()` and `getIntegrationById()` have been removed entirely, see -[below](./MIGRATION.md#deprecate-getintegration-and-getintegrationbyid). - -```js -// v7 -const replay = Sentry.getIntegration(Replay); -``` - -```js -// v8 -const replay = getClient().getIntegrationByName('Replay'); -``` - -#### `framesToPop` applies to parsed frames - -Error with `framesToPop` property will have the specified number of frames removed from the top of the stack. This -changes compared to the v7 where the property `framesToPop` was used to remove top n lines from the stack string. - -#### `tracingOrigins` has been replaced by `tracePropagationTargets` - -`tracingOrigins` is now removed in favor of the `tracePropagationTargets` option. The `tracePropagationTargets` option -should be set in the `Sentry.init()` options, or in your custom `Client`s option if you create them. We've also updated -the behavior of the `tracePropagationTargets` option for Browser SDKs, see -[below](./MIGRATION.md/#updated-behaviour-of-tracepropagationtargets-in-the-browser-http-tracing-headers--cors) for more -details. - -For example for the Browser SDKs: - -```ts -// v7 -Sentry.init({ - dsn: '__DSN__', - integrations: [new Sentry.BrowserTracing({ tracingOrigins: ['localhost', 'example.com'] })], -}); -``` - -```ts -// v8 -Sentry.init({ - dsn: '__DSN__', - integrations: [Sentry.browserTracingIntegration()], - tracePropagationTargets: ['localhost', 'example.com'], -}); -``` - -#### Removal of the `MetricsAggregator` integration class and `metricsAggregatorIntegration` - -The SDKs now support metrics features without any additional configuration. - -```ts -// v7 - Server (Node/Deno/Bun) -Sentry.init({ - dsn: '__DSN__', - _experiments: { - metricsAggregator: true, - }, -}); - -// v7 - Browser -Sentry.init({ - dsn: '__DSN__', - integrations: [Sentry.metricsAggregatorIntegration()], -}); -``` - -```ts -// v8 -Sentry.init({ - dsn: '__DSN__', -}); -``` - -#### Removal of Severity Enum - -In v7 we deprecated the `Severity` enum in favor of using the `SeverityLevel` type as this helps save bundle size, and -this has been removed in v8. You should now use the `SeverityLevel` type directly. - -```js -// v7 -import { Severity, SeverityLevel } from '@sentry/types'; + ``` -const levelA = Severity.error; +- 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. -const levelB: SeverityLevel = "error" -``` - -```js -// v8 -import { SeverityLevel } from '@sentry/types'; - -const levelA = "error" as SeverityLevel; - -const levelB: SeverityLevel = "error" -``` +- 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: -#### Removal of `Sentry.configureScope` method - -The top level `Sentry.configureScope` function has been removed. Instead, you should use the `Sentry.getCurrentScope()` -to access and mutate the current scope. - -```js -// v7 -Sentry.configureScope(scope => { - scope.setTag('key', 'value'); -}); -``` - -```js -// v8 -Sentry.getCurrentScope().setTag('key', 'value'); -``` - -#### Removal of `Span` class export from SDK packages - -In v8, we are no longer exporting the `Span` class from SDK packages (e.g. `@sentry/browser` or `@sentry/node`). -Internally, this class is now called `SentrySpan`, and it is no longer meant to be used by users directly. - -#### Removal of `spanStatusfromHttpCode` in favour of `getSpanStatusFromHttpCode` - -In v8, we are removing the `spanStatusfromHttpCode` function in favor of `getSpanStatusFromHttpCode`. - -```js -// v7 -const spanStatus = spanStatusfromHttpCode(200); -``` - -```js -// v8 -const spanStatus = getSpanStatusFromHttpCode(200); -``` - -#### Removal of `addGlobalEventProcessor` in favour of `addEventProcessor` - -In v8, we are removing the `addGlobalEventProcessor` function in favor of `addEventProcessor`. - -```js -// v7 -addGlobalEventProcessor(event => { - delete event.extra; - return event; -}); -``` - -```js -// v8 -Sentry.getGlobalScope().addEventProcessor(event => { - delete event.extra; - return event; -}); -``` - -#### Removal of `void` from transport return types - -The `send` method on the `Transport` interface now always requires a `TransportMakeRequestResponse` to be returned in -the promise. This means that the `void` return type is no longer allowed. - -```ts -// v7 -interface Transport { - send(event: Event): Promise; -} -``` - -```ts -// v8 -interface Transport { - send(event: Event): Promise; -} -``` - -#### Removal of `addGlobalEventProcessor` in favor of `addEventProcessor` - -In v8, we are removing the `addGlobalEventProcessor` function in favor of `addEventProcessor`. - -```js -// v7 -addGlobalEventProcessor(event => { - delete event.extra; - return event; -}); -``` - -```js -// v8 -addEventProcessor(event => { - delete event.extra; - return event; -}); -``` - -#### Removal of `Sentry.Handlers.trpcMiddleware()` in favor of `Sentry.trpcMiddleware()` - -The Sentry tRPC middleware got moved from `Sentry.Handlers.trpcMiddleware()` to `Sentry.trpcMiddleware()`. Functionally -they are the same: - -#### Removal of `Sentry.Handlers.requestHandler()`, `Sentry.Handlers.tracingHandler()` and `Sentry.Handlers.errorHandler()` - -For Express and Connect you previously had to use `Sentry.Handlers.requestHandler()`, -`Sentry.Handlers.tracingHandler()`, and `Sentry.Handlers.errorHandler()` to add Sentry instrumentation to your app. In -8.x, you only need to use the framework specific error handler (e.g `Sentry.setupExpressErrorHandler(app)`), you can -remove all other handlers. - -```js -// v7 -import * as Sentry from '@sentry/node'; -Sentry.Handlers.trpcMiddleware(); -``` - -```js -// v8 -import * as Sentry from '@sentry/node'; -Sentry.trpcMiddleware(); -``` - -### Browser SDK (Browser, React, Vue, Angular, Ember, etc.) - -Removed top-level exports: `Offline`, `makeXHRTransport`, `BrowserTracing`, `wrap` - -- [Removal of the `BrowserTracing` integration](./MIGRATION.md#removal-of-the-browsertracing-integration) -- [Removal of Offline integration](./MIGRATION.md#removal-of-the-offline-integration) -- [Removal of `makeXHRTransport` transport](./MIGRATION.md#removal-of-makexhrtransport-transport) -- [Removal of `wrap` method](./MIGRATION.md#removal-of-wrap-method) -- [Removal of `@sentry/angular-ivy` package](./MIGRATION.md#removal-of-sentryangular-ivy-package) -- [Removal of `@sentry/replay` package](./MIGRATION.md#removal-of-sentryreplay-package) - -#### Removal of the `BrowserTracing` integration - -The `BrowserTracing` integration, together with the custom routing instrumentations passed to it, are deprecated in v8. -Instead, you should use `Sentry.browserTracingIntegration()`. See examples -[below](./MIGRATION.md#deprecated-browsertracing-integration) - -#### Removal of `interactionsSampleRate` in `browserTracingIntegration` options - -The `interactionsSampleRate` option that could be passed to `browserTracingIntegration` or `new BrowserTracing()` was -removed in v8, due to the option being redundant and in favour of bundle size minimization. - -It's important to note that this sample rate only ever was applied when collecting INP (Interaction To Next Paint) -values. You most likely don't need to replace this option. Furthermore, INP values are already sampled by the -[`tracesSampleRate` SDK option](https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sampler), like -any regular span. At the time of writing, INP value collection does not deplete your span or transaction quota. - -If you used `interactionsSampleRate` before, and still want to reduce INP value collection, we recommend using the -`tracesSampler` SDK option instead: - -```javascript -// v7 -Sentry.init({ - integrations: [new BrowserTracing({ interactionsSampleRate: 0.1 })], -}); -``` - -```javascript -// v8 - please read the text above, you most likely don't need this :) -Sentry.init({ - tracesSampler: (ctx) => { - if (ctx.attributes?['sentry.op']?.startsWith('ui.interaction')) { - return 0.1; - } - return 0.5; - } -}) -``` - -#### Removal of the `Offline` integration - -The `Offline` integration has been removed in favor of the -[offline transport wrapper](http://docs.sentry.io/platforms/javascript/configuration/transports/#offline-caching). - -#### Removal of `makeXHRTransport` transport - -The `makeXHRTransport` transport has been removed. Only `makeFetchTransport` is available now. This means that the -Sentry SDK requires the fetch API to be available in the environment. - -#### Removal of `wrap` method - -The `wrap` method has been removed. There is no replacement API. - -#### Removal of `@sentry/angular-ivy` package - -The `@sentry/angular-ivy` package has been removed. The `@sentry/angular` package now supports Ivy by default and -requires at least Angular 14. If you are using Angular 13 or lower, we suggest upgrading your Angular version before -migrating to v8. If you can't upgrade your Angular version to at least Angular 14, you can also continue using the -`@sentry/angular-ivy@7` SDK. However, v7 of the SDKs will no longer be fully supported going forward. - -#### Removal of `@sentry/replay` package - -You can import from `@sentry/browser` (or from a respective SDK package like `@sentry/react` or `@sentry/vue`). - -### Server-side SDKs (Node, Deno, Bun, etc.) - -Removed top-level exports: `enableAnrDetection`, `Anr`, `deepReadDirSync`, `runWithAsyncContext` - -- [Removal of `enableAnrDetection` and `Anr` class](./MIGRATION.md#removal-of-enableanrdetection-and-anr-class) -- [Removal of `deepReadDirSync` method](./MIGRATION.md#removal-of-deepreaddirsync-method) -- [Removal of `runWithAsyncContext` method](./MIGRATION.md#removal-of-runwithasynccontext-method) -- [Removal of `Apollo` integration](./MIGRATION.md#removal-of-apollo-integration) - -#### Removal of `enableAnrDetection` and `Anr` class - -The `enableAnrDetection` and `Anr` class have been removed. See the -[docs](https://docs.sentry.io/platforms/node/configuration/application-not-responding/) for more details. PR: - -#### Removal of `deepReadDirSync` method + ```js + Sentry.init({ + integrations: [Sentry.captureConsoleIntegration({ handled: false })], + attachStackTrace: true, + }); + ``` -The `deepReadDirSync` method has been removed. There is no replacement API. +### `@sentry/browser` / All SDKs running in the browser -#### Removal of `runWithAsyncContext` method +- 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 `runWithAsyncContext` method has been removed in favour of `Sentry.withIsolationScope`. +### `@sentry/node` / All SDKs running in Node.js -```js -// before (v7) -Sentry.runWithAsyncContext(() => { - // Your code here... -}); +- 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. -// after (v8) -Sentry.withIsolationScope(() => { - // Your code here... -}); -``` +- 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. -#### Removal of Apollo integration +- The `processThreadBreadcrumbIntegration` was renamed to `childProcessIntegration`. -The Apollo integration has been removed in `8.x` as `8.x` automatically adds GraphQL support via `graphqlIntegration` -which is automatically enabled. +- 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. -```js -// before (v7) -Sentry.init({ - integrations: [Sentry.integrations.Apollo()], -}); +- 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. -// after (v8) -Sentry.init({}); -``` +- 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. -### Next.js SDK + For performance instrumentation using other/older Prisma versions: -Removed top-level exports: `withSentryApi`, `withSentryAPI`, `withSentryGetServerSideProps`, `withSentryGetStaticProps`, -`withSentryServerSideGetInitialProps`, `withSentryServerSideAppGetInitialProps`, -`withSentryServerSideDocumentGetInitialProps`, `withSentryServerSideErrorGetInitialProps`, `nextRouterInstrumentation`, -`IS_BUILD`, `isBuild` + 1. Install the `@prisma/instrumentation` package with the desired version. + 1. Pass a `new PrismaInstrumentation()` instance as exported from `@prisma/instrumentation` to the `prismaInstrumentation` option of this integration: -- [Removal of deprecated API in `@sentry/nextjs`](./MIGRATION.md#removal-of-deprecated-api-in-sentrynextjs) -- [Updated minimum compatible Next.js version to `13.2.0`](./MIGRATION.md#updated-minimum-compatible-nextjs-version-to-1320) -- [Merging of the Sentry Webpack Plugin options and SDK Build options](./MIGRATION.md#merging-of-the-sentry-webpack-plugin-options-and-sdk-build-options) -- [Removal of the `sentry` property in your Next.js options (next.config.js)](./MIGRATION.md#removal-of-the-sentry-property-in-your-nextjs-options-nextconfigjs) -- [Updated the `@sentry/webpack-plugin` dependency to version 2](./MIGRATION.md#updated-the-sentry-webpack-plugin-dependency-to-version-2) + ```js + import { PrismaInstrumentation } from '@prisma/instrumentation'; + Sentry.init({ + integrations: [ + prismaIntegration({ + // Override the default instrumentation that Sentry uses + prismaInstrumentation: new PrismaInstrumentation(), + }), + ], + }); + ``` -#### Removal of deprecated API in `@sentry/nextjs` + The passed instrumentation instance will override the default instrumentation instance the integration would use, while the `prismaIntegration` will still ensure data compatibility for the various Prisma versions. -The following previously deprecated API has been removed from the `@sentry/nextjs` package: + 1. Depending on your Prisma version (prior to Prisma version 6), add `previewFeatures = ["tracing"]` to the client generator block of your Prisma schema: -- `withSentryApi` (Replacement: `wrapApiHandlerWithSentry`) -- `withSentryAPI` (Replacement: `wrapApiHandlerWithSentry`) -- `withSentryGetServerSideProps` (Replacement: `wrapGetServerSidePropsWithSentry`) -- `withSentryGetStaticProps` (Replacement: `wrapGetStaticPropsWithSentry`) -- `withSentryServerSideGetInitialProps` (Replacement: `wrapGetInitialPropsWithSentry`) -- `withSentryServerSideAppGetInitialProps` (Replacement: `wrapAppGetInitialPropsWithSentry`) -- `withSentryServerSideDocumentGetInitialProps` (Replacement: `wrapDocumentGetInitialPropsWithSentry`) -- `withSentryServerSideErrorGetInitialProps` was renamed to `wrapErrorGetInitialPropsWithSentry` -- `nextRouterInstrumentation` (Replaced by using `browserTracingIntegration`) -- `IS_BUILD` -- `isBuild` + ``` + generator client { + provider = "prisma-client-js" + previewFeatures = ["tracing"] + } + ``` -#### Updated minimum compatible Next.js version to `13.2.0` +- 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 minimum version of Next.js compatible with the Sentry Next.js SDK has been raised to `13.2.0`. Older versions may -exhibit bugs or unexpected behaviour. +### All Meta-Framework SDKs (`@sentry/nextjs`, `@sentry/nuxt`, `@sentry/sveltekit`, `@sentry/astro`, `@sentry/solidstart`) -#### Merging of the Sentry Webpack Plugin options and SDK Build options +- SDKs no longer transform user-provided values for source map generation in build configurations (like Vite config, Rollup config, or `next.config.js`). -With version 8 of the Sentry Next.js SDK, `withSentryConfig` will no longer accept 3 arguments. The second argument -(holding options for the Sentry Webpack plugin) and the third argument (holding options for SDK build-time -configuration) should now be passed as one: + 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. -```ts -// OLD -const nextConfig = { - // Your Next.js options... -}; + To customize which files are deleted after upload, define the `filesToDeleteAfterUpload` array with globs. -module.exports = withSentryConfig( - nextConfig, - { - // Your Sentry Webpack Plugin Options... - }, - { - // Your Sentry SDK options... - }, -); +### `@sentry/react` -// NEW -const nextConfig = { - // Your Next.js options... -}; +- 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. -module.exports = withSentryConfig(nextConfig, { - // Your Sentry Webpack Plugin Options... - // AND your Sentry SDK options... -}); -``` + 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. -#### Removal of the `sentry` property in your Next.js options (next.config.js) +### `@sentry/nextjs` -With version 8 of the Sentry Next.js SDK, the SDK will no longer support passing Next.js options with a `sentry` -property to `withSentryConfig`. Please use the second argument of `withSentryConfig` to configure the SDK instead: - -```ts -// v7 -const nextConfig = { - // Your Next.js options... - - sentry: { - // Your Sentry SDK options... - }, -}; - -module.exports = withSentryConfig(nextConfig, { - // Your Sentry Webpack Plugin Options... -}); -``` - -```ts -// v8 -const nextConfig = { - // Your Next.js options... -}; - -module.exports = withSentryConfig(nextConfig, { - // Your Sentry Webpack Plugin Options... - // AND your Sentry SDK options... -}); -``` - -The reason for this change is to have one consistent way of defining the SDK options. We hope that this change will -reduce confusion when setting up the SDK, with the upside that the explicit option is properly typed and will therefore -have code completion. - -#### Updated the `@sentry/webpack-plugin` dependency to version 2 - -We bumped the internal usage of `@sentry/webpack-plugin` to a new major version. This comes with multiple upsides like a -simpler configuration interface and the use of new state of the art Debug ID technology. Debug IDs will simplify the -setup for source maps in Sentry and will not require you to match stack frame paths to uploaded artifacts anymore. - -To see the new options, check out the docs at https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/, -or look at the TypeScript type definitions of `withSentryConfig`. - -#### Updated the recommended way of calling `Sentry.init()` - -Version 8 of the Next.js SDK will require an additional `instrumentation.ts` file to execute the `sentry.server.config.js|ts` and `sentry.edge.config.js|ts` modules to initialize the SDK for the server-side. -The `instrumentation.ts` file is a Next.js native API called [instrumentation hook](https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation). - -To start using the Next.js instrumentation hook, follow these steps: - -1. First, enable the Next.js instrumentation hook by setting the [`experimental.instrumentationHook`](https://nextjs.org/docs/app/api-reference/next-config-js/instrumentationHook) to true in your `next.config.js`. (This step is no longer required with Next.js 15) - - ```JavaScript {filename:next.config.js} {2-4} - module.exports = { - experimental: { - instrumentationHook: true, // Not required on Next.js 15+ - }, - } - ``` +- 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. -2. Next, create a `instrumentation.ts|js` file in the root directory of your project (or in the src folder if you have have one). +- 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. -3. Now, export a register function from the `instrumentation.ts|js` file and import your `sentry.server.config.js|ts` and `sentry.edge.config.js|ts` modules: + 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. - ```JavaScript {filename:instrumentation.js} - import * as Sentry from '@sentry/nextjs'; - - export async function register() { - if (process.env.NEXT_RUNTIME === 'nodejs') { - await import('./sentry.server.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. - if (process.env.NEXT_RUNTIME === 'edge') { - await import('./sentry.edge.config'); - } - } - ``` +- The `sentry` property on the Next.js config object has officially been discontinued. + Pass options to `withSentryConfig` directly. - Note that you can initialize the SDK differently depending on which server runtime is being used. +## 3. Package Removals -If you are using a -[Next.js custom server](https://nextjs.org/docs/pages/building-your-application/configuring/custom-server), the -`instrumentation.ts` hook is not called by Next.js so you need to manually call it yourself from within your server -code. It is recommended to do so as early as possible in your application lifecycle. +The `@sentry/utils` package will no longer be published. -**Why are we making this change?** The very simple reason is that Next.js requires us to set up OpenTelemetry -instrumentation inside the `register` function of the instrumentation hook. Looking a little bit further into the -future, we also would like the Sentry SDK to be compatible with [Turbopack](https://turbo.build/pack), which is gonna be -the bundler that Next.js will be using instead of Webpack. The SDK in its previous version depended heavily on Webpack -in order to inject the `sentry.(server|edge).config.ts` files into the server-side code. Because this will not be -possible in the future, we are doing ourselves a favor and doing things the way Next.js intends us to do them - -hopefully reducing bugs and jank. +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. -#### Removal of `transpileClientSDK` +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. -Since we are dropping support for Internet Explorer 11 and other other older browser versions, we are also removing the -`transpileClientSDK` option from the Next.js SDK. If you need to support these browser versions, please configure -Webpack and Next.js to down-compile the SDK. +## 4. Removed APIs -### Astro SDK +### `@sentry/core` / All SDKs -- [Removal of `trackHeaders` option for Astro middleware](./MIGRATION.md#removal-of-trackheaders-option-for-astro-middleware) +- **The metrics API has been removed from the SDK.** -#### Removal of `trackHeaders` option for Astro middleware + 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). -Instead of opting-in via the middleware config, you can configure if headers should be captured via -`requestDataIntegration` options, which defaults to `true` but can be disabled like this: +- 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`: -```js -Sentry.init({ - integrations: [ - Sentry.requestDataIntegration({ - include: { - headers: false, - }, - }), - ], -}); -``` - -### SvelteKit SDK - -- [Breaking `sentrySvelteKit()` changes](./MIGRATION.md#breaking-sentrysveltekit-changes) - -#### Breaking `sentrySvelteKit()` changes - -We upgraded the `@sentry/vite-plugin` from version 0.x to 2.x. This package is internally used by the -`@sentry/sveltekit` SDK. With this change, resolving uploaded source maps should work out of the box much more often -than before -([more information](https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/artifact-bundles/)). - -To allow future upgrades of the Vite plugin without breaking stable and public APIs in `sentrySvelteKit`, we modified -the `sourceMapsUploadOptions` to remove the hard dependency on the API of the plugin. While you previously could specify -all [version 0.x Vite plugin options](https://www.npmjs.com/package/@sentry/vite-plugin/v/0.6.1), we now reduced them to -a subset of [2.x options](https://www.npmjs.com/package/@sentry/vite-plugin/v/2.14.2#options). All of these options are -optional just like before but here's an example of using the new options. - -```js -// v7 -sentrySvelteKit({ - sourceMapsUploadOptions: { - org: process.env.SENTRY_ORG, - project: process.env.SENTRY_PROJECT, - authToken: process.env.SENTRY_AUTH_TOKEN, - release: '1.0.1', - injectRelease: true, - include: ['./build/*/**/*'], - ignore: ['**/build/client/**/*'] - }, -}), -``` - -```js -// v8 -sentrySvelteKit({ - sourceMapsUploadOptions: { - org: process.env.SENTRY_ORG, - project: process.env.SENTRY_PROJECT, - authToken: process.env.SENTRY_AUTH_TOKEN, - release: { - name: '1.0.1', - inject: true - }, - sourcemaps: { - assets: ['./build/*/**/*'], - ignore: ['**/build/client/**/*'], - filesToDeleteAfterUpload: ['./build/**/*.map'] + ```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; + } }, - }, -}), -``` - -In the future, we might add additional [options](https://www.npmjs.com/package/@sentry/vite-plugin/v/2.14.2#options) -from the Vite plugin but if you would like to specify some of them directly, you can do this by passing in an -`unstable_sentryVitePluginOptions` object: -```js -sentrySvelteKit({ - sourceMapsUploadOptions: { - // ... - release: { - name: '1.0.1', - }, - unstable_sentryVitePluginOptions: { - release: { - setCommits: { - auto: true - } + // Custom profiles sampler + profilesSampler: samplingContext => { + - if (samplingContext.transactionContext.name === '/health-check') { + + if (samplingContext.name === '/health-check') { + return 0; + } else { + return 0.5; } - } - }, -}), -``` - -Important: we DO NOT guarantee stability of `unstable_sentryVitePluginOptions`. They can be removed or updated at any -time, including breaking changes within the same major version of the SDK. - -### AWS Serverless SDK - -- [Removal of `rethrowAfterCapture` option](./MIGRATION.md#removal-of-rethrowaftercapture-option) - -#### Removal of `rethrowAfterCapture` option - -In `v6.17.2` the `rethrowAfterCapture` option to `wrapHandler` was deprecated. In `v8` it has been removed. There is no -replacement API. - -### Ember SDK - -Removed top-level exports: `InitSentryForEmber`, `StartTransactionFunction` - -- [Removal of `InitSentryForEmber` export](./MIGRATION.md#removal-of-initsentryforember-export) -- [Updated Ember Dependencies](./MIGRATION.md#updated-ember-dependencies) - -#### Removal of `InitSentryForEmber` export - -The `InitSentryForEmber` export has been removed. Instead, you should use the `Sentry.init` method to initialize the -SDK. + }, + }) + ``` -#### Updated Ember Dependencies +- The `enableTracing` option was removed. + Instead, set `tracesSampleRate: 1` or `tracesSampleRate: 0`. -The following dependencies that the SDK uses have been bumped to a more recent version: +- The `autoSessionTracking` option was removed. -- `ember-auto-import` is bumped to `^2.4.3` -- `ember-cli-babel` is bumped to `^8.2.0` -- `ember-cli-typescript` is bumped to `^5.3.0` + 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) -### Svelte SDK + 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. -Removed top-level exports: `componentTrackingPreprocessor` +- 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. -#### Removal of `componentTrackingPreprocessor` export +- The `addOpenTelemetryInstrumentation` method has been removed. Use the `openTelemetryInstrumentations` option in `Sentry.init()` or your custom Sentry Client instead. -The `componentTrackingPreprocessor` export has been removed. You should instead use `withSentryConfig` to configure -component tracking. + ```js + import * as Sentry from '@sentry/node'; -```js -// v7 - svelte.config.js -import { componentTrackingPreprocessor } from '@sentry/svelte'; + // before + Sentry.addOpenTelemetryInstrumentation(new GenericPoolInstrumentation()); -const config = { - preprocess: [ - componentTrackingPreprocessor(), - // ... - ], - // ... -}; + // after + Sentry.init({ + openTelemetryInstrumentations: [new GenericPoolInstrumentation()], + }); + ``` -export default config; -``` +- The `debugIntegration` has been removed. To log outgoing events, use [Hook Options](https://docs.sentry.io/platforms/javascript/configuration/options/#hooks) (`beforeSend`, `beforeSendTransaction`, ...). -```js -// v8 - svelte.config.js -import { withSentryConfig } from "@sentry/svelte"; +- The `sessionTimingIntegration` has been removed. To capture session durations alongside events, use [Context](https://docs.sentry.io/platforms/javascript/enriching-events/context/) (`Sentry.setContext()`). -const config = { - // Your svelte config - compilerOptions: {...}, -}; +### Server-side SDKs (`@sentry/node` and all dependents) -export default withSentryConfig(config); -``` +- The `addOpenTelemetryInstrumentation` method was removed. + Use the `openTelemetryInstrumentations` option in `Sentry.init()` or your custom Sentry Client instead. -### React SDK +- `registerEsmLoaderHooks` now only accepts `true | false | undefined`. + The SDK will default to wrapping modules that are used as part of OpenTelemetry Instrumentation. -#### Updated error types to be `unknown` instead of `Error`. +- The `nestIntegration` was removed. + Use the NestJS SDK (`@sentry/nestjs`) instead. -In v8, we are changing the `ErrorBoundary` error types returned from `onError`, `onReset`, `onUnmount`, and -`beforeCapture`. to be `unknown` instead of `Error`. This more accurately matches behaviour of `componentDidCatch`, the -lifecycle method the Sentry `ErrorBoundary` component uses. +- The `setupNestErrorHandler` was removed. + Use the NestJS SDK (`@sentry/nestjs`) instead. -As per the [React docs on error boundaries](https://react.dev/reference/react/Component#componentdidcatch): +### `@sentry/browser` -> error: The `error` that was thrown. In practice, it will usually be an instance of `Error` but this is not guaranteed -> because JavaScript allows to throw any value, including strings or even `null`. +- The `captureUserFeedback` method has been removed. + Use the `captureFeedback` method instead and update the `comments` field to `message`. -This means you will have to use `instanceof Error` or similar to explicitly make sure that the error thrown was an -instance of `Error`. +### `@sentry/nextjs` -The Sentry SDK maintainers also went ahead and made a PR to update the -[TypeScript definitions of `componentDidCatch`](https://github.com/DefinitelyTyped/DefinitelyTyped/pull/69434) for the -React package - this will be released with React 20. +- The `hideSourceMaps` option was removed without replacements. + The SDK emits hidden sourcemaps by default. -### Gatsby SDK +### `@sentry/solidstart` -#### Removal of Gatsby Initialization via plugin options +- The `sentrySolidStartVite` plugin is no longer exported. Instead, wrap the SolidStart config with `withSentry` and + provide Sentry options as the second parameter. -In v8, we are removing the ability to initialize the Gatsby SDK via plugin options. Instead, you should create a -`sentry.config.js` file in the root of your project and initialize the SDK there. + ```ts + // app.config.ts + import { defineConfig } from '@solidjs/start/config'; + import { withSentry } from '@sentry/solidstart'; -```js -// v7 - gatsby-config.js -module.exports = { - // ... - plugins: [ - { - resolve: '@sentry/gatsby', - options: { - dsn: process.env.SENTRY_DSN, - }, - }, - // ... - ], -}; -``` - -```js -// v8 - gatsby-config.js -module.exports = { - // ... - plugins: [ - { - resolve: '@sentry/gatsby', - }, - // ... - ], -}; - -// v8 - sentry.config.js -import * as Sentry from '@sentry/gatsby'; - -Sentry.init({ - dsn: '__PUBLIC_DSN__', -}); -``` - -We've also added `enableClientWebpackPlugin` which allows you to enable or disable the `@sentry/webpack-plugin` in the -client-side build. By default, it is enabled. - -```js -// v8 - gatsby-config.js -module.exports = { - // ... - plugins: [ - { - resolve: '@sentry/gatsby', - options: { - enableClientWebpackPlugin: false, + export default defineConfig( + withSentry( + { + /* SolidStart config */ }, - }, - // ... - ], -}; -``` - -#### Automatic adding of `browserTracingIntegration` for Gatsby - -The Gatsby SDK no longer adds the `browserTracingIntegration` automatically. If you want to enable tracing in the -browser, you need to add it manually. Make sure to also configured a `tracePropagationTargets` value. - -```js -// v7 - gatsby-config.js -module.exports = { - // ... - plugins: [ - { - resolve: '@sentry/gatsby', - options: { - tracesSampleRate: 1.0, + { + /* Sentry build-time config (like project and org) */ }, - }, - // ... - ], -}; -``` - -```js -// v8 - gatsby-config.js -module.exports = { - // ... - plugins: [ - { - resolve: '@sentry/gatsby', - }, - // ... - ], -}; - -// v8 - sentry.config.js -import * as Sentry from '@sentry/gatsby'; - -Sentry.init({ - dsn: '__PUBLIC_DSN__', - integrations: [Sentry.browserTracingIntegration()], - - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for performance monitoring. - // We recommend adjusting this value in production - tracesSampleRate: 1.0, - - // Set `tracePropagationTargets` to control for which URLs distributed tracing should be enabled - tracePropagationTargets: ['localhost', /^https:\/\/yourserver\.io\/api/], -}); -``` - -## 5. Behaviour Changes - -- [Updated behaviour of `tracePropagationTargets` in the browser](./MIGRATION.md#updated-behaviour-of-tracepropagationtargets-in-the-browser-http-tracing-headers--cors) -- [Updated behaviour of `extraErrorDataIntegration`](./MIGRATION.md#extraerrordataintegration-changes) -- [Updated behaviour of `transactionContext` passed to `tracesSampler`](./MIGRATION.md#transactioncontext-no-longer-passed-to-tracessampler) -- [Updated behaviour of `getClient()`](./MIGRATION.md#getclient-always-returns-a-client) -- [Updated behaviour of the SDK in combination with `onUncaughtException` handlers in Node.js](./MIGRATION.md#behaviour-in-combination-with-onuncaughtexception-handlers-in-node.js) -- [Updated expected return value for `captureException()`, `captureMessage()` and `captureEvent` methods on Clients](./MIGRATION.md#updated-expected-return-value-for-captureexception-capturemessage-and-captureevent-methods-on-clients) -- [Removal of Client-Side health check transaction filters](./MIGRATION.md#removal-of-client-side-health-check-transaction-filters) -- [Change of Replay default options (`unblock` and `unmask`)](./MIGRATION.md#change-of-replay-default-options-unblock-and-unmask) -- [Angular Tracing Decorator renaming](./MIGRATION.md#angular-tracing-decorator-renaming) - -#### Updated behaviour of `tracePropagationTargets` in the browser (HTTP tracing headers & CORS) - -We updated the behaviour of the SDKs when no `tracePropagationTargets` option was defined. As a reminder, you can -provide a list of strings or RegExes that will be matched against URLs to tell the SDK, to which outgoing requests -tracing HTTP headers should be attached to. These tracing headers are used for distributed tracing. - -Previously, on the browser, when `tracePropagationTargets` were not defined, they defaulted to the following: -`['localhost', /^\/(?!\/)/]`. This meant that all request targets to that had "localhost" in the URL, or started with a -`/` were equipped with tracing headers. This default was chosen to prevent CORS errors in your browser applications. -However, this default had a few flaws. - -Going forward, when the `tracePropagationTargets` option is not set, tracing headers will be attached to all outgoing -requests on the same origin. For example, if you're on `https://example.com/` and you send a request to -`https://example.com/api`, the request will be traced (ie. will have trace headers attached). Requests to -`https://api.example.com/` will not, because it is on a different origin. The same goes for all applications running on -`localhost`. - -When you provide a `tracePropagationTargets` option, all of the entries you defined will now be matched be matched -against the full URL of the outgoing request. Previously, it was only matched against what you called request APIs with. -For example, if you made a request like `fetch("/api/posts")`, the provided `tracePropagationTargets` were only compared -against `"/api/posts"`. Going forward they will be matched against the entire URL, for example, if you were on the page -`https://example.com/` and you made the same request, it would be matched against `"https://example.com/api/posts"`. - -But that is not all. Because it would be annoying having to create matchers for the entire URL, if the request is a -same-origin request, we also match the `tracePropagationTargets` against the resolved `pathname` of the request. -Meaning, a matcher like `/^\/api/` would match a request call like `fetch('/api/posts')`, or -`fetch('https://same-origin.com/api/posts')` but not `fetch('https://different-origin.com/api/posts')`. + ), + ); + ``` -#### `extraErrorDataIntegration` changes +### `@sentry/nestjs` -The `extraErrorDataIntegration` integration now looks at -[`error.cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause) by -default. +- Removed `@WithSentry` decorator. + Use the `@SentryExceptionCaptured` decorator as a drop-in replacement. -#### `transactionContext` no longer passed to `tracesSampler` +- Removed `SentryService`. -Instead of an `transactionContext` being passed to the `tracesSampler` callback, the callback will directly receive -`name` and `attributes` going forward. Note that the `attributes` are only the attributes at span creation time, and -some attributes may only be set later during the span lifecycle (and thus not be available during sampling). + - 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. -#### `getClient()` always returns a client +- Removed `SentryTracingInterceptor`. -`getClient()` now always returns a client if `Sentry.init()` was called. For cases where this may be used to check if -Sentry was actually initialized, using `getClient()` will thus not work anymore. Instead, you should use the new -`Sentry.isInitialized()` utility to check this. + - 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. -#### Behaviour in combination with `onUncaughtException` handlers in Node.js +- Removed `SentryGlobalGenericFilter`. + Use the `SentryGlobalFilter` as a drop-in replacement. -Previously the SDK exited the process by default, even though additional `onUncaughtException` may have been registered, -that would have prevented the process from exiting. You could opt out of this behaviour by setting the -`exitEvenIfOtherHandlersAreRegistered: false` in the `onUncaughtExceptionIntegration` options. Up until now the value -for this option defaulted to `true`. - -Going forward, the default value for `exitEvenIfOtherHandlersAreRegistered` will be `false`, meaning that the SDK will -not exit your process when you have registered other `onUncaughtException` handlers. - -#### Updated expected return value for `captureException()`, `captureMessage()` and `captureEvent` methods on Clients - -The `Client` interface now expects implementations to always return a string representing the generated event ID for the -`captureException()`, `captureMessage()`, `captureEvent()` methods. Previously `undefined` was a valid return value. - -#### Removal of Client-Side health check transaction filters - -The SDK no longer filters out health check transactions by default. Instead, they are sent to Sentry but still dropped -by the Sentry backend by default. You can disable dropping them in your Sentry project settings. If you still want to -drop specific transactions within the SDK you can either use the `ignoreTransactions` SDK option. - -#### Change of Replay default options (`unblock` and `unmask`) - -The Replay options `unblock` and `unmask` now have `[]` as default value. This means that if you want to use these -options, you have to explicitly set them like this: - -```js -Sentry.init({ - integrations: [ - Sentry.replayIntegration({ - unblock: ['.sentry-unblock, [data-sentry-unblock]'], - unmask: ['.sentry-unmask, [data-sentry-unmask]'], - }), - ], -}); -``` - -#### Angular Tracing Decorator renaming - -The usage of `TraceClassDecorator` and the `TraceMethodDecorator` already implies that those are decorators. The word -`Decorator` is now removed from the names to avoid multiple mentioning. - -Additionally, the `TraceClass` and `TraceMethod` decorators accept an optional `name` parameter to set the transaction -name. This was added because Angular minifies class and method names, and you might want to set a more descriptive name. -If nothing provided, the name defaults to `'unnamed'`. - -```js -// v7 -@Sentry.TraceClassDecorator() -export class HeaderComponent { - @Sentry.TraceMethodDecorator() - ngOnChanges(changes: SimpleChanges) {} -} -``` - -```js -// v8 -@Sentry.TraceClass({ name: 'HeaderComponent' }) -export class HeaderComponent { - @Sentry.TraceMethod({ name: 'ngOnChanges' }) - ngOnChanges(changes: SimpleChanges) {} -} -``` - -## 6. Build Changes - -We now provide a proper ESM output of the SDK. There have also been some other build changes under the hood. One side -effect of this is that importing Sentry as a default import does not work anymore. Note that this was never supported -(even on v7) and this was never intended to work (and also not documented anywhere). However, it seems that for some -configuration combinations, it was still possible to do `import Sentry from '@sentry/browser'`. This is not possible -anymore in v8. Please use `import * as Sentry from '@sentry/browser'` instead. - -# Upgrading Sentry Feedback (beta, 7.x to 8.0) - -For details on upgrading Feedback from the beta 7.x to the release 8.x version, please view the -[dedicated Feedback MIGRATION docs](./docs/migration/feedback.md). - ---- - -# Deprecations in 7.x - -You can use the **Experimental** [@sentry/migr8](https://www.npmjs.com/package/@sentry/migr8) to automatically update -your SDK usage and fix most deprecations. This requires Node 18+. - -```bash -npx @sentry/migr8@latest -``` - -This will let you select which updates to run, and automatically update your code. Make sure to still review all code -changes! - -## Deprecated `BrowserTracing` integration - -The `BrowserTracing` integration, together with the custom routing instrumentations passed to it, are deprecated in v8. -Instead, you should use `Sentry.browserTracingIntegration()`. - -Package-specific browser tracing integrations are available directly. In most cases, there is a single integration -provided for each package, which will make sure to set up performance tracing correctly for the given SDK. For react, we -provide multiple integrations to cover different router integrations: - -### `@sentry/browser`, `@sentry/svelte`, `@sentry/gatsby` - -```js -import * as Sentry from '@sentry/browser'; - -Sentry.init({ - integrations: [Sentry.browserTracingIntegration()], -}); -``` +- Removed `SentryGlobalGraphQLFilter`. + Use the `SentryGlobalFilter` as a drop-in replacement. ### `@sentry/react` -```js -import * as Sentry from '@sentry/react'; - -Sentry.init({ - integrations: [ - // No react router - Sentry.browserTracingIntegration(), - // OR, if you are using react router, instead use one of the following: - Sentry.reactRouterV6BrowserTracingIntegration({ - useEffect, - useLocation, - useNavigationType, - createRoutesFromChildren, - matchRoutes, - stripBasename, - }), - Sentry.reactRouterV5BrowserTracingIntegration({ - history, - }), - Sentry.reactRouterV4BrowserTracingIntegration({ - history, - }), - Sentry.reactRouterV3BrowserTracingIntegration({ - history, - routes, - match, - }), - ], -}); -``` - -### `@sentry/vue` - -```js -import * as Sentry from '@sentry/vue'; - -Sentry.init({ - integrations: [ - Sentry.browserTracingIntegration({ - // pass router in, if applicable - router, - }), - ], -}); -``` +- The `wrapUseRoutes` method has been removed. + Depending on what version of react router you are using, use the `wrapUseRoutesV6` or `wrapUseRoutesV7` methods instead. -### `@sentry/angular` & `@sentry/angular-ivy` +- The `wrapCreateBrowserRouter` method has been removed. + Depending on what version of react router you are using, use the `wrapCreateBrowserRouterV6` or `wrapCreateBrowserRouterV7` methods instead. -```js -import * as Sentry from '@sentry/angular'; +### `@sentry/vue` -Sentry.init({ - integrations: [Sentry.browserTracingIntegration()], -}); +- The options `tracingOptions`, `trackComponents`, `timeout`, `hooks` have been removed everywhere except in the `tracingOptions` option of `vueIntegration()`. -// You still need to add the TraceService like before! -``` + These options should now be configured as follows: -### `@sentry/remix` + ```js + import * as Sentry from '@sentry/vue'; -```js -import * as Sentry from '@sentry/remix'; - -Sentry.init({ - integrations: [ - Sentry.browserTracingIntegration({ - useEffect, - useLocation, - useMatches, - }), - ], -}); -``` - -### `@sentry/nextjs`, `@sentry/astro`, `@sentry/sveltekit` - -Browser tracing is automatically set up for you in these packages. If you need to customize the options, you can do it -like this: - -```js -import * as Sentry from '@sentry/nextjs'; - -Sentry.init({ - integrations: [ - Sentry.browserTracingIntegration({ - // add custom options here - }), - ], -}); -``` - -### `@sentry/ember` - -Browser tracing is automatically set up for you. You can configure it as before through configuration. - -## Deprecated `transactionContext` passed to `tracesSampler` - -Instead of an `transactionContext` being passed to the `tracesSampler` callback, the callback will directly receive -`name` and `attributes` going forward. You can use these to make your sampling decisions, while `transactionContext` -will be removed in v8. Note that the `attributes` are only the attributes at span creation time, and some attributes may -only be set later during the span lifecycle (and thus not be available during sampling). - -## Deprecate `wrapRemixHandleError` in Remix SDK (since v7.100.0) - -This release deprecates `wrapRemixHandleError` in favor of using `sentryHandleError` from `@sentry/remix`. It can be -used as below: - -```typescript -// entry.server.ts - -export const handleError = Sentry.wrapHandleErrorWithSentry(() => { - // Custom handleError implementation -}); -``` - -## Deprecate using `getClient()` to check if the SDK was initialized - -In v8, `getClient()` will stop returning `undefined` if `Sentry.init()` was not called. For cases where this may be used -to check if Sentry was actually initialized, using `getClient()` will thus not work anymore. Instead, you should use the -new `Sentry.isInitialized()` utility to check this. - -## Deprecate `getCurrentHub()` - -In v8, you will no longer have a Hub, only Scopes as a concept. This also means that `getCurrentHub()` will eventually -be removed. - -Instead of `getCurrentHub()`, use the respective replacement API directly - see [Deprecate Hub](#deprecate-hub) for -details. - -## Deprecate class-based integrations - -In v7, integrations are classes and can be added as e.g. `integrations: [new Sentry.Integrations.ContextLines()]`. In -v8, integrations will not be classes anymore, but instead functions. Both the use as a class, as well as accessing -integrations from the `Integrations.XXX` hash, is deprecated in favor of using the new functional integrations - -- for example, `new Integrations.LinkedErrors()` becomes `linkedErrorsIntegration()`. - -The following list shows how integrations should be migrated: - -### List of integrations and their replacements - -| Old | New | Packages | -| ----------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `new BrowserTracing()` | `browserTracingIntegration()` | `@sentry/browser` | -| `new InboundFilters()` | `inboundFiltersIntegration()` | `@sentry/core`, `@sentry/browser`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge` | -| `new FunctionToString()` | `functionToStringIntegration()` | `@sentry/core`, `@sentry/browser`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge` | -| `new LinkedErrors()` | `linkedErrorsIntegration()` | `@sentry/core`, `@sentry/browser`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge` | -| `new ModuleMetadata()` | `moduleMetadataIntegration()` | `@sentry/core`, `@sentry/browser` | -| `new RequestData()` | `requestDataIntegration()` | `@sentry/core`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge` | -| `new Wasm() ` | `wasmIntegration()` | `@sentry/wasm` | -| `new Replay()` | `replayIntegration()` | `@sentry/browser` | -| `new ReplayCanvas()` | `replayCanvasIntegration()` | `@sentry/browser` | -| `new Feedback()` | `feedbackIntegration()` | `@sentry/browser` | -| `new CaptureConsole()` | `captureConsoleIntegration()` | `@sentry/integrations` | -| `new Debug()` | `debugIntegration()` | `@sentry/integrations` | -| `new Dedupe()` | `dedupeIntegration()` | `@sentry/browser`, `@sentry/integrations`, `@sentry/deno` | -| `new ExtraErrorData()` | `extraErrorDataIntegration()` | `@sentry/integrations` | -| `new ReportingObserver()` | `reportingObserverIntegration()` | `@sentry/integrations` | -| `new RewriteFrames()` | `rewriteFramesIntegration()` | `@sentry/integrations` | -| `new SessionTiming()` | `sessionTimingIntegration()` | `@sentry/integrations` | -| `new HttpClient()` | `httpClientIntegration()` | `@sentry/integrations` | -| `new ContextLines()` | `contextLinesIntegration()` | `@sentry/integrations`, `@sentry/node`, `@sentry/deno`, `@sentry/bun` | -| `new Breadcrumbs()` | `breadcrumbsIntegration()` | `@sentry/browser`, `@sentry/deno` | -| `new GlobalHandlers()` | `globalHandlersIntegration()` | `@sentry/browser` , `@sentry/deno` | -| `new HttpContext()` | `httpContextIntegration()` | `@sentry/browser` | -| `new TryCatch()` | `browserApiErrorsIntegration()` | `@sentry/browser`, `@sentry/deno` | -| `new VueIntegration()` | `vueIntegration()` | `@sentry/vue` | -| `new DenoContext()` | `denoContextIntegration()` | `@sentry/deno` | -| `new DenoCron()` | `denoCronIntegration()` | `@sentry/deno` | -| `new NormalizePaths()` | `normalizePathsIntegration()` | `@sentry/deno` | -| `new Console()` | `consoleIntegration()` | `@sentry/node` | -| `new Context()` | `nodeContextIntegration()` | `@sentry/node` | -| `new Modules()` | `modulesIntegration()` | `@sentry/node` | -| `new OnUncaughtException()` | `onUncaughtExceptionIntegration()` | `@sentry/node` | -| `new OnUnhandledRejection()` | `onUnhandledRejectionIntegration()` | `@sentry/node` | -| `new LocalVariables()` | `localVariablesIntegration()` | `@sentry/node` | -| `new Spotlight()` | `spotlightIntegration()` | `@sentry/node` | -| `new Anr()` | `anrIntegration()` | `@sentry/node` | -| `new Hapi()` | `hapiIntegration()` | `@sentry/node` | -| `new Undici()` | `nativeNodeFetchIntegration()` | `@sentry/node` | -| `new Http()` | `httpIntegration()` | `@sentry/node` | -| `new ProfilingIntegration()` | `nodeProfilingIntegration()` | `@sentry/profiling-node` | -| `new BrowserProfilingIntegration()` | `browserProfilingIntegration()` | `@sentry/browser` | - -## Deprecate `hub.bindClient()` and `makeMain()` - -Instead, either directly use `initAndBind()`, or the new APIs `setCurrentClient()` and `client.init()`. See -[Initializing the SDK in v8](./docs/v8-initializing.md) for more details. - -## Deprecate `Transaction` integration - -This pluggable integration from `@sentry/integrations` will be removed in v8. It was already undocumented and is not -necessary for the SDK to work as expected. - -## Changed integration interface - -In v8, integrations passed to a client will have an optional `setupOnce()` hook. Currently, this hook is always present, -but in v8 you will not be able to rely on this always existing anymore - any integration _may_ have a `setup` and/or a -`setupOnce` hook. Additionally, `setupOnce()` will not receive any arguments anymore. - -This should not affect most people, but in the case that you are manually calling `integration.setupOnce()` right now, -make sure to guard it's existence properly. - -## Deprecate `getIntegration()` and `getIntegrationById()` - -This deprecates `getIntegration()` on both the hub & the client, as well as `getIntegrationById()` on the baseclient. -Instead, use `getIntegrationByName()`. You can optionally pass an integration generic to make it easier to work with -typescript: - -```ts -const replay = getClient().getIntegrationByName('Replay'); -``` - -## Deprecate `Hub` - -The `Hub` has been a very important part of the Sentry SDK API up until now. Hubs were the SDK's "unit of concurrency" -to keep track of data across threads and to scope data to certain parts of your code. Because it is overly complicated -and confusing to power users, it is going to be replaced by a set of new APIs: the "new Scope API". - -`Scope`s have existed before in the SDK but we are now expanding on them because we have found them powerful enough to -fully cover the `Hub` API. - -If you are using the `Hub` right now, see the following table on how to migrate to the new API: - -| Old `Hub` API | New `Scope` API | -| ---------------------- | ------------------------------------------------------------------------------------ | -| `new Hub()` | `withScope()`, `withIsolationScope()` or `new Scope()` | -| hub.isOlderThan() | REMOVED - Was used to compare `Hub` instances, which are gonna be removed | -| hub.bindClient() | A combination of `scope.setClient()` and `client.init()` | -| hub.pushScope() | `Sentry.withScope()` | -| hub.popScope() | `Sentry.withScope()` | -| hub.withScope() | `Sentry.withScope()` | -| getClient() | `Sentry.getClient()` | -| getScope() | `Sentry.getCurrentScope()` to get the currently active scope | -| getIsolationScope() | `Sentry.getIsolationScope()` | -| getStack() | REMOVED - The stack used to hold scopes. Scopes are used directly now | -| getStackTop() | REMOVED - The stack used to hold scopes. Scopes are used directly now | -| captureException() | `Sentry.captureException()` | -| captureMessage() | `Sentry.captureMessage()` | -| captureEvent() | `Sentry.captureEvent()` | -| lastEventId() | `Sentry.lastEventId()` | -| addBreadcrumb() | `Sentry.addBreadcrumb()` | -| setUser() | `Sentry.setUser()` | -| setTags() | `Sentry.setTags()` | -| setExtras() | `Sentry.setExtras()` | -| setTag() | `Sentry.setTag()` | -| setExtra() | `Sentry.setExtra()` | -| setContext() | `Sentry.setContext()` | -| configureScope() | REMOVED - Scopes are now the unit of concurrency | -| run() | `Sentry.withScope()` or `Sentry.withIsolationScope()` | -| getIntegration() | `client.getIntegration()` | -| startTransaction() | `Sentry.startSpan()`, `Sentry.startInactiveSpan()` or `Sentry.startSpanManual()` | -| traceHeaders() | REMOVED - The closest equivalent is now `spanToTraceHeader(getActiveSpan())` | -| captureSession() | `Sentry.captureSession()` | -| startSession() | `Sentry.startSession()` | -| endSession() | `Sentry.endSession()` | -| shouldSendDefaultPii() | REMOVED - The closest equivalent is `Sentry.getClient().getOptions().sendDefaultPii` | - -The `Hub` constructor is also deprecated and will be removed in the next major version. If you are creating Hubs for -multi-client use like so: - -```ts -// OLD -const hub = new Hub(); -hub.bindClient(client); -makeMain(hub); -``` - -instead initialize the client as follows: - -```ts -// NEW -Sentry.withIsolationScope(() => { - Sentry.setCurrentClient(client); - client.init(); -}); -``` - -If you are using the Hub to capture events like so: - -```ts -// OLD -const client = new Client(); -const hub = new Hub(client); -hub.captureException(); -``` - -instead capture isolated events as follows: - -```ts -// NEW -const client = new Client(); -const scope = new Scope(); -scope.setClient(client); -scope.captureException(); -``` - -## Deprecate `client.setupIntegrations()` - -Instead, use the new `client.init()` method. You should probably not use this directly and instead use `Sentry.init()`, -which calls this under the hood. But if you have a special use case that requires that, you can call `client.init()` -instead now. - -## Deprecate `scope.getSpan()` and `scope.setSpan()` - -Instead, you can get the currently active span via `Sentry.getActiveSpan()`. Setting a span on the scope happens -automatically when you use the new performance APIs `startSpan()` and `startSpanManual()`. - -## Deprecate `scope.getTransaction()` and `getActiveTransaction()` - -Instead, you should not rely on the active transaction, but just use `startSpan()` APIs, which handle this for you. - -## Deprecate arguments for `startSpan()` APIs - -In v8, the API to start a new span will be reduced from the currently available options. Going forward, only these -argument will be passable to `startSpan()`, `startSpanManual()` and `startInactiveSpan()`: - -- `name` -- `attributes` -- `origin` -- `op` -- `startTime` -- `scope` - -## Deprecate `startTransaction()` & `span.startChild()` - -In v8, the old performance API `startTransaction()` (and `hub.startTransaction()`), as well as `span.startChild()`, will -be removed. Instead, use the new performance APIs: - -- `startSpan()` -- `startSpanManual()` -- `startInactiveSpan()` - -You can [read more about the new performance APIs here](./docs/v8-new-performance-apis.md). - -## Deprecate variations of `Sentry.continueTrace()` - -The version of `Sentry.continueTrace()` which does not take a callback argument will be removed in favor of the version -that does. Additionally, the callback argument will not receive an argument with the next major version. - -Use `Sentry.continueTrace()` as follows: - -```ts -app.get('/your-route', req => { - Sentry.withIsolationScope(isolationScope => { - Sentry.continueTrace( - { - sentryTrace: req.headers.get('sentry-trace'), - baggage: req.headers.get('baggage'), - }, - () => { - // All events recorded in this callback will be associated with the incoming trace. For example: - Sentry.startSpan({ name: '/my-route' }, async () => { - await doExpensiveWork(); - }); - }, - ); + Sentry.init({ + integrations: [ + Sentry.vueIntegration({ + tracingOptions: { + trackComponents: true, + timeout: 1000, + hooks: ['mount', 'update', 'unmount'], + }, + }), + ], }); -}); -``` + ``` -## Deprecated fields on `Span` and `Transaction` +- 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). -In v8, the Span class is heavily reworked. The following properties & methods are thus deprecated: +- The option `stateTransformer` in `createSentryPiniaPlugin()` now receives the full state from all stores as its parameter. + The top-level keys of the state object are the store IDs. -- `span.toContext()`: Access the fields directly instead. -- `span.updateWithContext(newSpanContext)`: Update the fields directly instead. -- `span.setName(newName)`: Use `span.updateName(newName)` instead. -- `span.toTraceparent()`: use `spanToTraceHeader(span)` util instead. -- `span.getTraceContext()`: Use `spanToTraceContext(span)` utility function instead. -- `span.sampled`: Use `span.isRecording()` instead. -- `span.spanId`: Use `span.spanContext().spanId` instead. -- `span.parentSpanId`: Use `spanToJSON(span).parent_span_id` instead. -- `span.traceId`: Use `span.spanContext().traceId` instead. -- `span.name`: Use `spanToJSON(span).description` instead. -- `span.description`: Use `spanToJSON(span).description` instead. -- `span.getDynamicSamplingContext`: Use `spanToBaggageHeader(span)` utility function instead. -- `span.tags`: Set tags on the surrounding scope instead, or use attributes. -- `span.data`: Use `spanToJSON(span).data` instead. -- `span.setTag()`: Use `span.setAttribute()` instead or set tags on the surrounding scope. -- `span.setData()`: Use `span.setAttribute()` instead. -- `span.instrumenter` This field was removed and will be replaced internally. -- `span.transaction`: Use `getRootSpan` utility function instead. -- `span.spanRecorder`: Span recording will be handled internally by the SDK. -- `span.status`: Use `.setStatus` to set or update and `spanToJSON()` to read the span status. -- `span.op`: Use `startSpan` functions to set, `setAttribute()` to update and `spanToJSON` to read the span operation. -- `span.isSuccess`: Use `spanToJSON(span).status === 'ok'` instead. -- `transaction.setMetadata()`: Use attributes instead, or set data on the scope. -- `transaction.metadata`: Use attributes instead, or set data on the scope. -- `transaction.setContext()`: Set context on the surrounding scope instead. -- `transaction.setMeasurement()`: Use `Sentry.setMeasurement()` instead. In v8, setting measurements will be limited to - the currently active root span. -- `transaction.setName()`: Set the name with `.updateName()` and the source with `.setAttribute()` instead. -- `span.startTimestamp`: use `spanToJSON(span).start_timestamp` instead. You cannot update this anymore in v8. -- `span.endTimestamp`: use `spanToJSON(span).timestamp` instead. You cannot update this anymore in v8. You can pass a - custom end timestamp to `span.end(endTimestamp)`. +### `@sentry/nuxt` -## Deprecate `pushScope` & `popScope` in favor of `withScope` +- The `tracingOptions` option in `Sentry.init()` was removed in favor of passing the `vueIntegration()` to `Sentry.init({ integrations: [...] })` and setting `tracingOptions` there. -Instead of manually pushing/popping a scope, you should use `Sentry.withScope(callback: (scope: Scope))` instead. +- The option `stateTransformer` in the `piniaIntegration` now receives the full state from all stores as its parameter. + The top-level keys of the state object are the store IDs. -## Deprecate `configureScope` in favor of using `getCurrentScope()` +### `@sentry/vue` and `@sentry/nuxt` -Instead of updating the scope in a callback via `configureScope()`, you should access it via `getCurrentScope()` and -configure it directly: +- When component tracking is enabled, "update" spans are no longer created by default. -```js -Sentry.getCurrentScope().setTag('xx', 'yy'); -``` - -## Deprecate `addGlobalEventProcessor` in favor of `addEventProcessor` - -Instead of using `addGlobalEventProcessor`, you should use `addEventProcessor` which does not add the event processor -globally, but to the current client. - -For the vast majority of cases, the behavior of these should be the same. Only in the case where you have multiple -clients will this differ - but you'll likely want to add event processors per-client then anyhow, not globally. - -In v8, we will remove the global event processors overall, as that allows us to avoid keeping global state that is not -necessary. + Add an `"update"` item to the `tracingOptions.hooks` option via the `vueIntegration()` to restore this behavior. -## Deprecate `extractTraceParentData` export from `@sentry/core` & downstream packages - -Instead, import this directly from `@sentry/utils`. + ```ts + Sentry.init({ + integrations: [ + Sentry.vueIntegration({ + tracingOptions: { + trackComponents: true, + hooks: [ + 'mount', + 'update', // add this line to re-enable update spans + 'unmount', + ], + }, + }), + ], + }); + ``` -Generally, in most cases you should probably use `continueTrace` instead, which abstracts this away from you and handles -scope propagation for you. +### `@sentry/remix` -## Deprecate `timestampWithMs` export - #7878 +- The `autoInstrumentRemix` option was removed. + The SDK now always behaves as if the option were set to `true`. -The `timestampWithMs` util is deprecated in favor of using `timestampInSeconds`. +### `@sentry/sveltekit` -## `addTracingExtensions` replaces `addExtensionMethods` (since 7.46.0) +- 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. -Since the deprecation of `@sentry/tracing`, tracing extensions are now added by calling `addTracingExtensions` which is -exported from all framework SDKs. +### `@sentry/core` -```js -// Before -import * as Sentry from '@sentry/browser'; -import { addExtensionMethods } from '@sentry/tracing'; +- A `sampleRand` field on `PropagationContext` is now required. This is relevant if you used `scope.setPropagationContext(...)` -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, -}); +- The `DEFAULT_USER_INCLUDES` constant has been removed. There is no replacement. -addExtensionMethods(); +- The `BAGGAGE_HEADER_NAME` export has been removed. Use a `"baggage"` string constant directly instead. -// After -import * as Sentry from '@sentry/browser'; +- The `extractRequestData` method has been removed. Manually extract relevant data of request objects instead. -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, -}); +- The `addRequestDataToEvent` method has been removed. Use `httpRequestToRequestData` instead and put the resulting object directly on `event.request`. -Sentry.addTracingExtensions(); -``` +- The `addNormalizedRequestDataToEvent` method has been removed. Use `httpRequestToRequestData` instead and put the resulting object directly on `event.request`. -## Remove requirement for `@sentry/tracing` package (since 7.46.0) +- The `generatePropagationContext()` method was removed. + Use `generateTraceId()` directly. -With `7.46.0` you no longer require the `@sentry/tracing` package to use tracing and performance monitoring with the -Sentry JavaScript SDKs. The `@sentry/tracing` package will be removed in a future major release, but can still be used -in the meantime. +- 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. -#### Browser: +- The `initSessionFlusher` method on the `ServerRuntimeClient` was removed without replacements. + Any mechanisms creating sessions will flush themselves. -```js -// Before -import * as Sentry from '@sentry/browser'; -import { BrowserTracing } from '@sentry/tracing'; +- The `IntegrationClass` type was removed. + Instead, use `Integration` or `IntegrationFn`. -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, - integrations: [new BrowserTracing()], -}); +- The following exports have been removed without replacement: -// After -import * as Sentry from '@sentry/browser'; + - `getNumberOfUrlSegments` + - `validSeverityLevels` + - `makeFifoCache` + - `arrayify` + - `flatten` + - `urlEncode` + - `getDomElement` + - `memoBuilder` + - `extractPathForTransaction` + - `_browserPerformanceTimeOriginMode` + - `addTracingHeadersToFetchRequest` + - `SessionFlusher` -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, - integrations: [new Sentry.BrowserTracing()], -}); -``` +- The following types have been removed without replacement: -#### Node: + - `Request` + `RequestEventData` + - `TransactionNamingScheme` + - `RequestDataIntegrationOptions` + - `SessionFlusherLike` + - `RequestSession` + - `RequestSessionStatus` -```js -// Before -const Sentry = require('@sentry/node'); -require('@sentry/tracing'); +### `@sentry/opentelemetry` -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, -}); +- Removed `getPropagationContextFromSpan` without replacement. +- Removed `generateSpanContextForPropagationContext` without replacement. -// After -const Sentry = require('@sentry/node'); +#### Other/Internal Changes -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, - integrations: [ - // Automatically instrument Node.js libraries and frameworks - ...Sentry.autoDiscoverNodePerformanceMonitoringIntegrations(), - ], -}); -``` +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. -**Note:** If you imported `stripUrlQueryAndFragment` from `@sentry/tracing`, you'll need to import it from -`@sentry/utils`, once you remove `@sentry/tracing`. +- `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. -## Replay options changed (since 7.35.0) - #6645 +## 5. Build Changes -Some options for replay have been deprecated in favor of new APIs. See -[Replay Migration docs](./docs/migration/replay.md#upgrading-replay-from-7340-to-7350---6645) for details. +- The CJS code for the SDK now only contains compatibility statements for CJS/ESM in modules that have default exports: -## Renaming of Next.js wrapper methods (since 7.31.0) - #6790 + ```js + Object.defineProperty(exports, '__esModule', { value: true }); + ``` -We updated the names of the functions to wrap data fetchers and API routes to better reflect what they are doing. The -old methods can still be used but are deprecated and will be removed in the next major update of the SDK. + Let us know if this is causing issues in your setup by opening an issue on GitHub. -Following function names were updated: +- `@sentry/deno` is no longer published on the `deno.land` registry so you'll need to import the SDK from npm: -- `withSentryAPI` was renamed to `wrapApiHandlerWithSentry` -- `withSentryGetServerSideProps` was renamed to `wrapGetServerSidePropsWithSentry` -- `withSentryGetStaticProps` was renamed to `wrapGetStaticPropsWithSentry` -- `withSentryServerSideGetInitialProps` was renamed to `wrapGetInitialPropsWithSentry` -- `withSentryServerSideAppGetInitialProps` was renamed to `wrapAppGetInitialPropsWithSentry` -- `withSentryServerSideDocumentGetInitialProps` was renamed to `wrapDocumentGetInitialPropsWithSentry` -- `withSentryServerSideErrorGetInitialProps` was renamed to `wrapErrorGetInitialPropsWithSentry` + ```javascript + import * as Sentry from 'npm:@sentry/deno'; -## Deprecated `tracingOrigins` (since 7.19.0) - #6176 + Sentry.init({ + dsn: '__DSN__', + // ... + }); + ``` -The `tracingOrigins` option is deprecated in favor of using `shouldCreateSpanForRequest` and `tracePropagationTargets`. +## 6. Type Changes -## Deprecate `componentTrackingPreprocessor` in Svelte SDK (since 7.16.0) - #5936 +- `Scope` usages now always expect `Scope` instances -This release adds the `withSentryConfig` feature to the Svelte SDK. It replaces the now deprecated Svelte -`componentTrackingPreprocessor` which will be removed in the next major release. +- `Client` usages now always expect `BaseClient` instances. + The abstract `Client` class was removed. + Client classes now have to extend from `BaseClient`. -## Deprecate `getGlobalObject` in `@sentry/utils` (since 7.16.0) - #5949 +These changes should not affect most users unless you relied on passing things with a similar shape to internal methods. -This is no longer used. +In v8, interfaces have been exported from `@sentry/types`, while implementations have been exported from other packages. -## Deprecate @sentry/hub (since 7.15.0) - #5823 +## No Version Support Timeline -This release deprecates `@sentry/hub` and all of it's exports. All of the `@sentry/hub` exports have moved to -`@sentry/core`. `@sentry/hub` will be removed in the next major release. +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. -# Upgrading Sentry Replay (beta, 7.24.0) +Additionally, we hold ourselves accountable to any security issues, meaning that if any vulnerabilities are found, we will in almost all cases backport them. -For details on upgrading Replay in its beta phase, please view the -[dedicated Replay MIGRATION docs](./docs/migration/replay.md). +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. diff --git a/docs/migration/v7-to-v8.md b/docs/migration/v7-to-v8.md new file mode 100644 index 000000000000..a863713b6757 --- /dev/null +++ b/docs/migration/v7-to-v8.md @@ -0,0 +1,1937 @@ +# Upgrading from 7.x to 8.x + +The main goal of version 8 is to improve our performance monitoring APIs, integrations API, and ESM support. This +version is breaking because we removed deprecated APIs, restructured npm package contents, and introduced new +dependencies on OpenTelemetry. Below we will outline the steps you need to take to tackle to deprecated methods. + +Before updating to `8.x` of the SDK, we recommend upgrading to the latest version of `7.x`. You can then follow +[these steps](#deprecations-in-7x) remove deprecated methods in `7.x` before upgrading to `8.x`. + +The v8 version of the JavaScript SDK requires a self-hosted version of Sentry 24.4.2 (for user feedback screenshots) or +higher. Lower versions may continue to work, but may not support all features (e.g. the new user feedback APIs). + +## 1. Version Support changes: + +**Node.js**: We now officially support Node 14.18+ for our CJS package, and Node 18.19.1+ for our ESM package. This +applies to `@sentry/node` and all of our node-based server-side sdks (`@sentry/nextjs`, `@sentry/serverless`, etc.). We +no longer test against Node 8, 10, or 12 and cannot guarantee that the SDK will work as expected on these versions. + +**Browser**: Our browser SDKs (`@sentry/browser`, `@sentry/react`, `@sentry/vue`, etc.) now require ES2018+ +compatibility plus support for +[`globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis). This means +that we no longer support IE11 (end of an era). This also means that the Browser SDK requires the fetch API to be +available in the environment. + +New minimum supported browsers: + +- Chrome 71 +- Edge 79 +- Safari 12.1, iOS Safari 12.2 +- Firefox 65 +- Opera 58 +- Samsung Internet 10 + +For IE11 support please transpile your code to ES5 using babel or similar and add required polyfills. + +**React**: The Next.js SDK now supports React 16+ + +**Next.js**: The Next.js SDK now supports Next.js 13.2.0+ + +**Express**: Complex router setups are only properly parametrized in Node 16+. + +## 2. Package removal + +We've removed the following packages: + +- [@sentry/hub](#sentryhub) +- [@sentry/tracing](#sentrytracing) +- [@sentry/integrations](#sentryintegrations) +- [@sentry/serverless](#sentryserverless) +- [@sentry/replay](#sentryreplay) + +#### @sentry/hub + +`@sentry/hub` has been removed and will no longer be published. All of the `@sentry/hub` exports have moved to +`@sentry/core`. + +#### @sentry/tracing + +`@sentry/tracing` has been removed and will no longer be published. See [below](#4-removal-of-deprecated-apis) for more +details. + +For Browser SDKs you can import `browserTracingIntegration` from the SDK directly: + +```js +// v7 +import * as Sentry from '@sentry/browser'; +import { BrowserTracing } from '@sentry/tracing'; + +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, + integrations: [new BrowserTracing()], +}); +``` + +```js +// v8 +import * as Sentry from '@sentry/browser'; + +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, + integrations: [Sentry.browserTracingIntegration()], +}); +``` + +If you don't want to use `browserTracingIntegration` but still manually start spans, you can now use +`Sentry.registerSpanErrorInstrumentation()` to setup handlers for span instrumentation. +`registerSpanErrorInstrumentation` replaces the `addExtensionMethods` method from `@sentry/tracing`. + +```js +// v7 +import * as Sentry from '@sentry/browser'; +import '@sentry/tracing'; + +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, +}); +``` + +```js +// v8 +import * as Sentry from '@sentry/browser'; + +Sentry.registerSpanErrorInstrumentation(); + +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, +}); +``` + +For Node SDKs you no longer need the side effect import, you can remove all references to `@sentry/tracing`. + +```js +// v7 +const Sentry = require('@sentry/node'); +require('@sentry/tracing'); + +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, +}); +``` + +```js +// v8 +const Sentry = require('@sentry/node'); + +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, +}); +``` + +#### @sentry/integrations + +`@sentry/integrations` has been removed and will no longer be published. We moved pluggable integrations from their own +package (`@sentry/integrations`) to `@sentry/browser` and `@sentry/node`. in addition they are now functions instead of +classes. + +```js +// v7 +import { RewriteFrames } from '@sentry/integrations'; +``` + +```js +// v8 +import { rewriteFramesIntegration } from '@sentry/browser'; +``` + +Integrations that are now exported from `@sentry/browser` (or framework-specific packages like `@sentry/react`): + +- `httpClientIntegration` (`HTTPClient`) +- `contextLinesIntegration` (`ContextLines`) +- `reportingObserverIntegration` (`ReportingObserver`) + +Integrations that are now exported from `@sentry/node` and `@sentry/browser` (or framework-specific packages like +`@sentry/react`): + +- `captureConsoleIntegration` (`CaptureConsole`) +- `debugIntegration` (`Debug`) +- `extraErrorDataIntegration` (`ExtraErrorData`) +- `rewriteFramesIntegration` (`RewriteFrames`) +- `sessionTimingIntegration` (`SessionTiming`) +- `dedupeIntegration` (`Dedupe`) - _Note: enabled by default, not pluggable_ + +The `Transaction` integration has been removed from `@sentry/integrations`. There is no replacement API. + +#### @sentry/serverless + +`@sentry/serverless` has been removed and will no longer be published. The serverless package has been split into two +different packages, `@sentry/aws-serverless` and `@sentry/google-cloud-serverless`. + +The `@sentry/google-cloud-serverless` package has also been changed to only emit CJS builds because it can only +instrument CJS. ESM support will be re-added at a later date. + +In `@sentry/serverless` you had to use a namespace import to initialize the SDK. This has been removed so that you can +directly import from the SDK instead. + +```js +// v7 +const Sentry = require('@sentry/serverless'); + +Sentry.AWSLambda.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, +}); + +// v8 +const Sentry = require('@sentry/aws-serverless'); + +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, +}); +``` + +```js +// v7 +const Sentry = require('@sentry/serverless'); + +Sentry.GCPFunction.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, +}); + +// v8 +const Sentry = require('@sentry/google-cloud-serverless'); + +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, +}); +``` + +#### @sentry/replay + +`@sentry/replay` has been removed and will no longer be published. You can import replay functionality and the replay +integration directly from the Browser SDK or browser framework-specific packages like `@sentry/react`. + +```js +// v7 +import { Replay } from '@sentry/replay'; +``` + +```js +import { replayIntegration } from '@sentry/browser'; +``` + +## 3. Performance Monitoring Changes + +- [Initializing the SDK in v8](#initializing-the-node-sdk) +- [Performance Monitoring API](#performance-monitoring-api) +- [Performance Monitoring Integrations](#performance-monitoring-integrations) + +### Initializing the Node SDK + +If you are using `@sentry/node` or `@sentry/bun`, or a package that depends on it (`@sentry/nextjs`, `@sentry/remix`, +`@sentry/sveltekit`, `@sentry/`), you will need to initialize the SDK differently. The primary change is to ensure that +the SDK is initialized as early as possible. See [Initializing the SDK in v8](../v8-initializing.md) on what steps to +follow. + +For example with the Remix SDK, you should initialize the SDK at the top of your `entry.server.tsx` server entrypoint +before you do anything else. + +```js +// first import Sentry and initialize Sentry +import * as Sentry from '@sentry/remix'; + +Sentry.init({ + dsn: 'https://public@dsn.ingest.sentry.io/1337', + tracesSampleRate: 1, + tracePropagationTargets: ['example.org'], + // Disabling to test series of envelopes deterministically. + autoSessionTracking: false, +}); + +// then handle everything else +import type { EntryContext } from '@remix-run/node'; +import { RemixServer } from '@remix-run/react'; +import { renderToString } from 'react-dom/server'; + +export const handleError = Sentry.wrapRemixHandleError; +``` + +### Performance Monitoring API + +The APIs for Performance Monitoring in the SDK have been revamped to align with OpenTelemetry, an open standard for +tracing and metrics. This allows us to provide a more consistent and powerful API for performance monitoring, and adds +support for a variety of new integrations out of the box for our Node SDK. + +Instead of using `startTransaction` and `span.startChild`, you rely on new helper methods to create spans top level +helpers to create spans. + +```js +// Measure how long a callback takes, `startSpan` returns the value of the callback. +// The span will become the "active span" for the duration of the callback. +const value = Sentry.startSpan({ name: 'mySpan' }, span => { + span.setAttribute('key', 'value'); + return expensiveFunction(); +}); + +// `startSpan` works with async callbacks as well - just make sure to return a promise! +const value = await Sentry.startSpan({ name: 'mySpan' }, async span => { + span.setAttribute('key', 'value'); + return await expensiveFunction(); +}); + +// You can nest spans via more `startSpan` calls. +const value = Sentry.startSpan({ name: 'mySpan' }, span => { + span.setAttribute('key1', 'value1'); + + // `nestedSpan` becomes the child of `mySpan`. + return Sentry.startSpan({ name: 'nestedSpan' }, nestedSpan => { + nestedSpan.setAttribute('key2', 'value2'); + return expensiveFunction(); + }); +}); + +// You can also create an inactive span that does not take a callback. +// Useful when you need to pass a span reference into another closure (like measuring duration between hooks). +const span = Sentry.startInactiveSpan({ name: 'mySpan' }); + +// Use `startSpanManual` if you want to manually control when to end the span +// Useful when you need to hook into event emitters or similar. +function middleware(res, req, next) { + return Sentry.startSpanManual({ name: 'mySpan' }, span => { + res.on('finish', () => { + span.end(); + }); + return next(); + }); +} +``` + +You can [read more about the new performance APIs here](./v8-new-performance-apis.md). + +To accommodate these changes, we're removed the following APIs: + +- [`startTransaction` and `span.startChild`](#deprecate-starttransaction--spanstartchild) +- [Certain arguments in `startSpan` and `startTransaction`](#deprecate-arguments-for-startspan-apis) +- [`scope.getSpan` and `scope.setSpan`](#deprecate-scopegetspan-and-scopesetspan) +- [Variations of `continueTrace`](#deprecate-variations-of-sentrycontinuetrace) + +We've also removed a variety of [top level fields](#deprecated-fields-on-span-and-transaction) on the `span` class. + +### Performance Monitoring Integrations + +As we added support for OpenTelemetry, we have expanded the automatic instrumentation for our Node.js SDK. We are adding +support for frameworks like Fastify, Nest.js, and Hapi, and expanding support for databases like Prisma and MongoDB via +Mongoose. + +We now support the following integrations out of the box without extra configuration: + +- `httpIntegration`: Automatically instruments Node `http` and `https` standard libraries +- `nativeNodeFetchIntegration`: Automatically instruments top level fetch and undici +- `expressIntegration`: Automatically instruments Express.js +- `fastifyIntegration`: Automatically instruments Fastify +- `hapiIntegration`: Automatically instruments Hapi +- `graphqlIntegration`: Automatically instruments GraphQL +- `mongoIntegration`: Automatically instruments MongoDB +- `mongooseIntegration`: Automatically instruments Mongoose +- `mysqlIntegration`: Automatically instruments MySQL +- `mysql2Integration`: Automatically instruments MySQL2 +- `redisIntegration`: Automatically instruments Redis (supported clients: ioredis) +- `nestIntegration`: Automatically instruments Nest.js +- `postgresIntegration`: Automatically instruments PostgreSQL +- `prismaIntegration`: Automatically instruments Prisma + +To make sure these integrations work properly you'll have to change how you +[initialize the SDK](./docs/v8-initializing.md) + +## 4. Removal of deprecated APIs + +- [General](#general) +- [Browser SDK](#browser-sdk-browser-react-vue-angular-ember-etc) +- [Server-side SDKs (Node, Deno, Bun)](#server-side-sdks-node-deno-bun-etc) +- [Next.js SDK](#nextjs-sdk) +- [SvelteKit SDK](#sveltekit-sdk) +- [Astro SDK](#astro-sdk) +- [AWS Serverless SDK](#aws-serverless-sdk) +- [Ember SDK](#ember-sdk) +- [Svelte SDK](#svelte-sdk) +- [React SDK](#react-sdk) + +### General + +Removed top-level exports: `tracingOrigins`, `MetricsAggregator`, `metricsAggregatorIntegration`, `Severity`, +`Sentry.configureScope`, `Span`, `spanStatusfromHttpCode`, `makeMain`, `pushScope`, `popScope`, +`addGlobalEventProcessor`, `timestampWithMs`, `addExtensionMethods`, `addGlobalEventProcessor`, `getActiveTransaction` + +Removed `@sentry/utils` exports: `timestampWithMs`, `addOrUpdateIntegration`, `tracingContextFromHeaders`, `walk` + +- [Deprecation of `Hub` and `getCurrentHub()`](#deprecate-hub) +- [Removal of class-based integrations](#removal-of-class-based-integrations) +- [`tracingOrigins` option replaced with `tracePropagationTargets`](#tracingorigins-has-been-replaced-by-tracepropagationtargets) +- [Removal of `MetricsAggregator` and `metricsAggregatorIntegration`](#removal-of-the-metricsaggregator-integration-class-and-metricsaggregatorintegration) +- [Removal of `Severity` Enum](#removal-of-severity-enum) +- [Removal of `Sentry.configureScope` method](#removal-of-sentryconfigurescope-method) +- [Removal of `Span` class export from SDK packages](#removal-of-span-class-export-from-sdk-packages) +- [Removal of `spanStatusfromHttpCode` in favour of `getSpanStatusFromHttpCode`](#removal-of-spanstatusfromhttpcode-in-favour-of-getspanstatusfromhttpcode) +- [Removal of `addGlobalEventProcessor` in favour of `addEventProcessor`](#removal-of-addglobaleventprocessor-in-favour-of-addeventprocessor) +- [Remove `void` from transport return types](#removal-of-void-from-transport-return-types) +- [Remove `addGlobalEventProcessor` in favor of `addEventProcessor`](#removal-of-addglobaleventprocessor-in-favor-of-addeventprocessor) + +#### Deprecation of `Hub` and `getCurrentHub()` + +The `Hub` has been a very important part of the Sentry SDK API up until now. Hubs were the SDK's "unit of concurrency" +to keep track of data across threads and to scope data to certain parts of your code. Because it is overly complicated +and confusing to power users, it is going to be replaced by a set of new APIs: the "new Scope API". For now `Hub` and +`getCurrentHub` are still available, but it will be removed in the next major version. + +See [Deprecate Hub](#deprecate-hub) for details on how to replace existing usage of the Hub APIs. + +The `hub.bindClient` and `makeMain` methods have been removed entirely, see +[initializing the SDK in v8](./v8-initializing.md) for details how to work around this. + +#### Removal of class-based integrations + +In v7, integrations are classes and can be added as e.g. `integrations: [new Sentry.Replay()]`. In v8, integrations will +not be classes anymore, but instead functions. Both the use as a class, as well as accessing integrations from the +`Integrations.XXX` hash, is deprecated in favor of using the new functional integrations. For example, +`new Integrations.LinkedErrors()` becomes `linkedErrorsIntegration()`. + +For docs on the new integration interface, see [below](#changed-integration-interface). + +For a list of integrations and their replacements, see [below](#list-of-integrations-and-their-replacements). + +The `getIntegration()` and `getIntegrationById()` have been removed entirely, see +[below](#deprecate-getintegration-and-getintegrationbyid). + +```js +// v7 +const replay = Sentry.getIntegration(Replay); +``` + +```js +// v8 +const replay = getClient().getIntegrationByName('Replay'); +``` + +#### `framesToPop` applies to parsed frames + +Error with `framesToPop` property will have the specified number of frames removed from the top of the stack. This +changes compared to the v7 where the property `framesToPop` was used to remove top n lines from the stack string. + +#### `tracingOrigins` has been replaced by `tracePropagationTargets` + +`tracingOrigins` is now removed in favor of the `tracePropagationTargets` option. The `tracePropagationTargets` option +should be set in the `Sentry.init()` options, or in your custom `Client`s option if you create them. We've also updated +the behavior of the `tracePropagationTargets` option for Browser SDKs, see +[below](#updated-behaviour-of-tracepropagationtargets-in-the-browser-http-tracing-headers--cors) for more details. + +For example for the Browser SDKs: + +```ts +// v7 +Sentry.init({ + dsn: '__DSN__', + integrations: [new Sentry.BrowserTracing({ tracingOrigins: ['localhost', 'example.com'] })], +}); +``` + +```ts +// v8 +Sentry.init({ + dsn: '__DSN__', + integrations: [Sentry.browserTracingIntegration()], + tracePropagationTargets: ['localhost', 'example.com'], +}); +``` + +#### Removal of the `MetricsAggregator` integration class and `metricsAggregatorIntegration` + +The SDKs now support metrics features without any additional configuration. + +```ts +// v7 - Server (Node/Deno/Bun) +Sentry.init({ + dsn: '__DSN__', + _experiments: { + metricsAggregator: true, + }, +}); + +// v7 - Browser +Sentry.init({ + dsn: '__DSN__', + integrations: [Sentry.metricsAggregatorIntegration()], +}); +``` + +```ts +// v8 +Sentry.init({ + dsn: '__DSN__', +}); +``` + +#### Removal of Severity Enum + +In v7 we deprecated the `Severity` enum in favor of using the `SeverityLevel` type as this helps save bundle size, and +this has been removed in v8. You should now use the `SeverityLevel` type directly. + +```js +// v7 +import { Severity, SeverityLevel } from '@sentry/types'; + +const levelA = Severity.error; + +const levelB: SeverityLevel = "error" +``` + +```js +// v8 +import { SeverityLevel } from '@sentry/types'; + +const levelA = "error" as SeverityLevel; + +const levelB: SeverityLevel = "error" +``` + +#### Removal of `Sentry.configureScope` method + +The top level `Sentry.configureScope` function has been removed. Instead, you should use the `Sentry.getCurrentScope()` +to access and mutate the current scope. + +```js +// v7 +Sentry.configureScope(scope => { + scope.setTag('key', 'value'); +}); +``` + +```js +// v8 +Sentry.getCurrentScope().setTag('key', 'value'); +``` + +#### Removal of `Span` class export from SDK packages + +In v8, we are no longer exporting the `Span` class from SDK packages (e.g. `@sentry/browser` or `@sentry/node`). +Internally, this class is now called `SentrySpan`, and it is no longer meant to be used by users directly. + +#### Removal of `spanStatusfromHttpCode` in favour of `getSpanStatusFromHttpCode` + +In v8, we are removing the `spanStatusfromHttpCode` function in favor of `getSpanStatusFromHttpCode`. + +```js +// v7 +const spanStatus = spanStatusfromHttpCode(200); +``` + +```js +// v8 +const spanStatus = getSpanStatusFromHttpCode(200); +``` + +#### Removal of `addGlobalEventProcessor` in favour of `addEventProcessor` + +In v8, we are removing the `addGlobalEventProcessor` function in favor of `addEventProcessor`. + +```js +// v7 +addGlobalEventProcessor(event => { + delete event.extra; + return event; +}); +``` + +```js +// v8 +Sentry.getGlobalScope().addEventProcessor(event => { + delete event.extra; + return event; +}); +``` + +#### Removal of `void` from transport return types + +The `send` method on the `Transport` interface now always requires a `TransportMakeRequestResponse` to be returned in +the promise. This means that the `void` return type is no longer allowed. + +```ts +// v7 +interface Transport { + send(event: Event): Promise; +} +``` + +```ts +// v8 +interface Transport { + send(event: Event): Promise; +} +``` + +#### Removal of `addGlobalEventProcessor` in favor of `addEventProcessor` + +In v8, we are removing the `addGlobalEventProcessor` function in favor of `addEventProcessor`. + +```js +// v7 +addGlobalEventProcessor(event => { + delete event.extra; + return event; +}); +``` + +```js +// v8 +addEventProcessor(event => { + delete event.extra; + return event; +}); +``` + +#### Removal of `Sentry.Handlers.trpcMiddleware()` in favor of `Sentry.trpcMiddleware()` + +The Sentry tRPC middleware got moved from `Sentry.Handlers.trpcMiddleware()` to `Sentry.trpcMiddleware()`. Functionally +they are the same: + +#### Removal of `Sentry.Handlers.requestHandler()`, `Sentry.Handlers.tracingHandler()` and `Sentry.Handlers.errorHandler()` + +For Express and Connect you previously had to use `Sentry.Handlers.requestHandler()`, +`Sentry.Handlers.tracingHandler()`, and `Sentry.Handlers.errorHandler()` to add Sentry instrumentation to your app. In +8.x, you only need to use the framework specific error handler (e.g `Sentry.setupExpressErrorHandler(app)`), you can +remove all other handlers. + +```js +// v7 +import * as Sentry from '@sentry/node'; +Sentry.Handlers.trpcMiddleware(); +``` + +```js +// v8 +import * as Sentry from '@sentry/node'; +Sentry.trpcMiddleware(); +``` + +### Browser SDK (Browser, React, Vue, Angular, Ember, etc.) + +Removed top-level exports: `Offline`, `makeXHRTransport`, `BrowserTracing`, `wrap` + +- [Removal of the `BrowserTracing` integration](#removal-of-the-browsertracing-integration) +- [Removal of Offline integration](#removal-of-the-offline-integration) +- [Removal of `makeXHRTransport` transport](#removal-of-makexhrtransport-transport) +- [Removal of `wrap` method](#removal-of-wrap-method) +- [Removal of `@sentry/angular-ivy` package](#removal-of-sentryangular-ivy-package) +- [Removal of `@sentry/replay` package](#removal-of-sentryreplay-package) + +#### Removal of the `BrowserTracing` integration + +The `BrowserTracing` integration, together with the custom routing instrumentations passed to it, are deprecated in v8. +Instead, you should use `Sentry.browserTracingIntegration()`. See examples +[below](#deprecated-browsertracing-integration) + +#### Removal of `interactionsSampleRate` in `browserTracingIntegration` options + +The `interactionsSampleRate` option that could be passed to `browserTracingIntegration` or `new BrowserTracing()` was +removed in v8, due to the option being redundant and in favour of bundle size minimization. + +It's important to note that this sample rate only ever was applied when collecting INP (Interaction To Next Paint) +values. You most likely don't need to replace this option. Furthermore, INP values are already sampled by the +[`tracesSampleRate` SDK option](https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sampler), like +any regular span. At the time of writing, INP value collection does not deplete your span or transaction quota. + +If you used `interactionsSampleRate` before, and still want to reduce INP value collection, we recommend using the +`tracesSampler` SDK option instead: + +```javascript +// v7 +Sentry.init({ + integrations: [new BrowserTracing({ interactionsSampleRate: 0.1 })], +}); +``` + +```javascript +// v8 - please read the text above, you most likely don't need this :) +Sentry.init({ + tracesSampler: (ctx) => { + if (ctx.attributes?['sentry.op']?.startsWith('ui.interaction')) { + return 0.1; + } + return 0.5; + } +}) +``` + +#### Removal of the `Offline` integration + +The `Offline` integration has been removed in favor of the +[offline transport wrapper](http://docs.sentry.io/platforms/javascript/configuration/transports/#offline-caching). + +#### Removal of `makeXHRTransport` transport + +The `makeXHRTransport` transport has been removed. Only `makeFetchTransport` is available now. This means that the +Sentry SDK requires the fetch API to be available in the environment. + +#### Removal of `wrap` method + +The `wrap` method has been removed. There is no replacement API. + +#### Removal of `@sentry/angular-ivy` package + +The `@sentry/angular-ivy` package has been removed. The `@sentry/angular` package now supports Ivy by default and +requires at least Angular 14. If you are using Angular 13 or lower, we suggest upgrading your Angular version before +migrating to v8. If you can't upgrade your Angular version to at least Angular 14, you can also continue using the +`@sentry/angular-ivy@7` SDK. However, v7 of the SDKs will no longer be fully supported going forward. + +#### Removal of `@sentry/replay` package + +You can import from `@sentry/browser` (or from a respective SDK package like `@sentry/react` or `@sentry/vue`). + +### Server-side SDKs (Node, Deno, Bun, etc.) + +Removed top-level exports: `enableAnrDetection`, `Anr`, `deepReadDirSync`, `runWithAsyncContext` + +- [Removal of `enableAnrDetection` and `Anr` class](#removal-of-enableanrdetection-and-anr-class) +- [Removal of `deepReadDirSync` method](#removal-of-deepreaddirsync-method) +- [Removal of `runWithAsyncContext` method](#removal-of-runwithasynccontext-method) +- [Removal of `Apollo` integration](#removal-of-apollo-integration) + +#### Removal of `enableAnrDetection` and `Anr` class + +The `enableAnrDetection` and `Anr` class have been removed. See the +[docs](https://docs.sentry.io/platforms/node/configuration/application-not-responding/) for more details. PR: + +#### Removal of `deepReadDirSync` method + +The `deepReadDirSync` method has been removed. There is no replacement API. + +#### Removal of `runWithAsyncContext` method + +The `runWithAsyncContext` method has been removed in favour of `Sentry.withIsolationScope`. + +```js +// before (v7) +Sentry.runWithAsyncContext(() => { + // Your code here... +}); + +// after (v8) +Sentry.withIsolationScope(() => { + // Your code here... +}); +``` + +#### Removal of Apollo integration + +The Apollo integration has been removed in `8.x` as `8.x` automatically adds GraphQL support via `graphqlIntegration` +which is automatically enabled. + +```js +// before (v7) +Sentry.init({ + integrations: [Sentry.integrations.Apollo()], +}); + +// after (v8) +Sentry.init({}); +``` + +### Next.js SDK + +Removed top-level exports: `withSentryApi`, `withSentryAPI`, `withSentryGetServerSideProps`, `withSentryGetStaticProps`, +`withSentryServerSideGetInitialProps`, `withSentryServerSideAppGetInitialProps`, +`withSentryServerSideDocumentGetInitialProps`, `withSentryServerSideErrorGetInitialProps`, `nextRouterInstrumentation`, +`IS_BUILD`, `isBuild` + +- [Removal of deprecated API in `@sentry/nextjs`](#removal-of-deprecated-api-in-sentrynextjs) +- [Updated minimum compatible Next.js version to `13.2.0`](#updated-minimum-compatible-nextjs-version-to-1320) +- [Merging of the Sentry Webpack Plugin options and SDK Build options](#merging-of-the-sentry-webpack-plugin-options-and-sdk-build-options) +- [Removal of the `sentry` property in your Next.js options (next.config.js)](#removal-of-the-sentry-property-in-your-nextjs-options-nextconfigjs) +- [Updated the `@sentry/webpack-plugin` dependency to version 2](#updated-the-sentry-webpack-plugin-dependency-to-version-2) + +#### Removal of deprecated API in `@sentry/nextjs` + +The following previously deprecated API has been removed from the `@sentry/nextjs` package: + +- `withSentryApi` (Replacement: `wrapApiHandlerWithSentry`) +- `withSentryAPI` (Replacement: `wrapApiHandlerWithSentry`) +- `withSentryGetServerSideProps` (Replacement: `wrapGetServerSidePropsWithSentry`) +- `withSentryGetStaticProps` (Replacement: `wrapGetStaticPropsWithSentry`) +- `withSentryServerSideGetInitialProps` (Replacement: `wrapGetInitialPropsWithSentry`) +- `withSentryServerSideAppGetInitialProps` (Replacement: `wrapAppGetInitialPropsWithSentry`) +- `withSentryServerSideDocumentGetInitialProps` (Replacement: `wrapDocumentGetInitialPropsWithSentry`) +- `withSentryServerSideErrorGetInitialProps` was renamed to `wrapErrorGetInitialPropsWithSentry` +- `nextRouterInstrumentation` (Replaced by using `browserTracingIntegration`) +- `IS_BUILD` +- `isBuild` + +#### Updated minimum compatible Next.js version to `13.2.0` + +The minimum version of Next.js compatible with the Sentry Next.js SDK has been raised to `13.2.0`. Older versions may +exhibit bugs or unexpected behaviour. + +#### Merging of the Sentry Webpack Plugin options and SDK Build options + +With version 8 of the Sentry Next.js SDK, `withSentryConfig` will no longer accept 3 arguments. The second argument +(holding options for the Sentry Webpack plugin) and the third argument (holding options for SDK build-time +configuration) should now be passed as one: + +```ts +// OLD +const nextConfig = { + // Your Next.js options... +}; + +module.exports = withSentryConfig( + nextConfig, + { + // Your Sentry Webpack Plugin Options... + }, + { + // Your Sentry SDK options... + }, +); + +// NEW +const nextConfig = { + // Your Next.js options... +}; + +module.exports = withSentryConfig(nextConfig, { + // Your Sentry Webpack Plugin Options... + // AND your Sentry SDK options... +}); +``` + +#### Removal of the `sentry` property in your Next.js options (next.config.js) + +With version 8 of the Sentry Next.js SDK, the SDK will no longer support passing Next.js options with a `sentry` +property to `withSentryConfig`. Please use the second argument of `withSentryConfig` to configure the SDK instead: + +```ts +// v7 +const nextConfig = { + // Your Next.js options... + + sentry: { + // Your Sentry SDK options... + }, +}; + +module.exports = withSentryConfig(nextConfig, { + // Your Sentry Webpack Plugin Options... +}); +``` + +```ts +// v8 +const nextConfig = { + // Your Next.js options... +}; + +module.exports = withSentryConfig(nextConfig, { + // Your Sentry Webpack Plugin Options... + // AND your Sentry SDK options... +}); +``` + +The reason for this change is to have one consistent way of defining the SDK options. We hope that this change will +reduce confusion when setting up the SDK, with the upside that the explicit option is properly typed and will therefore +have code completion. + +#### Updated the `@sentry/webpack-plugin` dependency to version 2 + +We bumped the internal usage of `@sentry/webpack-plugin` to a new major version. This comes with multiple upsides like a +simpler configuration interface and the use of new state of the art Debug ID technology. Debug IDs will simplify the +setup for source maps in Sentry and will not require you to match stack frame paths to uploaded artifacts anymore. + +To see the new options, check out the docs at https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/, +or look at the TypeScript type definitions of `withSentryConfig`. + +#### Updated the recommended way of calling `Sentry.init()` + +Version 8 of the Next.js SDK will require an additional `instrumentation.ts` file to execute the `sentry.server.config.js|ts` and `sentry.edge.config.js|ts` modules to initialize the SDK for the server-side. +The `instrumentation.ts` file is a Next.js native API called [instrumentation hook](https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation). + +To start using the Next.js instrumentation hook, follow these steps: + +1. First, enable the Next.js instrumentation hook by setting the [`experimental.instrumentationHook`](https://nextjs.org/docs/app/api-reference/next-config-js/instrumentationHook) to true in your `next.config.js`. (This step is no longer required with Next.js 15) + + ```JavaScript {filename:next.config.js} {2-4} + module.exports = { + experimental: { + instrumentationHook: true, // Not required on Next.js 15+ + }, + } + ``` + +2. Next, create a `instrumentation.ts|js` file in the root directory of your project (or in the src folder if you have have one). + +3. Now, export a register function from the `instrumentation.ts|js` file and import your `sentry.server.config.js|ts` and `sentry.edge.config.js|ts` modules: + + ```JavaScript {filename:instrumentation.js} + import * as Sentry from '@sentry/nextjs'; + + export async function register() { + if (process.env.NEXT_RUNTIME === 'nodejs') { + await import('./sentry.server.config'); + } + + if (process.env.NEXT_RUNTIME === 'edge') { + await import('./sentry.edge.config'); + } + } + ``` + + Note that you can initialize the SDK differently depending on which server runtime is being used. + +If you are using a +[Next.js custom server](https://nextjs.org/docs/pages/building-your-application/configuring/custom-server), the +`instrumentation.ts` hook is not called by Next.js so you need to manually call it yourself from within your server +code. It is recommended to do so as early as possible in your application lifecycle. + +**Why are we making this change?** The very simple reason is that Next.js requires us to set up OpenTelemetry +instrumentation inside the `register` function of the instrumentation hook. Looking a little bit further into the +future, we also would like the Sentry SDK to be compatible with [Turbopack](https://turbo.build/pack), which is gonna be +the bundler that Next.js will be using instead of Webpack. The SDK in its previous version depended heavily on Webpack +in order to inject the `sentry.(server|edge).config.ts` files into the server-side code. Because this will not be +possible in the future, we are doing ourselves a favor and doing things the way Next.js intends us to do them - +hopefully reducing bugs and jank. + +#### Removal of `transpileClientSDK` + +Since we are dropping support for Internet Explorer 11 and other other older browser versions, we are also removing the +`transpileClientSDK` option from the Next.js SDK. If you need to support these browser versions, please configure +Webpack and Next.js to down-compile the SDK. + +### Astro SDK + +- [Removal of `trackHeaders` option for Astro middleware](#removal-of-trackheaders-option-for-astro-middleware) + +#### Removal of `trackHeaders` option for Astro middleware + +Instead of opting-in via the middleware config, you can configure if headers should be captured via +`requestDataIntegration` options, which defaults to `true` but can be disabled like this: + +```js +Sentry.init({ + integrations: [ + Sentry.requestDataIntegration({ + include: { + headers: false, + }, + }), + ], +}); +``` + +### SvelteKit SDK + +- [Breaking `sentrySvelteKit()` changes](#breaking-sentrysveltekit-changes) + +#### Breaking `sentrySvelteKit()` changes + +We upgraded the `@sentry/vite-plugin` from version 0.x to 2.x. This package is internally used by the +`@sentry/sveltekit` SDK. With this change, resolving uploaded source maps should work out of the box much more often +than before +([more information](https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/artifact-bundles/)). + +To allow future upgrades of the Vite plugin without breaking stable and public APIs in `sentrySvelteKit`, we modified +the `sourceMapsUploadOptions` to remove the hard dependency on the API of the plugin. While you previously could specify +all [version 0.x Vite plugin options](https://www.npmjs.com/package/@sentry/vite-plugin/v/0.6.1), we now reduced them to +a subset of [2.x options](https://www.npmjs.com/package/@sentry/vite-plugin/v/2.14.2#options). All of these options are +optional just like before but here's an example of using the new options. + +```js +// v7 +sentrySvelteKit({ + sourceMapsUploadOptions: { + org: process.env.SENTRY_ORG, + project: process.env.SENTRY_PROJECT, + authToken: process.env.SENTRY_AUTH_TOKEN, + release: '1.0.1', + injectRelease: true, + include: ['./build/*/**/*'], + ignore: ['**/build/client/**/*'] + }, +}), +``` + +```js +// v8 +sentrySvelteKit({ + sourceMapsUploadOptions: { + org: process.env.SENTRY_ORG, + project: process.env.SENTRY_PROJECT, + authToken: process.env.SENTRY_AUTH_TOKEN, + release: { + name: '1.0.1', + inject: true + }, + sourcemaps: { + assets: ['./build/*/**/*'], + ignore: ['**/build/client/**/*'], + filesToDeleteAfterUpload: ['./build/**/*.map'] + }, + }, +}), +``` + +In the future, we might add additional [options](https://www.npmjs.com/package/@sentry/vite-plugin/v/2.14.2#options) +from the Vite plugin but if you would like to specify some of them directly, you can do this by passing in an +`unstable_sentryVitePluginOptions` object: + +```js +sentrySvelteKit({ + sourceMapsUploadOptions: { + // ... + release: { + name: '1.0.1', + }, + unstable_sentryVitePluginOptions: { + release: { + setCommits: { + auto: true + } + } + } + }, +}), +``` + +Important: we DO NOT guarantee stability of `unstable_sentryVitePluginOptions`. They can be removed or updated at any +time, including breaking changes within the same major version of the SDK. + +### AWS Serverless SDK + +- [Removal of `rethrowAfterCapture` option](#removal-of-rethrowaftercapture-option) + +#### Removal of `rethrowAfterCapture` option + +In `v6.17.2` the `rethrowAfterCapture` option to `wrapHandler` was deprecated. In `v8` it has been removed. There is no +replacement API. + +### Ember SDK + +Removed top-level exports: `InitSentryForEmber`, `StartTransactionFunction` + +- [Removal of `InitSentryForEmber` export](#removal-of-initsentryforember-export) +- [Updated Ember Dependencies](#updated-ember-dependencies) + +#### Removal of `InitSentryForEmber` export + +The `InitSentryForEmber` export has been removed. Instead, you should use the `Sentry.init` method to initialize the +SDK. + +#### Updated Ember Dependencies + +The following dependencies that the SDK uses have been bumped to a more recent version: + +- `ember-auto-import` is bumped to `^2.4.3` +- `ember-cli-babel` is bumped to `^8.2.0` +- `ember-cli-typescript` is bumped to `^5.3.0` + +### Svelte SDK + +Removed top-level exports: `componentTrackingPreprocessor` + +#### Removal of `componentTrackingPreprocessor` export + +The `componentTrackingPreprocessor` export has been removed. You should instead use `withSentryConfig` to configure +component tracking. + +```js +// v7 - svelte.config.js +import { componentTrackingPreprocessor } from '@sentry/svelte'; + +const config = { + preprocess: [ + componentTrackingPreprocessor(), + // ... + ], + // ... +}; + +export default config; +``` + +```js +// v8 - svelte.config.js +import { withSentryConfig } from "@sentry/svelte"; + +const config = { + // Your svelte config + compilerOptions: {...}, +}; + +export default withSentryConfig(config); +``` + +### React SDK + +#### Updated error types to be `unknown` instead of `Error`. + +In v8, we are changing the `ErrorBoundary` error types returned from `onError`, `onReset`, `onUnmount`, and +`beforeCapture`. to be `unknown` instead of `Error`. This more accurately matches behaviour of `componentDidCatch`, the +lifecycle method the Sentry `ErrorBoundary` component uses. + +As per the [React docs on error boundaries](https://react.dev/reference/react/Component#componentdidcatch): + +> error: The `error` that was thrown. In practice, it will usually be an instance of `Error` but this is not guaranteed +> because JavaScript allows to throw any value, including strings or even `null`. + +This means you will have to use `instanceof Error` or similar to explicitly make sure that the error thrown was an +instance of `Error`. + +The Sentry SDK maintainers also went ahead and made a PR to update the +[TypeScript definitions of `componentDidCatch`](https://github.com/DefinitelyTyped/DefinitelyTyped/pull/69434) for the +React package - this will be released with React 20. + +### Gatsby SDK + +#### Removal of Gatsby Initialization via plugin options + +In v8, we are removing the ability to initialize the Gatsby SDK via plugin options. Instead, you should create a +`sentry.config.js` file in the root of your project and initialize the SDK there. + +```js +// v7 - gatsby-config.js +module.exports = { + // ... + plugins: [ + { + resolve: '@sentry/gatsby', + options: { + dsn: process.env.SENTRY_DSN, + }, + }, + // ... + ], +}; +``` + +```js +// v8 - gatsby-config.js +module.exports = { + // ... + plugins: [ + { + resolve: '@sentry/gatsby', + }, + // ... + ], +}; + +// v8 - sentry.config.js +import * as Sentry from '@sentry/gatsby'; + +Sentry.init({ + dsn: '__PUBLIC_DSN__', +}); +``` + +We've also added `enableClientWebpackPlugin` which allows you to enable or disable the `@sentry/webpack-plugin` in the +client-side build. By default, it is enabled. + +```js +// v8 - gatsby-config.js +module.exports = { + // ... + plugins: [ + { + resolve: '@sentry/gatsby', + options: { + enableClientWebpackPlugin: false, + }, + }, + // ... + ], +}; +``` + +#### Automatic adding of `browserTracingIntegration` for Gatsby + +The Gatsby SDK no longer adds the `browserTracingIntegration` automatically. If you want to enable tracing in the +browser, you need to add it manually. Make sure to also configured a `tracePropagationTargets` value. + +```js +// v7 - gatsby-config.js +module.exports = { + // ... + plugins: [ + { + resolve: '@sentry/gatsby', + options: { + tracesSampleRate: 1.0, + }, + }, + // ... + ], +}; +``` + +```js +// v8 - gatsby-config.js +module.exports = { + // ... + plugins: [ + { + resolve: '@sentry/gatsby', + }, + // ... + ], +}; + +// v8 - sentry.config.js +import * as Sentry from '@sentry/gatsby'; + +Sentry.init({ + dsn: '__PUBLIC_DSN__', + integrations: [Sentry.browserTracingIntegration()], + + // Set tracesSampleRate to 1.0 to capture 100% + // of transactions for performance monitoring. + // We recommend adjusting this value in production + tracesSampleRate: 1.0, + + // Set `tracePropagationTargets` to control for which URLs distributed tracing should be enabled + tracePropagationTargets: ['localhost', /^https:\/\/yourserver\.io\/api/], +}); +``` + +## 5. Behaviour Changes + +- [Updated behaviour of `tracePropagationTargets` in the browser](#updated-behaviour-of-tracepropagationtargets-in-the-browser-http-tracing-headers--cors) +- [Updated behaviour of `extraErrorDataIntegration`](#extraerrordataintegration-changes) +- [Updated behaviour of `transactionContext` passed to `tracesSampler`](#transactioncontext-no-longer-passed-to-tracessampler) +- [Updated behaviour of `getClient()`](#getclient-always-returns-a-client) +- [Updated behaviour of the SDK in combination with `onUncaughtException` handlers in Node.js](#behaviour-in-combination-with-onuncaughtexception-handlers-in-node.js) +- [Updated expected return value for `captureException()`, `captureMessage()` and `captureEvent` methods on Clients](#updated-expected-return-value-for-captureexception-capturemessage-and-captureevent-methods-on-clients) +- [Removal of Client-Side health check transaction filters](#removal-of-client-side-health-check-transaction-filters) +- [Change of Replay default options (`unblock` and `unmask`)](#change-of-replay-default-options-unblock-and-unmask) +- [Angular Tracing Decorator renaming](#angular-tracing-decorator-renaming) + +#### Updated behaviour of `tracePropagationTargets` in the browser (HTTP tracing headers & CORS) + +We updated the behaviour of the SDKs when no `tracePropagationTargets` option was defined. As a reminder, you can +provide a list of strings or RegExes that will be matched against URLs to tell the SDK, to which outgoing requests +tracing HTTP headers should be attached to. These tracing headers are used for distributed tracing. + +Previously, on the browser, when `tracePropagationTargets` were not defined, they defaulted to the following: +`['localhost', /^\/(?!\/)/]`. This meant that all request targets to that had "localhost" in the URL, or started with a +`/` were equipped with tracing headers. This default was chosen to prevent CORS errors in your browser applications. +However, this default had a few flaws. + +Going forward, when the `tracePropagationTargets` option is not set, tracing headers will be attached to all outgoing +requests on the same origin. For example, if you're on `https://example.com/` and you send a request to +`https://example.com/api`, the request will be traced (ie. will have trace headers attached). Requests to +`https://api.example.com/` will not, because it is on a different origin. The same goes for all applications running on +`localhost`. + +When you provide a `tracePropagationTargets` option, all of the entries you defined will now be matched be matched +against the full URL of the outgoing request. Previously, it was only matched against what you called request APIs with. +For example, if you made a request like `fetch("/api/posts")`, the provided `tracePropagationTargets` were only compared +against `"/api/posts"`. Going forward they will be matched against the entire URL, for example, if you were on the page +`https://example.com/` and you made the same request, it would be matched against `"https://example.com/api/posts"`. + +But that is not all. Because it would be annoying having to create matchers for the entire URL, if the request is a +same-origin request, we also match the `tracePropagationTargets` against the resolved `pathname` of the request. +Meaning, a matcher like `/^\/api/` would match a request call like `fetch('/api/posts')`, or +`fetch('https://same-origin.com/api/posts')` but not `fetch('https://different-origin.com/api/posts')`. + +#### `extraErrorDataIntegration` changes + +The `extraErrorDataIntegration` integration now looks at +[`error.cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause) by +default. + +#### `transactionContext` no longer passed to `tracesSampler` + +Instead of an `transactionContext` being passed to the `tracesSampler` callback, the callback will directly receive +`name` and `attributes` going forward. Note that the `attributes` are only the attributes at span creation time, and +some attributes may only be set later during the span lifecycle (and thus not be available during sampling). + +#### `getClient()` always returns a client + +`getClient()` now always returns a client if `Sentry.init()` was called. For cases where this may be used to check if +Sentry was actually initialized, using `getClient()` will thus not work anymore. Instead, you should use the new +`Sentry.isInitialized()` utility to check this. + +#### Behaviour in combination with `onUncaughtException` handlers in Node.js + +Previously the SDK exited the process by default, even though additional `onUncaughtException` may have been registered, +that would have prevented the process from exiting. You could opt out of this behaviour by setting the +`exitEvenIfOtherHandlersAreRegistered: false` in the `onUncaughtExceptionIntegration` options. Up until now the value +for this option defaulted to `true`. + +Going forward, the default value for `exitEvenIfOtherHandlersAreRegistered` will be `false`, meaning that the SDK will +not exit your process when you have registered other `onUncaughtException` handlers. + +#### Updated expected return value for `captureException()`, `captureMessage()` and `captureEvent` methods on Clients + +The `Client` interface now expects implementations to always return a string representing the generated event ID for the +`captureException()`, `captureMessage()`, `captureEvent()` methods. Previously `undefined` was a valid return value. + +#### Removal of Client-Side health check transaction filters + +The SDK no longer filters out health check transactions by default. Instead, they are sent to Sentry but still dropped +by the Sentry backend by default. You can disable dropping them in your Sentry project settings. If you still want to +drop specific transactions within the SDK you can either use the `ignoreTransactions` SDK option. + +#### Change of Replay default options (`unblock` and `unmask`) + +The Replay options `unblock` and `unmask` now have `[]` as default value. This means that if you want to use these +options, you have to explicitly set them like this: + +```js +Sentry.init({ + integrations: [ + Sentry.replayIntegration({ + unblock: ['.sentry-unblock, [data-sentry-unblock]'], + unmask: ['.sentry-unmask, [data-sentry-unmask]'], + }), + ], +}); +``` + +#### Angular Tracing Decorator renaming + +The usage of `TraceClassDecorator` and the `TraceMethodDecorator` already implies that those are decorators. The word +`Decorator` is now removed from the names to avoid multiple mentioning. + +Additionally, the `TraceClass` and `TraceMethod` decorators accept an optional `name` parameter to set the transaction +name. This was added because Angular minifies class and method names, and you might want to set a more descriptive name. +If nothing provided, the name defaults to `'unnamed'`. + +```js +// v7 +@Sentry.TraceClassDecorator() +export class HeaderComponent { + @Sentry.TraceMethodDecorator() + ngOnChanges(changes: SimpleChanges) {} +} +``` + +```js +// v8 +@Sentry.TraceClass({ name: 'HeaderComponent' }) +export class HeaderComponent { + @Sentry.TraceMethod({ name: 'ngOnChanges' }) + ngOnChanges(changes: SimpleChanges) {} +} +``` + +## 6. Build Changes + +We now provide a proper ESM output of the SDK. There have also been some other build changes under the hood. One side +effect of this is that importing Sentry as a default import does not work anymore. Note that this was never supported +(even on v7) and this was never intended to work (and also not documented anywhere). However, it seems that for some +configuration combinations, it was still possible to do `import Sentry from '@sentry/browser'`. This is not possible +anymore in v8. Please use `import * as Sentry from '@sentry/browser'` instead. + +# Upgrading Sentry Feedback (beta, 7.x to 8.0) + +For details on upgrading Feedback from the beta 7.x to the release 8.x version, please view the +[dedicated Feedback MIGRATION docs](./feedback.md). + +--- + +# Deprecations in 7.x + +You can use the **Experimental** [@sentry/migr8](https://www.npmjs.com/package/@sentry/migr8) to automatically update +your SDK usage and fix most deprecations. This requires Node 18+. + +```bash +npx @sentry/migr8@latest +``` + +This will let you select which updates to run, and automatically update your code. Make sure to still review all code +changes! + +## Deprecated `BrowserTracing` integration + +The `BrowserTracing` integration, together with the custom routing instrumentations passed to it, are deprecated in v8. +Instead, you should use `Sentry.browserTracingIntegration()`. + +Package-specific browser tracing integrations are available directly. In most cases, there is a single integration +provided for each package, which will make sure to set up performance tracing correctly for the given SDK. For react, we +provide multiple integrations to cover different router integrations: + +### `@sentry/browser`, `@sentry/svelte`, `@sentry/gatsby` + +```js +import * as Sentry from '@sentry/browser'; + +Sentry.init({ + integrations: [Sentry.browserTracingIntegration()], +}); +``` + +### `@sentry/react` + +```js +import * as Sentry from '@sentry/react'; + +Sentry.init({ + integrations: [ + // No react router + Sentry.browserTracingIntegration(), + // OR, if you are using react router, instead use one of the following: + Sentry.reactRouterV6BrowserTracingIntegration({ + useEffect, + useLocation, + useNavigationType, + createRoutesFromChildren, + matchRoutes, + stripBasename, + }), + Sentry.reactRouterV5BrowserTracingIntegration({ + history, + }), + Sentry.reactRouterV4BrowserTracingIntegration({ + history, + }), + Sentry.reactRouterV3BrowserTracingIntegration({ + history, + routes, + match, + }), + ], +}); +``` + +### `@sentry/vue` + +```js +import * as Sentry from '@sentry/vue'; + +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration({ + // pass router in, if applicable + router, + }), + ], +}); +``` + +### `@sentry/angular` & `@sentry/angular-ivy` + +```js +import * as Sentry from '@sentry/angular'; + +Sentry.init({ + integrations: [Sentry.browserTracingIntegration()], +}); + +// You still need to add the TraceService like before! +``` + +### `@sentry/remix` + +```js +import * as Sentry from '@sentry/remix'; + +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration({ + useEffect, + useLocation, + useMatches, + }), + ], +}); +``` + +### `@sentry/nextjs`, `@sentry/astro`, `@sentry/sveltekit` + +Browser tracing is automatically set up for you in these packages. If you need to customize the options, you can do it +like this: + +```js +import * as Sentry from '@sentry/nextjs'; + +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration({ + // add custom options here + }), + ], +}); +``` + +### `@sentry/ember` + +Browser tracing is automatically set up for you. You can configure it as before through configuration. + +## Deprecated `transactionContext` passed to `tracesSampler` + +Instead of an `transactionContext` being passed to the `tracesSampler` callback, the callback will directly receive +`name` and `attributes` going forward. You can use these to make your sampling decisions, while `transactionContext` +will be removed in v8. Note that the `attributes` are only the attributes at span creation time, and some attributes may +only be set later during the span lifecycle (and thus not be available during sampling). + +## Deprecate `wrapRemixHandleError` in Remix SDK (since v7.100.0) + +This release deprecates `wrapRemixHandleError` in favor of using `sentryHandleError` from `@sentry/remix`. It can be +used as below: + +```typescript +// entry.server.ts + +export const handleError = Sentry.wrapHandleErrorWithSentry(() => { + // Custom handleError implementation +}); +``` + +## Deprecate using `getClient()` to check if the SDK was initialized + +In v8, `getClient()` will stop returning `undefined` if `Sentry.init()` was not called. For cases where this may be used +to check if Sentry was actually initialized, using `getClient()` will thus not work anymore. Instead, you should use the +new `Sentry.isInitialized()` utility to check this. + +## Deprecate `getCurrentHub()` + +In v8, you will no longer have a Hub, only Scopes as a concept. This also means that `getCurrentHub()` will eventually +be removed. + +Instead of `getCurrentHub()`, use the respective replacement API directly - see [Deprecate Hub](#deprecate-hub) for +details. + +## Deprecate class-based integrations + +In v7, integrations are classes and can be added as e.g. `integrations: [new Sentry.Integrations.ContextLines()]`. In +v8, integrations will not be classes anymore, but instead functions. Both the use as a class, as well as accessing +integrations from the `Integrations.XXX` hash, is deprecated in favor of using the new functional integrations + +- for example, `new Integrations.LinkedErrors()` becomes `linkedErrorsIntegration()`. + +The following list shows how integrations should be migrated: + +### List of integrations and their replacements + +| Old | New | Packages | +| ----------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `new BrowserTracing()` | `browserTracingIntegration()` | `@sentry/browser` | +| `new InboundFilters()` | `inboundFiltersIntegration()` | `@sentry/core`, `@sentry/browser`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge` | +| `new FunctionToString()` | `functionToStringIntegration()` | `@sentry/core`, `@sentry/browser`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge` | +| `new LinkedErrors()` | `linkedErrorsIntegration()` | `@sentry/core`, `@sentry/browser`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge` | +| `new ModuleMetadata()` | `moduleMetadataIntegration()` | `@sentry/core`, `@sentry/browser` | +| `new RequestData()` | `requestDataIntegration()` | `@sentry/core`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge` | +| `new Wasm() ` | `wasmIntegration()` | `@sentry/wasm` | +| `new Replay()` | `replayIntegration()` | `@sentry/browser` | +| `new ReplayCanvas()` | `replayCanvasIntegration()` | `@sentry/browser` | +| `new Feedback()` | `feedbackIntegration()` | `@sentry/browser` | +| `new CaptureConsole()` | `captureConsoleIntegration()` | `@sentry/integrations` | +| `new Debug()` | `debugIntegration()` | `@sentry/integrations` | +| `new Dedupe()` | `dedupeIntegration()` | `@sentry/browser`, `@sentry/integrations`, `@sentry/deno` | +| `new ExtraErrorData()` | `extraErrorDataIntegration()` | `@sentry/integrations` | +| `new ReportingObserver()` | `reportingObserverIntegration()` | `@sentry/integrations` | +| `new RewriteFrames()` | `rewriteFramesIntegration()` | `@sentry/integrations` | +| `new SessionTiming()` | `sessionTimingIntegration()` | `@sentry/integrations` | +| `new HttpClient()` | `httpClientIntegration()` | `@sentry/integrations` | +| `new ContextLines()` | `contextLinesIntegration()` | `@sentry/integrations`, `@sentry/node`, `@sentry/deno`, `@sentry/bun` | +| `new Breadcrumbs()` | `breadcrumbsIntegration()` | `@sentry/browser`, `@sentry/deno` | +| `new GlobalHandlers()` | `globalHandlersIntegration()` | `@sentry/browser` , `@sentry/deno` | +| `new HttpContext()` | `httpContextIntegration()` | `@sentry/browser` | +| `new TryCatch()` | `browserApiErrorsIntegration()` | `@sentry/browser`, `@sentry/deno` | +| `new VueIntegration()` | `vueIntegration()` | `@sentry/vue` | +| `new DenoContext()` | `denoContextIntegration()` | `@sentry/deno` | +| `new DenoCron()` | `denoCronIntegration()` | `@sentry/deno` | +| `new NormalizePaths()` | `normalizePathsIntegration()` | `@sentry/deno` | +| `new Console()` | `consoleIntegration()` | `@sentry/node` | +| `new Context()` | `nodeContextIntegration()` | `@sentry/node` | +| `new Modules()` | `modulesIntegration()` | `@sentry/node` | +| `new OnUncaughtException()` | `onUncaughtExceptionIntegration()` | `@sentry/node` | +| `new OnUnhandledRejection()` | `onUnhandledRejectionIntegration()` | `@sentry/node` | +| `new LocalVariables()` | `localVariablesIntegration()` | `@sentry/node` | +| `new Spotlight()` | `spotlightIntegration()` | `@sentry/node` | +| `new Anr()` | `anrIntegration()` | `@sentry/node` | +| `new Hapi()` | `hapiIntegration()` | `@sentry/node` | +| `new Undici()` | `nativeNodeFetchIntegration()` | `@sentry/node` | +| `new Http()` | `httpIntegration()` | `@sentry/node` | +| `new ProfilingIntegration()` | `nodeProfilingIntegration()` | `@sentry/profiling-node` | +| `new BrowserProfilingIntegration()` | `browserProfilingIntegration()` | `@sentry/browser` | + +## Deprecate `hub.bindClient()` and `makeMain()` + +Instead, either directly use `initAndBind()`, or the new APIs `setCurrentClient()` and `client.init()`. See +[Initializing the SDK in v8](../v8-initializing.md) for more details. + +## Deprecate `Transaction` integration + +This pluggable integration from `@sentry/integrations` will be removed in v8. It was already undocumented and is not +necessary for the SDK to work as expected. + +## Changed integration interface + +In v8, integrations passed to a client will have an optional `setupOnce()` hook. Currently, this hook is always present, +but in v8 you will not be able to rely on this always existing anymore - any integration _may_ have a `setup` and/or a +`setupOnce` hook. Additionally, `setupOnce()` will not receive any arguments anymore. + +This should not affect most people, but in the case that you are manually calling `integration.setupOnce()` right now, +make sure to guard it's existence properly. + +## Deprecate `getIntegration()` and `getIntegrationById()` + +This deprecates `getIntegration()` on both the hub & the client, as well as `getIntegrationById()` on the baseclient. +Instead, use `getIntegrationByName()`. You can optionally pass an integration generic to make it easier to work with +typescript: + +```ts +const replay = getClient().getIntegrationByName('Replay'); +``` + +## Deprecate `Hub` + +The `Hub` has been a very important part of the Sentry SDK API up until now. Hubs were the SDK's "unit of concurrency" +to keep track of data across threads and to scope data to certain parts of your code. Because it is overly complicated +and confusing to power users, it is going to be replaced by a set of new APIs: the "new Scope API". + +`Scope`s have existed before in the SDK but we are now expanding on them because we have found them powerful enough to +fully cover the `Hub` API. + +If you are using the `Hub` right now, see the following table on how to migrate to the new API: + +| Old `Hub` API | New `Scope` API | +| ---------------------- | ------------------------------------------------------------------------------------ | +| `new Hub()` | `withScope()`, `withIsolationScope()` or `new Scope()` | +| hub.isOlderThan() | REMOVED - Was used to compare `Hub` instances, which are gonna be removed | +| hub.bindClient() | A combination of `scope.setClient()` and `client.init()` | +| hub.pushScope() | `Sentry.withScope()` | +| hub.popScope() | `Sentry.withScope()` | +| hub.withScope() | `Sentry.withScope()` | +| getClient() | `Sentry.getClient()` | +| getScope() | `Sentry.getCurrentScope()` to get the currently active scope | +| getIsolationScope() | `Sentry.getIsolationScope()` | +| getStack() | REMOVED - The stack used to hold scopes. Scopes are used directly now | +| getStackTop() | REMOVED - The stack used to hold scopes. Scopes are used directly now | +| captureException() | `Sentry.captureException()` | +| captureMessage() | `Sentry.captureMessage()` | +| captureEvent() | `Sentry.captureEvent()` | +| lastEventId() | `Sentry.lastEventId()` | +| addBreadcrumb() | `Sentry.addBreadcrumb()` | +| setUser() | `Sentry.setUser()` | +| setTags() | `Sentry.setTags()` | +| setExtras() | `Sentry.setExtras()` | +| setTag() | `Sentry.setTag()` | +| setExtra() | `Sentry.setExtra()` | +| setContext() | `Sentry.setContext()` | +| configureScope() | REMOVED - Scopes are now the unit of concurrency | +| run() | `Sentry.withScope()` or `Sentry.withIsolationScope()` | +| getIntegration() | `client.getIntegration()` | +| startTransaction() | `Sentry.startSpan()`, `Sentry.startInactiveSpan()` or `Sentry.startSpanManual()` | +| traceHeaders() | REMOVED - The closest equivalent is now `spanToTraceHeader(getActiveSpan())` | +| captureSession() | `Sentry.captureSession()` | +| startSession() | `Sentry.startSession()` | +| endSession() | `Sentry.endSession()` | +| shouldSendDefaultPii() | REMOVED - The closest equivalent is `Sentry.getClient().getOptions().sendDefaultPii` | + +The `Hub` constructor is also deprecated and will be removed in the next major version. If you are creating Hubs for +multi-client use like so: + +```ts +// OLD +const hub = new Hub(); +hub.bindClient(client); +makeMain(hub); +``` + +instead initialize the client as follows: + +```ts +// NEW +Sentry.withIsolationScope(() => { + Sentry.setCurrentClient(client); + client.init(); +}); +``` + +If you are using the Hub to capture events like so: + +```ts +// OLD +const client = new Client(); +const hub = new Hub(client); +hub.captureException(); +``` + +instead capture isolated events as follows: + +```ts +// NEW +const client = new Client(); +const scope = new Scope(); +scope.setClient(client); +scope.captureException(); +``` + +## Deprecate `client.setupIntegrations()` + +Instead, use the new `client.init()` method. You should probably not use this directly and instead use `Sentry.init()`, +which calls this under the hood. But if you have a special use case that requires that, you can call `client.init()` +instead now. + +## Deprecate `scope.getSpan()` and `scope.setSpan()` + +Instead, you can get the currently active span via `Sentry.getActiveSpan()`. Setting a span on the scope happens +automatically when you use the new performance APIs `startSpan()` and `startSpanManual()`. + +## Deprecate `scope.getTransaction()` and `getActiveTransaction()` + +Instead, you should not rely on the active transaction, but just use `startSpan()` APIs, which handle this for you. + +## Deprecate arguments for `startSpan()` APIs + +In v8, the API to start a new span will be reduced from the currently available options. Going forward, only these +argument will be passable to `startSpan()`, `startSpanManual()` and `startInactiveSpan()`: + +- `name` +- `attributes` +- `origin` +- `op` +- `startTime` +- `scope` + +## Deprecate `startTransaction()` & `span.startChild()` + +In v8, the old performance API `startTransaction()` (and `hub.startTransaction()`), as well as `span.startChild()`, will +be removed. Instead, use the new performance APIs: + +- `startSpan()` +- `startSpanManual()` +- `startInactiveSpan()` + +You can [read more about the new performance APIs here](../v8-new-performance-apis.md). + +## Deprecate variations of `Sentry.continueTrace()` + +The version of `Sentry.continueTrace()` which does not take a callback argument will be removed in favor of the version +that does. Additionally, the callback argument will not receive an argument with the next major version. + +Use `Sentry.continueTrace()` as follows: + +```ts +app.get('/your-route', req => { + Sentry.withIsolationScope(isolationScope => { + Sentry.continueTrace( + { + sentryTrace: req.headers.get('sentry-trace'), + baggage: req.headers.get('baggage'), + }, + () => { + // All events recorded in this callback will be associated with the incoming trace. For example: + Sentry.startSpan({ name: '/my-route' }, async () => { + await doExpensiveWork(); + }); + }, + ); + }); +}); +``` + +## Deprecated fields on `Span` and `Transaction` + +In v8, the Span class is heavily reworked. The following properties & methods are thus deprecated: + +- `span.toContext()`: Access the fields directly instead. +- `span.updateWithContext(newSpanContext)`: Update the fields directly instead. +- `span.setName(newName)`: Use `span.updateName(newName)` instead. +- `span.toTraceparent()`: use `spanToTraceHeader(span)` util instead. +- `span.getTraceContext()`: Use `spanToTraceContext(span)` utility function instead. +- `span.sampled`: Use `span.isRecording()` instead. +- `span.spanId`: Use `span.spanContext().spanId` instead. +- `span.parentSpanId`: Use `spanToJSON(span).parent_span_id` instead. +- `span.traceId`: Use `span.spanContext().traceId` instead. +- `span.name`: Use `spanToJSON(span).description` instead. +- `span.description`: Use `spanToJSON(span).description` instead. +- `span.getDynamicSamplingContext`: Use `spanToBaggageHeader(span)` utility function instead. +- `span.tags`: Set tags on the surrounding scope instead, or use attributes. +- `span.data`: Use `spanToJSON(span).data` instead. +- `span.setTag()`: Use `span.setAttribute()` instead or set tags on the surrounding scope. +- `span.setData()`: Use `span.setAttribute()` instead. +- `span.instrumenter` This field was removed and will be replaced internally. +- `span.transaction`: Use `getRootSpan` utility function instead. +- `span.spanRecorder`: Span recording will be handled internally by the SDK. +- `span.status`: Use `.setStatus` to set or update and `spanToJSON()` to read the span status. +- `span.op`: Use `startSpan` functions to set, `setAttribute()` to update and `spanToJSON` to read the span operation. +- `span.isSuccess`: Use `spanToJSON(span).status === 'ok'` instead. +- `transaction.setMetadata()`: Use attributes instead, or set data on the scope. +- `transaction.metadata`: Use attributes instead, or set data on the scope. +- `transaction.setContext()`: Set context on the surrounding scope instead. +- `transaction.setMeasurement()`: Use `Sentry.setMeasurement()` instead. In v8, setting measurements will be limited to + the currently active root span. +- `transaction.setName()`: Set the name with `.updateName()` and the source with `.setAttribute()` instead. +- `span.startTimestamp`: use `spanToJSON(span).start_timestamp` instead. You cannot update this anymore in v8. +- `span.endTimestamp`: use `spanToJSON(span).timestamp` instead. You cannot update this anymore in v8. You can pass a + custom end timestamp to `span.end(endTimestamp)`. + +## Deprecate `pushScope` & `popScope` in favor of `withScope` + +Instead of manually pushing/popping a scope, you should use `Sentry.withScope(callback: (scope: Scope))` instead. + +## Deprecate `configureScope` in favor of using `getCurrentScope()` + +Instead of updating the scope in a callback via `configureScope()`, you should access it via `getCurrentScope()` and +configure it directly: + +```js +Sentry.getCurrentScope().setTag('xx', 'yy'); +``` + +## Deprecate `addGlobalEventProcessor` in favor of `addEventProcessor` + +Instead of using `addGlobalEventProcessor`, you should use `addEventProcessor` which does not add the event processor +globally, but to the current client. + +For the vast majority of cases, the behavior of these should be the same. Only in the case where you have multiple +clients will this differ - but you'll likely want to add event processors per-client then anyhow, not globally. + +In v8, we will remove the global event processors overall, as that allows us to avoid keeping global state that is not +necessary. + +## Deprecate `extractTraceParentData` export from `@sentry/core` & downstream packages + +Instead, import this directly from `@sentry/utils`. + +Generally, in most cases you should probably use `continueTrace` instead, which abstracts this away from you and handles +scope propagation for you. + +## Deprecate `timestampWithMs` export - #7878 + +The `timestampWithMs` util is deprecated in favor of using `timestampInSeconds`. + +## `addTracingExtensions` replaces `addExtensionMethods` (since 7.46.0) + +Since the deprecation of `@sentry/tracing`, tracing extensions are now added by calling `addTracingExtensions` which is +exported from all framework SDKs. + +```js +// Before +import * as Sentry from '@sentry/browser'; +import { addExtensionMethods } from '@sentry/tracing'; + +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, +}); + +addExtensionMethods(); + +// After +import * as Sentry from '@sentry/browser'; + +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, +}); + +Sentry.addTracingExtensions(); +``` + +## Remove requirement for `@sentry/tracing` package (since 7.46.0) + +With `7.46.0` you no longer require the `@sentry/tracing` package to use tracing and performance monitoring with the +Sentry JavaScript SDKs. The `@sentry/tracing` package will be removed in a future major release, but can still be used +in the meantime. + +#### Browser: + +```js +// Before +import * as Sentry from '@sentry/browser'; +import { BrowserTracing } from '@sentry/tracing'; + +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, + integrations: [new BrowserTracing()], +}); + +// After +import * as Sentry from '@sentry/browser'; + +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, + integrations: [new Sentry.BrowserTracing()], +}); +``` + +#### Node: + +```js +// Before +const Sentry = require('@sentry/node'); +require('@sentry/tracing'); + +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, +}); + +// After +const Sentry = require('@sentry/node'); + +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, + integrations: [ + // Automatically instrument Node.js libraries and frameworks + ...Sentry.autoDiscoverNodePerformanceMonitoringIntegrations(), + ], +}); +``` + +**Note:** If you imported `stripUrlQueryAndFragment` from `@sentry/tracing`, you'll need to import it from +`@sentry/utils`, once you remove `@sentry/tracing`. + +## Replay options changed (since 7.35.0) - #6645 + +Some options for replay have been deprecated in favor of new APIs. See +[Replay Migration docs](./replay.md#upgrading-replay-from-7340-to-7350---6645) for details. + +## Renaming of Next.js wrapper methods (since 7.31.0) - #6790 + +We updated the names of the functions to wrap data fetchers and API routes to better reflect what they are doing. The +old methods can still be used but are deprecated and will be removed in the next major update of the SDK. + +Following function names were updated: + +- `withSentryAPI` was renamed to `wrapApiHandlerWithSentry` +- `withSentryGetServerSideProps` was renamed to `wrapGetServerSidePropsWithSentry` +- `withSentryGetStaticProps` was renamed to `wrapGetStaticPropsWithSentry` +- `withSentryServerSideGetInitialProps` was renamed to `wrapGetInitialPropsWithSentry` +- `withSentryServerSideAppGetInitialProps` was renamed to `wrapAppGetInitialPropsWithSentry` +- `withSentryServerSideDocumentGetInitialProps` was renamed to `wrapDocumentGetInitialPropsWithSentry` +- `withSentryServerSideErrorGetInitialProps` was renamed to `wrapErrorGetInitialPropsWithSentry` + +## Deprecated `tracingOrigins` (since 7.19.0) - #6176 + +The `tracingOrigins` option is deprecated in favor of using `shouldCreateSpanForRequest` and `tracePropagationTargets`. + +## Deprecate `componentTrackingPreprocessor` in Svelte SDK (since 7.16.0) - #5936 + +This release adds the `withSentryConfig` feature to the Svelte SDK. It replaces the now deprecated Svelte +`componentTrackingPreprocessor` which will be removed in the next major release. + +## Deprecate `getGlobalObject` in `@sentry/utils` (since 7.16.0) - #5949 + +This is no longer used. + +## Deprecate @sentry/hub (since 7.15.0) - #5823 + +This release deprecates `@sentry/hub` and all of it's exports. All of the `@sentry/hub` exports have moved to +`@sentry/core`. `@sentry/hub` will be removed in the next major release. + +# Upgrading Sentry Replay (beta, 7.24.0) + +For details on upgrading Replay in its beta phase, please view the [dedicated Replay MIGRATION docs](./replay.md). diff --git a/docs/migration/v8-to-v9.md b/docs/migration/v8-to-v9.md deleted file mode 100644 index ac2648059143..000000000000 --- a/docs/migration/v8-to-v9.md +++ /dev/null @@ -1,504 +0,0 @@ -# Upgrading from 8.x to 9.x - -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 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. - -### General Runtime Support Changes - -**ECMAScript Version:** All the JavaScript code in the Sentry SDK packages may now contain ECMAScript 2020 features. -This includes features like Nullish Coalescing (`??`), Optional Chaining (`?.`), `String.matchAll()`, Logical Assignment Operators (`&&=`, `||=`, `??=`), and `Promise.allSettled()`. - -If you observe failures due to syntax or features listed above, it may indicate that your current runtime does not support ES2020. -If your runtime does not support ES2020, we recommend transpiling the SDK using Babel or similar tooling. - -**Node.js:** The minimum supported Node.js version is **18.0.0**, except for ESM-only SDKs (`@sentry/astro`, `@sentry/nuxt`, `@sentry/sveltekit`) which require Node.js version **18.19.1** or higher. - -**Browsers:** Due to SDK code now including ES2020 features, the minimum supported browser list now looks as follows: - -- Chrome 80 -- Edge 80 -- Safari 14, iOS Safari 14.4 -- Firefox 74 -- Opera 67 -- Samsung Internet 13.0 - -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**. - -### Framework and Library Support Changes - -Support for the following frameworks and library versions are dropped: - -- **Remix**: Version `1.x` -- **TanStack Router**: Version `1.63.0` and lower (relevant when using `tanstackRouterBrowserTracingIntegration`) -- **SvelteKit**: Version `1.x` -- **Ember.js**: Version `3.x` and lower (minimum supported version is `4.x`) -- **Prisma**: Version `5.x` - -### TypeScript Version Policy - -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_ continue to be compatible, but no guarantees apply. - -## 2. Behavior Changes - -### `@sentry/core` / All SDKs - -- 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. - We recommend checking your `beforeSendSpan` to account for this change. - -- 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 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 }, () => { - getCurrentScope().setTag('tag-a', 'a'); // this tag will only remain within the callback - // set the tag directly on customScope in addition, if you want to to persist the tag outside of the callback - customScope.setTag('tag-a', 'a'); - }); - ``` - -- 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: - - ```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. - 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. - -### `@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. - -- 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. - - For performance instrumentation using other/older Prisma versions: - - 1. Install the `@prisma/instrumentation` package with the desired version. - 1. Pass a `new PrismaInstrumentation()` instance as exported from `@prisma/instrumentation` to the `prismaInstrumentation` option of this integration: - - ```js - import { PrismaInstrumentation } from '@prisma/instrumentation'; - Sentry.init({ - integrations: [ - prismaIntegration({ - // Override the default instrumentation that Sentry uses - prismaInstrumentation: new PrismaInstrumentation(), - }), - ], - }); - ``` - - The passed instrumentation instance will override the default instrumentation instance the integration would use, while the `prismaIntegration` will still ensure data compatibility for the various Prisma versions. - - 1. Depending on your Prisma version (prior to Prisma version 6), add `previewFeatures = ["tracing"]` to the client generator block of your Prisma schema: - - ``` - generator client { - provider = "prisma-client-js" - previewFeatures = ["tracing"] - } - ``` - -- 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. - -### 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. - You can opt out of this behavior by explicitly setting `sourcemaps.deleteSourcemapsAfterUpload` to `false` in your Sentry config. - -- 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. - - 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. - -- 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. - -## 3. Package Removals - -The `@sentry/utils` package will no longer be published. - -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. Removed APIs - -### `@sentry/core` / All SDKs - -- **The metrics API has been removed from the SDK.** - - 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`. - -- 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. - - ```js - import * as Sentry from '@sentry/node'; - - // before - Sentry.addOpenTelemetryInstrumentation(new GenericPoolInstrumentation()); - - // after - Sentry.init({ - openTelemetryInstrumentations: [new GenericPoolInstrumentation()], - }); - ``` - -- 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/nextjs` - -- The `hideSourceMaps` option was removed without replacements. - The SDK emits hidden sourcemaps by default. - -### `@sentry/solidstart` - -- The `sentrySolidStartVite` plugin is no longer exported. Instead, wrap the SolidStart config with `withSentry` and - provide Sentry options as the second parameter. - - ```ts - // app.config.ts - import { defineConfig } from '@solidjs/start/config'; - import { withSentry } from '@sentry/solidstart'; - - export default defineConfig( - withSentry( - { - /* SolidStart config */ - }, - { - /* Sentry build-time config (like project and org) */ - }, - ), - ); - ``` - -### `@sentry/nestjs` - -- 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` as a drop-in replacement. - -- Removed `SentryGlobalGraphQLFilter`. - Use the `SentryGlobalFilter` as a drop-in replacement. - -### `@sentry/react` - -- 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 configured as follows: - - ```js - import * as Sentry from '@sentry/vue'; - - Sentry.init({ - integrations: [ - Sentry.vueIntegration({ - tracingOptions: { - trackComponents: true, - timeout: 1000, - hooks: ['mount', 'update', 'unmount'], - }, - }), - ], - }); - ``` - -- 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 option `stateTransformer` in `createSentryPiniaPlugin()` now receives the full state from all stores as its parameter. The top-level keys of the state object are the store IDs. - -### `@sentry/nuxt` - -- The `tracingOptions` option in `Sentry.init()` was removed in favor of passing the `vueIntegration()` to `Sentry.init({ integrations: [...] })` and setting `tracingOptions` there. -- The option `stateTransformer` in the `piniaIntegration` now receives the full state from all stores as its parameter. The top-level keys of the state object are the store IDs. - -### `@sentry/vue` and `@sentry/nuxt` - -- When component tracking is enabled, "update" spans are no longer created by default. - - Add an `"update"` item to the `tracingOptions.hooks` option via the `vueIntegration()` to restore this behavior. - - ```ts - Sentry.init({ - integrations: [ - Sentry.vueIntegration({ - tracingOptions: { - trackComponents: true, - hooks: [ - 'mount', - 'update', // add this line to re-enable update spans - 'unmount', - ], - }, - }), - ], - }); - ``` - -### `@sentry/remix` - -- The `autoInstrumentRemix` option was removed. - The SDK now always behaves as if the option were set to `true`. - -### `@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. - -### `@sentry/core` - -- A `sampleRand` field on `PropagationContext` is now required. This is relevant if you used `scope.setPropagationContext(...)` - -- The `DEFAULT_USER_INCLUDES` constant has been removed. There is no replacement. - -- The `BAGGAGE_HEADER_NAME` export has been removed. Use a `"baggage"` string constant directly instead. - -- The `extractRequestData` method has been removed. Manually extract relevant data of request objects instead. - -- The `addRequestDataToEvent` method has been removed. Use `httpRequestToRequestData` instead and put the resulting object directly on `event.request`. - -- The `addNormalizedRequestDataToEvent` method has been removed. Use `httpRequestToRequestData` instead and put the resulting object directly on `event.request`. - -- The `generatePropagationContext()` method was removed. - Use `generateTraceId()` directly. - -- 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. - -- The `initSessionFlusher` method on the `ServerRuntimeClient` was removed without replacements. - Any mechanisms creating sessions will flush themselves. - -- The `IntegrationClass` type was removed. - Instead, use `Integration` or `IntegrationFn`. - -- The following exports have been removed without replacement: - - - `getNumberOfUrlSegments` - - `validSeverityLevels` - - `makeFifoCache` - - `arrayify` - - `flatten` - - `urlEncode` - - `getDomElement` - - `memoBuilder` - - `extractPathForTransaction` - - `_browserPerformanceTimeOriginMode` - - `addTracingHeadersToFetchRequest` - - `SessionFlusher` - -- The following types have been removed without replacement: - - - `Request` - `RequestEventData` - - `TransactionNamingScheme` - - `RequestDataIntegrationOptions` - - `SessionFlusherLike` - - `RequestSession` - - `RequestSessionStatus` - -### `@sentry/opentelemetry` - -- Removed `getPropagationContextFromSpan` without replacement. -- Removed `generateSpanContextForPropagationContext` without replacement. - -#### 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 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. - -## 5. Build Changes - -- 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` is no longer published on the `deno.land` registry so you'll need to import the SDK from npm: - - ```javascript - import * as Sentry from 'npm:@sentry/deno'; - - Sentry.init({ - dsn: '__DSN__', - // ... - }); - ``` - -## 6. Type Changes - -- `Scope` usages now always expect `Scope` instances - -- `Client` usages now always expect `BaseClient` instances. - The abstract `Client` class was removed. - Client classes now have to extend from `BaseClient`. - -These changes should not affect most users unless you relied on passing things with a similar shape to internal methods. - -In v8, interfaces have been exported from `@sentry/types`, while implementations have been exported from other packages. - -## 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. - -Additionally, we hold ourselves accountable to any security issues, meaning that if any vulnerabilities are found, we will in almost all cases backport them. - -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.