From b75a7200fd221b7b08da74b629f0af39008e98a8 Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Tue, 27 Feb 2024 14:47:28 -0500 Subject: [PATCH 1/3] docs(v8): Restructure migration docs --- MIGRATION.md | 2251 +++++++++++++-------------------- docs/migration/v4-to-v5_v6.md | 404 ++++++ docs/migration/v6-to-v7.md | 544 ++++++++ 3 files changed, 1811 insertions(+), 1388 deletions(-) create mode 100644 docs/migration/v4-to-v5_v6.md create mode 100644 docs/migration/v6-to-v7.md diff --git a/MIGRATION.md b/MIGRATION.md index 0ab76f759ab7..7e28becbe2b4 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -1,1730 +1,1205 @@ -# Upgrading from 7.x to 8.x +# Sentry JavaScript SDK Migration Docs -## Removal of `trackHeaders` option for Astro middleware +These docs walk through how to migrate our JavaScript SDKs through different major versions. -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: +- Upgrading from [SDK 4.x to 5.x/6.x](./docs/migration/v4-to-v5_v6.md) +- Uprading 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) -``` -Sentry.init({ - integrations: [ - Sentry.requestDataIntegration({ - include: { - headers: false - }, - }), - ], -}); -``` +# Upgrading from 7.x to 8.x -## Removal of Client-Side health check transaction filters +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. -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. +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`. -## Removal of the `MetricsAggregator` integration class and `metricsAggregatorIntegration` +The v8 version of the JavaScript SDK requires a self-hosted version of Sentry TBD or higher (Will be chosen once first +stable release of `8.x` comes out). -The SDKs now support metrics features without any additional configuration. +## 1. Version Support changes: -## Updated behaviour of `tracePropagationTargets` in the browser (HTTP tracing headers & CORS) +**Node.js**: We now official support Node 14+ for our CJS package, and Node 18.8+ 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. -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. +**Browser**: Our browser SDKs (`@sentry/browser`, `@sentry/react`, `@sentry/vue`, etc.) now require ES6+ compatible +browsers. 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. -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. +New minimum supported browsers: -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`. +- Chrome 51 +- Edge 15 +- Safari/iOS Safari 10 +- Firefox 54 +- Opera 38 +- Samnsung Internet 5 -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"`. +For IE11 support please transpile your code to ES5 using babel or similar and add required polyfills. -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')`. +**React**: We no longer support React 15 in version 8 of the React SDK. -## Removal of the `tracingOrigins` option +## 2. Package removal -After its deprecation in v7 the `tracingOrigins` option 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. The `tracePropagationTargets` option can no longer be set in the `browserTracingIntegration()` options. +We've removed the following packages: -## Dropping Support for React 15 +- [@sentry/hub](./MIGRATION.md#sentryhub) +- [@sentry/tracing](./MIGRATION.md#sentrytracing) +- [@sentry/integrations](./MIGRATION.md#sentryintegrations) -Sentry will no longer officially support React 15 in version 8. This means that React 15.x will be removed -from`@sentry/react`'s peer dependencies. +#### @sentry/hub -## Removal of deprecated API in `@sentry/nextjs` +`@sentry/hub` has been removed and will no longer be published. All of the `@sentry/hub` exports have moved to +`@sentry/core`. -The following previously deprecated API has been removed from the `@sentry/nextjs` package: +#### @sentry/tracing -- `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` +`@sentry/tracing` has been removed and will no longer be published. See +[below](./MIGRATION.md/#3-removal-of-deprecated-apis) for more details. -## Removal of `Span` class export from SDK packages +For Browser SDKs you can import `BrowserTracing` from the SDK directly: -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. +```js +// Before +import * as Sentry from '@sentry/browser'; +import { BrowserTracing } from '@sentry/tracing'; -## Removal of Severity Enum +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, + integrations: [new BrowserTracing()], +}); -In v7 we deprecated the `Severity` enum in favor of using the `SeverityLevel` type. In v8 we removed the `Severity` -enum. If you were using the `Severity` enum, you should replace it with the `SeverityLevel` type. See -[below](#severity-severitylevel-and-severitylevels) for code snippet examples +// After +import * as Sentry from '@sentry/browser'; -## Removal of the `Offline` integration +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, + integrations: [new Sentry.BrowserTracing()], +}); +``` -The `Offline` integration has been removed in favor of the offline transport wrapper: -http://docs.sentry.io/platforms/javascript/configuration/transports/#offline-caching +If you were importing `@sentry/tracing` for the side effect, you can now use `Sentry.addTracingExtensions()` to add the +tracing extensions to the SDK. `addTracingExtensions` replaces the `addExtensionMethods` method from `@sentry/tracing`. -## Removal of `enableAnrDetection` and `Anr` class (##10562) +```js +// Before +import * as Sentry from '@sentry/browser'; +import '@sentry/tracing'; -The `enableAnrDetection` and `Anr` class have been removed. See the -[docs](https://docs.sentry.io/platforms/node/configuration/application-not-responding/) for more details how to migrate -to `anrIntegration`, the new integration for ANR detection. +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, +}); -## Removal of `Sentry.configureScope` (#10565) +// After +import * as Sentry from '@sentry/browser'; -The top level `Sentry.configureScope` function has been removed. Instead, you should use the `Sentry.getCurrentScope()` -to access and mutate the current scope. +Sentry.addTracingExtensions(); -## Deletion of `@sentry/hub` package (#10530) +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, + integrations: [new Sentry.BrowserTracing()], +}); +``` -`@sentry/hub` has been removed. All exports from `@sentry/tracing` should be available in `@sentry/core` or in -`@sentry/browser` and `@sentry/node`. +For Node SDKs you no longer need the side effect import, you can remove all references to `@sentry/tracing`. -## Deletion of `@sentry/tracing` package +```js +// Before +const Sentry = require('@sentry/node'); +require('@sentry/tracing'); -`@sentry/tracing` has been removed. All exports from `@sentry/tracing` should be available in `@sentry/core` or in -`@sentry/browser` and `@sentry/node`. +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, +}); -## Removal of `makeXHRTransport` transport (#10703) +// After +const Sentry = require('@sentry/node'); -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. +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, +}); +``` -## General API Changes +#### @sentry/integrations -- The minumum supported Node version for all the SDK packages is Node 14 (#10527) -- Remove `spanStatusfromHttpCode` in favour of `getSpanStatusFromHttpCode` (#10361) -- Remove deprecated `deepReadDirSync` export from `@sentry/node` (#10564) -- Remove `_eventFromIncompleteOnError` usage (#10553) -- The `Transaction` integration in `@sentry/integrations` has been removed. There is no replacement API. (#10556) -- `extraErrorDataIntegration` now looks at - [`error.cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause) by - default. +`@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. -## Integrations +```js +// before +import { RewriteFrames } from '@sentry/integrations'; -We moved pluggable integrations from their own package (`@sentry/integrations`) to `@sentry/browser` and `@sentry/node`. +// after +import { rewriteFramesIntegration } from '@sentry/browser'; +``` Integrations that are now exported from `@sentry/browser` (or framework-specific packages like `@sentry/react`): -- httpClientIntegration -- contextLinesIntegration -- reportingObserverIntegration +- 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 -- debugIntegration -- extraErrorDataIntegration -- rewriteFramesIntegration -- sessionTimingIntegration -- dedupeIntegration (enabled by default, not pluggable) +- captureConsoleIntegration (`CaptureConsole`) +- debugIntegration (`Debug`) +- extraErrorDataIntegration (`ExtraErrorData`) +- rewriteFramesIntegration (`RewriteFrames`) +- sessionTimingIntegration (`SessionTiming`) +- dedupeIntegration (`Dedupe`) - _Note: enabled by default, not pluggable_ -# Deprecations in 7.x +The `Transaction` integration has been removed from `@sentry/integrations`. There is no replacement API. -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+. +## 3. Performance Monitoring Changes -```bash -npx @sentry/migr8@latest -``` +- [Performance Monitoring API](./MIGRATION.md#performance-monitoring-api) +- [Performance Monitoring Integrations](./MIGRATION.md#performance-monitoring-integrations) -This will let you select which updates to run, and automatically update your code. Make sure to still review all code -changes! +### Performance Monitoring API -## Depreacted `BrowserTracing` integration +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. -The `BrowserTracing` integration, together with the custom routing instrumentations passed to it, are deprecated in v8. -Instead, you should use `Sentry.browserTracingIntegration()`. +Instead of using `startTransaction` and `span.startChild`, you rely on new helper methods to create spans top level +helpers to create spans. -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: +```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(); +}); -### `@sentry/browser`, `@sentry/svelte`, `@sentry/gatsby` +// `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(); +}); -```js -import * as Sentry from '@sentry/browser'; +// You can nest spans via more `startSpan` calls. +const value = Sentry.startSpan({ name: 'mySpan' }, span => { + span.setAttribute('key1', 'value1'); -Sentry.init({ - integrations: [Sentry.browserTracingIntegration()], + // `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(); + }); +} ``` -### `@sentry/react` +You can [read more about the new performance APIs here](./docs/v8-new-performance-apis.md). -```js -import * as Sentry from '@sentry/react'; +To accomodate 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: + +- `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 +- `nestIntegration`: Automatically instruments Nest.js +- `postgresIntegration`: Automatically instruments PostgreSQL +- `prismaIntegration`: Automatically instruments Prisma + +## 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) +- [Astro SDK](./MIGRATION.md#astro-sdk) + +### General + +Removed top-level exports: `tracingOrigins`, `MetricsAggregator`, `metricsAggregatorIntegration`, `Severity`, +`Sentry.configureScope`, `Span`, `spanStatusfromHttpCode`, `makeMain`, `lastEventId`, `pushScope`, `popScope`, +`addGlobalEventProcessor`, `timestampWithMs`, `addExtensionMethods` + +- [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) +- [Removal of `lastEventId()` method](./MIGRATION.md#deprecate-lasteventid) + +#### Deprecation of `Hub` and `getCurrentHub()` -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, - }), - ], -}); -``` +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. -### `@sentry/vue` +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 -import * as Sentry from '@sentry/vue'; +// before +const replay = Sentry.getIntegration(Replay); -Sentry.init({ - integrations: [ - Sentry.browserTracingIntegration({ - // pass router in, if applicable - router, - }), - ], -}); +// after +const replay = getClient().getIntegrationByName('Replay'); ``` -### `@sentry/angular` & `@sentry/angular-ivy` +#### `tracingOrigins` has been replaced by `tracePropagationTargets` -```js -import * as Sentry from '@sentry/angular'; +`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. +```ts +// Before (Browser) Sentry.init({ - integrations: [Sentry.browserTracingIntegration()], + dsn: '__DSN__', + integrations: [new Sentry.BrowserTracing({})], }); -// You still need to add the Trace Service like before! +// After +Sentry.init({ + dsn: '__DSN__', + tracePropagationTargets: ['localhost', 'example.com'], +}); ``` -### `@sentry/remix` +#### Removal of the `MetricsAggregator` integration class and `metricsAggregatorIntegration` -```js -import * as Sentry from '@sentry/remix'; +The SDKs now support metrics features without any additional configuration. +```ts +// before +// Server (Node/Deno/Bun) Sentry.init({ - integrations: [ - Sentry.browserTracingIntegration({ - useEffect, - useLocation, - useMatches, - }), - ], + dsn: '__DSN__', + _experiments: { + metricsAggregator: true, + }, }); -``` - -### `@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'; +// Browser +Sentry.init({ + dsn: '__DSN__', + integrations: [Sentry.metricsAggregatorIntegration()], +}); +// after Sentry.init({ - integrations: [ - Sentry.browserTracingIntegration({ - // add custom options here - }), - ], + dsn: '__DSN__', }); ``` -### `@sentry/ember` +#### Removal of Severity Enum -Browser tracing is automatically set up for you. You can configure it as before through configuration. +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. -## Deprecated `transactionContext` passed to `tracesSampler` +```js +// Before: +import { Severity, SeverityLevel } from '@sentry/types'; -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). +const levelA = Severity.error; -## Deprecate using `getClient()` to check if the SDK was initialized +const levelB: SeverityLevel = "error" -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. +// After +import { SeverityLevel } from '@sentry/types'; -## Deprecate `getCurrentHub()` +const levelA = "error" as SeverityLevel; -In v8, you will no longer have a Hub, only Scopes as a concept. This also means that `getCurrentHub()` will eventually -be removed. +const levelB: SeverityLevel = "error" +``` -Instead of `getCurrentHub()`, use the respective replacement API directly - see [Deprecate Hub](#deprecate-hub) for -details. +#### Removal of `Sentry.configureScope` method -## Deprecate class-based integrations +The top level `Sentry.configureScope` function has been removed. Instead, you should use the `Sentry.getCurrentScope()` +to access and mutate the current scope. -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 +```js +// Before +Sentry.configureScope(scope => { + scope.setTag('key', 'value'); +}); -- for example, `new Integrations.LinkedErrors()` becomes `linkedErrorsIntegration()`. - -The following list shows how integrations should be migrated: - -| 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` | - -## 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() | REMOVED - Use event processors or beforeSend instead | -| 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.setTransactionName()` - -Instead, either set this as attributes or tags, or use an event processor to set `event.transaction`. - -## 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(); - }); - }, - ); - }); -}); -``` - -## Deprecate `Sentry.lastEventId()` and `hub.lastEventId()` - -`Sentry.lastEventId()` sometimes causes race conditions, so we are deprecating it in favour of the `beforeSend` -callback. - -```js -// Before - -Sentry.init({ - beforeSend(event, hint) { - const lastCapturedEventId = Sentry.lastEventId(); - - // Do something with `lastCapturedEventId` here - - return event; - }, -}); - -// After -Sentry.init({ - beforeSend(event, hint) { - const lastCapturedEventId = event.event_id; - - // Do something with `lastCapturedEventId` here - - return event; - }, -}); -``` - -## 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 `getDynamicSamplingContextFromSpan` 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 `lastEventId()` - -Instead, if you need the ID of a recently captured event, we recommend using `beforeSend` instead: - -```ts -import * as Sentry from '@sentry/browser'; - -Sentry.init({ - dsn: '__DSN__', - beforeSend(event, hint) { - const lastCapturedEventId = event.event_id; - - // Do something with `lastCapturedEventId` here - - return event; - }, -}); +// After +Sentry.getCurrentScope().setTag('key', 'value'); ``` -## Deprecate `timestampWithMs` export - #7878 +#### Removal of `Span` class export from SDK packages -The `timestampWithMs` util is deprecated in favor of using `timestampInSeconds`. +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. -## `addTracingExtensions` replaces `addExtensionMethods` (since 7.46.0) +#### Removal of `spanStatusfromHttpCode` in favour of `getSpanStatusFromHttpCode` -Since the deprecation of `@sentry/tracing`, tracing extensions are now added by calling `addTracingExtensions` which is -exported from all framework SDKs. +In v8, we are removing the `spanStatusfromHttpCode` function in favor of `getSpanStatusFromHttpCode`. ```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'; +// before +const spanStatus = spanStatusfromHttpCode(200); -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, -}); - -Sentry.addTracingExtensions(); +// after +const spanStatus = getSpanStatusFromHttpCode(200); ``` -## 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()], -}); -``` +#### Removal of `addGlobalEventProcessor` in favour of `addEventProcessor` -#### Node: +In v8, we are removing the `addGlobalEventProcessor` function in favor of `addEventProcessor`. ```js -// Before -const Sentry = require('@sentry/node'); -require('@sentry/tracing'); - -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, +// before +addGlobalEventProcessor(event => { + delete event.extra; + return event; }); -// After -const Sentry = require('@sentry/node'); - -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, - integrations: [ - // Automatically instrument Node.js libraries and frameworks - ...Sentry.autoDiscoverNodePerformanceMonitoringIntegrations(), - ], +// after +addEventProcessor(event => { + delete event.extra; + return event; }); ``` -**Note:** If you imported `stripUrlQueryAndFragment` from `@sentry/tracing`, you'll need to import it from -`@sentry/utils`, once you remove `@sentry/tracing`. +#### Removal of `lastEventId()` method -## Replay options changed (since 7.35.0) - #6645 +The `lastEventId` function has been removed. See [below](./MIGRATION.md#deprecate-lasteventid) for more details. -Some options for replay have been deprecated in favor of new APIs. See -[Replay Migration docs](./packages/replay/MIGRATION.md#upgrading-replay-from-7340-to-7350) for details. +### Browser SDK (Browser, React, Vue, Angular, Ember, etc.) -## Renaming of Next.js wrapper methods (since 7.31.0) - #6790 +Removed top-level exports: `Offline`, `makeXHRTransport`, `BrowserTracing` -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. +- [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) -Following function names were updated: +#### Removal of the `BrowserTracing` integration -- `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` +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) -## Deprecated `tracingOrigins` (since 7.19.0) - #6176 +#### Removal of the `Offline` integration -The `tracingOrigins` option is deprecated in favor of using `shouldCreateSpanForRequest` and `tracePropagationTargets`. +The `Offline` integration has been removed in favor of the +[offline transport wrapper](http://docs.sentry.io/platforms/javascript/configuration/transports/#offline-caching). -## Deprecate `componentTrackingPreprocessor` in Svelte SDK (since 7.16.0) - #5936 +#### Removal of `makeXHRTransport` transport -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. +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. -## Deprecate `getGlobalObject` in `@sentry/utils` (since 7.16.0) - #5949 +### Server-side SDKs (Node, Deno, Bun, etc.) -This is no longer used. +Removed top-level exports: `enableAnrDetection`, `Anr`, `deepReadDirSync` -## Deprecate @sentry/hub (since 7.15.0) - #5823 +- [Removal of `enableAnrDetection` and `Anr` class](./MIGRATION.md#removal-of-enableanrdetection-and-anr-class) +- [Removal of `deepReadDirSync` method](./MIGRATION.md#removal-of-deepreaddirsync-method) -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. +#### Removal of `enableAnrDetection` and `Anr` class -# Upgrading Sentry Replay (beta, 7.24.0) +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: -For details on upgrading Replay in its beta phase, please view the -[dedicated Replay MIGRATION docs](./packages/replay/MIGRATION.md). +#### Removal of `deepReadDirSync` method -# Upgrading from 6.x to 7.x +The `deepReadDirSync` method has been removed. There is no replacement API. -The main goal of version 7 is to reduce bundle size. This version is breaking because we removed deprecated APIs, -upgraded our build tooling, and restructured npm package contents. Below we will outline all the breaking changes you -should consider when upgrading. +### Next.js SDK -**TL;DR** If you only use basic features of Sentry, or you simply copy & pasted the setup examples from our docs, here's -what changed for you: +Removed top-level exports: `withSentryApi`, `withSentryAPI`, `withSentryGetServerSideProps`, `withSentryGetStaticProps`, +`withSentryServerSideGetInitialProps`, `withSentryServerSideAppGetInitialProps`, +`withSentryServerSideDocumentGetInitialProps`, `withSentryServerSideErrorGetInitialProps`, `nextRouterInstrumentation`, +`IS_BUILD`, `isBuild` -- If you installed additional Sentry packages, such as`@sentry/tracing` alongside your Sentry SDK (e.g. `@sentry/react` - or `@sentry/node`), make sure to upgrade all of them to version 7. -- Our CDN bundles are now ES6 - you will need to [reconfigure your script tags](#renaming-of-cdn-bundles) if you want to - keep supporting ES5 and IE11 on the new SDK version. -- Distributed CommonJS files will be ES6. Use a transpiler if you need to support old node versions. -- We bumped the TypeScript version we generate our types with to 3.8.3. Please check if your TypeScript projects using - TypeScript version 3.7 or lower still compile. Otherwise, upgrade your TypeScript version. -- `whitelistUrls` and `blacklistUrls` have been renamed to `allowUrls` and `denyUrls` in the `Sentry.init()` options. -- The `UserAgent` integration is now called `HttpContext`. -- If you are using Performance Monitoring and with tracing enabled, you might have to - [make adjustments to your server's CORS settings](#propagation-of-baggage-header) +- [Removal of deprecated API in `@sentry/nextjs`](./MIGRATION.md#removal-of-deprecated-api-in-sentrynextjs) -## Dropping Support for Node.js v6 +#### Removal of deprecated API in `@sentry/nextjs` -Node.js version 6 has reached end of life in April 2019. For Sentry JavaScript SDK version 7, we will no longer be -supporting version 6 of Node.js. +The following previously deprecated API has been removed from the `@sentry/nextjs` package: -As far as SDK development goes, dropping support means no longer running integration tests for Node.js version 6, and -also no longer handling edge cases specific to version 6. Running the new SDK version on Node.js v6 is therefore highly -discouraged. +- `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` -## Removal of `@sentry/minimal` +### Astro SDK -The `@sentry/minimal` package was deleted and it's functionality was moved to `@sentry/hub`. All exports from -`@sentry/minimal` should be available in `@sentry/hub` other than `_callOnClient` function which was removed. +#### Removal of `trackHeaders` option for Astro middleware -```ts -// New in v7: -import { addBreadcrumb, captureException, configureScope, setTag } from '@sentry/hub'; +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: -// Before: -import { addBreadcrumb, captureException, configureScope, setTag } from '@sentry/minimal'; +```js +Sentry.init({ + integrations: [ + Sentry.requestDataIntegration({ + include: { + headers: false + }, + }), + ], +}); ``` -## Explicit Client Options - -In v7, we've updated the `Client` to have options separate from the options passed into `Sentry.init`. This means that -constructing a client now requires 3 options: `integrations`, `transport` and `stackParser`. These can be customized as -you see fit. - -```ts -import { BrowserClient, defaultStackParser, defaultIntegrations, makeFetchTransport } from '@sentry/browser'; +## 5. Behaviour Changes -// New in v7: -const client = new BrowserClient({ - transport: makeFetchTransport, - stackParser: defaultStackParser, - integrations: defaultIntegrations, -}); +- [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) +- [Removal of Client-Side health check transaction filters](./MIGRATION.md#removal-of-client-side-health-check-transaction-filters) -// Before: -const client = new BrowserClient(); -``` +#### Updated behaviour of `tracePropagationTargets` in the browser (HTTP tracing headers & CORS) -Since you now explicitly pass in the dependencies of the client, you can also tree-shake out dependencies that you do -not use this way. For example, you can tree-shake out the SDK's default integrations and only use the ones that you want -like so: +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. -```ts -import { - BrowserClient, - Breadcrumbs, - Dedupe, - defaultStackParser, - GlobalHandlers, - Integrations, - makeFetchTransport, - LinkedErrors, -} from '@sentry/browser'; - -// New in v7: -const client = new BrowserClient({ - transport: makeFetchTransport, - stackParser: defaultStackParser, - integrations: [new Breadcrumbs(), new GlobalHandlers(), new LinkedErrors(), new Dedupe()], -}); -``` +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. -## Removal Of Old Platform Integrations From `@sentry/integrations` Package +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`. -The following classes will be removed from the `@sentry/integrations` package and can no longer be used: +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"`. -- `Angular` -- `Ember` -- `Vue` +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')`. -These classes have been superseded and were moved into their own packages, `@sentry/angular`, `@sentry/ember`, and -`@sentry/vue` in a previous version. Refer to those packages if you want to integrate Sentry into your Angular, Ember, -or Vue application. +#### `extraErrorDataIntegration` changes -## Moving To ES6 For CommonJS Files +The `extraErrorDataIntegration` integration now looks at +[`error.cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause) by +default. -From version 7 onwards, the CommonJS files in Sentry JavaScript SDK packages will use ES6. +#### `transactionContext` no longer passed to `tracesSampler` -If you need to support Internet Explorer 11 or old Node.js versions, we recommend using a preprocessing tool like -[Babel](https://babeljs.io/) to convert Sentry packages to ES5. +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). -## Renaming Of CDN Bundles +#### `getClient()` always returns a client -CDN bundles will be ES6 by default. Files that followed the naming scheme `bundle.es6.min.js` were renamed to -`bundle.min.js` and any bundles using ES5 (files without `.es6`) turned into `bundle.es5.min.js`. +`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. -See our [docs on CDN bundles](https://docs.sentry.io/platforms/javascript/install/cdn/) for more information. +#### Removal of Client-Side health check transaction filters -## Restructuring Of Package Content +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. -Up until v6.x, we have published our packages on npm with the following structure: +# Deprecations in 7.x -- `build` folder contained CDN bundles -- `dist` folder contained CommonJS files and TypeScript declarations -- `esm` folder contained ESM files and TypeScript declarations +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+. -Moving forward the JavaScript SDK packages will generally have the following structure: +```bash +npx @sentry/migr8@latest +``` -- `cjs` folder contains CommonJS files -- `esm` folder contains ESM files -- `types` folder contains TypeScript declarations +This will let you select which updates to run, and automatically update your code. Make sure to still review all code +changes! -**CDN bundles of version 7 or higher will no longer be distributed through our npm package.** This means that most -third-party CDNs like [unpkg](https://unpkg.com/) or [jsDelivr](https://www.jsdelivr.com/) will also not provide them. +## Deprecated `BrowserTracing` integration -If you depend on any specific files in a Sentry JavaScript npm package, you will most likely need to update their -references. For example, imports on `@sentry/browser/dist/client` will become `@sentry/browser/cjs/client`. However, -directly importing from specific files is discouraged. +The `BrowserTracing` integration, together with the custom routing instrumentations passed to it, are deprecated in v8. +Instead, you should use `Sentry.browserTracingIntegration()`. -## Removing the `API` class from `@sentry/core` +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: -The internal `API` class was removed in favor of using client options explicitly. +### `@sentry/browser`, `@sentry/svelte`, `@sentry/gatsby` ```js -// New in v7: -import { - initAPIDetails, - getEnvelopeEndpointWithUrlEncodedAuth, - getStoreEndpointWithUrlEncodedAuth, -} from '@sentry/core'; - -const client = getCurrentHub().getClient(); -const dsn = client.getDsn(); -const options = client.getOptions(); -const envelopeEndpoint = getEnvelopeEndpointWithUrlEncodedAuth(dsn, options.tunnel); - -// Before: -import { API } from '@sentry/core'; +import * as Sentry from '@sentry/browser'; -const api = new API(dsn, metadata, tunnel); -const dsn = api.getDsn(); -const storeEndpoint = api.getStoreEndpointWithUrlEncodedAuth(); -const envelopeEndpoint = api.getEnvelopeEndpointWithUrlEncodedAuth(); +Sentry.init({ + integrations: [Sentry.browserTracingIntegration()], +}); ``` -## Transport Changes - -The `Transport` API was simplified and some functionality (e.g. APIDetails and client reports) was refactored and moved -to the Client. To send data to Sentry, we switched from the previously used -[Store endpoint](https://develop.sentry.dev/sdk/store/) to the -[Envelopes endpoint](https://develop.sentry.dev/sdk/envelopes/). - -This example shows the new v7 and the v6 Transport API: +### `@sentry/react` ```js -// New in v7: -export interface Transport { - /* Sends an envelope to the Envelope endpoint in Sentry */ - send(request: Envelope): PromiseLike; - /* Waits for all events to be sent or the timeout to expire, whichever comes first */ - flush(timeout?: number): PromiseLike; -} +import * as Sentry from '@sentry/react'; -// Before: -export interface Transport { - /* Sends the event to the Store endpoint in Sentry */ - sendEvent(event: Event): PromiseLike; - /* Sends the session to the Envelope endpoint in Sentry */ - sendSession?(session: Session | SessionAggregates): PromiseLike; - /* Waits for all events to be sent or the timeout to expire, whichever comes first */ - close(timeout?: number): PromiseLike; - /* Increment the counter for the specific client outcome */ - recordLostEvent?(type: Outcome, category: SentryRequestType): void; -} +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, + }), + ], +}); ``` -### Custom Transports +### `@sentry/vue` -If you rely on a custom transport, you will need to make some adjustments to how it is created when migrating to v7. -Note that we changed our transports from a class-based to a functional approach, meaning that the previously class-based -transports are now created via functions. This also means that custom transports are now passed by specifying a factory -function in the `Sentry.init` options object instead passing the custom transport's class. +```js +import * as Sentry from '@sentry/vue'; -The following example shows how to create a custom transport in v7 vs. how it was done in v6: +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration({ + // pass router in, if applicable + router, + }), + ], +}); +``` -```js -// New in v7: -import { BaseTransportOptions, Transport, TransportMakeRequestResponse, TransportRequest } from '@sentry/types'; -import { createTransport } from '@sentry/core'; - -export function makeMyCustomTransport(options: BaseTransportOptions): Transport { - function makeRequest(request: TransportRequest): PromiseLike { - // this is where your sending logic goes - const myCustomRequest = { - body: request.body, - url: options.url - }; - // you define how `sendMyCustomRequest` works - return sendMyCustomRequest(myCustomRequest).then(response => ({ - headers: { - 'x-sentry-rate-limits': response.headers.get('X-Sentry-Rate-Limits'), - 'retry-after': response.headers.get('Retry-After'), - }, - })); - } +### `@sentry/angular` & `@sentry/angular-ivy` - // `createTransport` takes care of rate limiting and flushing - return createTransport(options, makeRequest); -} +```js +import * as Sentry from '@sentry/angular'; Sentry.init({ - dsn: '...', - transport: makeMyCustomTransport, // this function will be called when the client is initialized - ... -}) + integrations: [Sentry.browserTracingIntegration()], +}); -// Before: -class MyCustomTransport extends BaseTransport { - constructor(options: TransportOptions) { - // initialize your transport here - super(options); - } - - public sendEvent(event: Event): PromiseLike { - // this is where your sending logic goes - // `url` is decoded from dsn in BaseTransport - const myCustomRequest = createMyCustomRequestFromEvent(event, this.url); - return sendMyCustomRequest(myCustomRequest).then(() => resolve({status: 'success'})); - } - - public sendSession(session: Session): PromiseLike {...} - // ... -} +// You still need to add the Trace Service like before! +``` + +### `@sentry/remix` + +```js +import * as Sentry from '@sentry/remix'; Sentry.init({ - dsn: '...', - transport: MyCustomTransport, // the constructor was called when the client was initialized - ... -}) + integrations: [ + Sentry.browserTracingIntegration({ + useEffect, + useLocation, + useMatches, + }), + ], +}); ``` -Overall, the new way of transport creation allows you to create your custom sending implementation without having to -deal with the conversion of events or sessions to envelopes. We recommend calling using the `createTransport` function -from `@sentry/core` as demonstrated in the example above which, besides creating the `Transport` object with your custom -logic, will also take care of rate limiting and flushing. - -For a complete v7 transport implementation, take a look at our -[browser fetch transport](https://github.com/getsentry/sentry-javascript/blob/ebc938a03d6efe7d0c4bbcb47714e84c9a566a9c/packages/browser/src/transports/fetch.ts#L1-L34). - -### Node Transport Changes +### `@sentry/nextjs`, `@sentry/astro`, `@sentry/sveltekit` -To clean up the options interface, we now require users to pass down transport related options under the -`transportOptions` key. The options that were changed were `caCerts`, `httpProxy`, and `httpsProxy`. In addition, -`httpProxy` and `httpsProxy` were unified to a single option under the `transportOptions` key, `proxy`. +Browser tracing is automatically set up for you in these packages. If you need to customize the options, you can do it +like this: -```ts -// New in v7: -Sentry.init({ - dsn: '...', - transportOptions: { - caCerts: getMyCaCert(), - proxy: 'http://example.com', - }, -}); +```js +import * as Sentry from '@sentry/nextjs'; -// Before: Sentry.init({ - dsn: '...', - caCerts: getMyCaCert(), - httpsProxy: 'http://example.com', + integrations: [ + Sentry.browserTracingIntegration({ + // add custom options here + }), + ], }); ``` -## Enum Changes - -Given that enums have a high bundle-size impact, our long term goal is to eventually remove all enums from the SDK in -favor of string literals. +### `@sentry/ember` -### Removed Enums +Browser tracing is automatically set up for you. You can configure it as before through configuration. -- The previously deprecated enum `Status` was removed (see - [#4891](https://github.com/getsentry/sentry-javascript/pull/4891)). -- The previously deprecated internal-only enum `RequestSessionStatus` was removed (see - [#4889](https://github.com/getsentry/sentry-javascript/pull/4889)) in favor of string literals. -- The previously deprecated internal-only enum `SessionStatus` was removed (see - [#4890](https://github.com/getsentry/sentry-javascript/pull/4890)) in favor of string literals. +## Deprecated `transactionContext` passed to `tracesSampler` -### Deprecated Enums +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). -The two enums `SpanStatus`, and `Severity` remain deprecated, as we decided to limit the number of high-impact breaking -changes in v7. They will be removed in the next major release which is why we strongly recommend moving to the -corresponding string literals. Here's how to adjust [`Severity`](#severity-severitylevel-and-severitylevels) and -[`SpanStatus`](#spanstatus). +## Deprecate using `getClient()` to check if the SDK was initialized -## Session Changes +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. -Note: These changes are not relevant for the majority of Sentry users but if you are building an SDK on top of the -Javascript SDK, you might need to make some adaptions. The internal `Session` class was refactored and replaced with a -more functional approach in [#5054](https://github.com/getsentry/sentry-javascript/pull/5054). Instead of the class, we -now export a `Session` interface from `@sentry/types` and three utility functions to create and update a `Session` -object from `@sentry/hub`. This short example shows what has changed and how to deal with the new functions: +## Deprecate `getCurrentHub()` -```js -// New in v7: -import { makeSession, updateSession, closeSession } from '@sentry/hub'; +In v8, you will no longer have a Hub, only Scopes as a concept. This also means that `getCurrentHub()` will eventually +be removed. -const session = makeSession({ release: 'v1.0' }); -updateSession(session, { environment: 'prod' }); -closeSession(session, 'ok'); +Instead of `getCurrentHub()`, use the respective replacement API directly - see [Deprecate Hub](#deprecate-hub) for +details. -// Before: -import { Session } from '@sentry/hub'; +## Deprecate class-based integrations -const session = new Session({ release: 'v1.0' }); -session.update({ environment: 'prod' }); -session.close('ok'); -``` +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 -## Propagation of Baggage Header - -We introduced a new way of propagating tracing and transaction-related information between services. This change adds -the [`baggage` HTTP header](https://www.w3.org/TR/baggage/) to outgoing requests if the instrumentation of requests is -enabled. Since this adds a header to your HTTP requests, you might need to adjust your Server's CORS settings to allow -this additional header. Take a look at the -[Sentry docs](https://docs.sentry.io/platforms/javascript/performance/connect-services/#navigation-and-other-xhr-requests) -for more in-depth instructions what to change. - -## General API Changes - -For our efforts to reduce bundle size of the SDK we had to remove and refactor parts of the package which introduced a -few changes to the API: - -- Remove support for deprecated `@sentry/apm` package. `@sentry/tracing` should be used instead. -- Remove deprecated `user` field from DSN. `publicKey` should be used instead. -- Remove deprecated `whitelistUrls` and `blacklistUrls` options from `Sentry.init`. They have been superseded by - `allowUrls` and `denyUrls` specifically. See - [our docs page on inclusive language](https://develop.sentry.dev/inclusion/) for more details. -- Gatsby SDK: Remove `Sentry` from `window` object. -- Remove deprecated `Status`, `SessionStatus`, and `RequestSessionStatus` enums. These were only part of an internal - API. If you are using these enums, we encourage you to to look at - [b177690d](https://github.com/getsentry/sentry-javascript/commit/b177690d89640aef2587039113c614672c07d2be), - [5fc3147d](https://github.com/getsentry/sentry-javascript/commit/5fc3147dfaaf1a856d5923e4ba409479e87273be), and - [f99bdd16](https://github.com/getsentry/sentry-javascript/commit/f99bdd16539bf6fac14eccf1a974a4988d586b28) to to see - the changes we've made to our code as result. We generally recommend using string literals instead of the removed - enums. -- Remove 'critical' severity. -- Remove deprecated `getActiveDomain` method and `DomainAsCarrier` type from `@sentry/hub`. -- Rename `registerRequestInstrumentation` to `instrumentOutgoingRequests` in `@sentry/tracing`. -- Remove `Backend` and port its functionality into `Client` (see - [#4911](https://github.com/getsentry/sentry-javascript/pull/4911) and - [#4919](https://github.com/getsentry/sentry-javascript/pull/4919)). `Backend` was an unnecessary abstraction which is - not present in other Sentry SDKs. For the sake of reducing complexity, increasing consistency with other Sentry SDKs - and decreasing bundle-size, `Backend` was removed. -- Remove support for Opera browser pre v15. -- Rename `UserAgent` integration to `HttpContext`. (see - [#5027](https://github.com/getsentry/sentry-javascript/pull/5027)) -- Remove `SDK_NAME` export from `@sentry/browser`, `@sentry/node`, `@sentry/tracing` and `@sentry/vue` packages. -- Removed `eventStatusFromHttpCode` to save on bundle size. -- Replace `BrowserTracing` `maxTransactionDuration` option with `finalTimeout` option -- Removed `ignoreSentryErrors` option from AWS lambda SDK. Errors originating from the SDK will now _always_ be caught - internally. -- Removed `Integrations.BrowserTracing` export from `@sentry/nextjs`. Please import `BrowserTracing` from - `@sentry/nextjs` directly. -- Removed static `id` property from `BrowserTracing` integration. -- Removed usage of deprecated `event.stacktrace` field - -## Sentry Angular SDK Changes - -The Sentry Angular SDK (`@sentry/angular`) is now compiled with the Angular compiler (see -[#4641](https://github.com/getsentry/sentry-javascript/pull/4641)). This change was necessary to fix a long-lasting bug -in the SDK (see [#3282](https://github.com/getsentry/sentry-javascript/issues/3282)): `TraceDirective` and `TraceModule` -can now be used again without risking an application compiler error or having to disable AOT compilation. - -### Angular Version Compatibility - -As in v6, we continue to list Angular 10-13 in our peer dependencies, meaning that these are the Angular versions we -officially support. If you are using v7 with Angular <10 in your project and you experience problems, we recommend -staying on the latest 6.x version until you can upgrade your Angular version. As v7 of our SDK is compiled with the -Angular 10 compiler and we upgraded our Typescript version, the SDK will work with Angular 10 and above. Tests have -shown that Angular 9 seems to work as well (use at your own risk) but we recommend upgrading to a more recent Angular -version. - -### Import Changes - -Due to the compiler change, our NPM package structure changed as well as it now conforms to the -[Angular Package Format v10](https://docs.google.com/document/d/1uh2D6XqaGh2yjjXwfF4SrJqWl1MBhMPntlNBBsk6rbw/edit). In -case you're importing from specific paths other than `@sentry/angular` you will have to adjust these paths. As an -example, `import ... from '@sentry/angular/esm/injex.js'` should be changed to -`import ... from '@sentry/angular/esm2015/index.js'`. Generally, we strongly recommend only importing from -`@sentry/angular`. - -# Upgrading from 6.17.x to 6.18.0 - -Version 6.18.0 deprecates the `frameContextLines` top-level option for the Node SDK. This option will be removed in an -upcoming major version. To migrate off of the top-level option, pass it instead to the new `ContextLines` integration. +- for example, `new Integrations.LinkedErrors()` becomes `linkedErrorsIntegration()`. -```js -// New in 6.18.0 -init({ - dsn: '__DSN__', - integrations: [new ContextLines({ frameContextLines: 10 })], -}); +The following list shows how integrations should be migrated: -// Before: -init({ - dsn: '__DSN__', - frameContextLines: 10, -}); -``` +### List of integrations and their replacements -# Upgrading from 6.x to 6.17.x +| 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` | -You only need to make changes when migrating to `6.17.x` if you are using our internal `Dsn` class. Our internal API -class and typescript enums were deprecated, so we recommend you migrate them as well. +## Deprecate `hub.bindClient()` and `makeMain()` -The internal `Dsn` class was removed in `6.17.0`. For additional details, you can look at the -[PR where this change happened](https://github.com/getsentry/sentry-javascript/pull/4325). To migrate, see the following -example. +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. -```js -// New in 6.17.0: -import { dsnToString, makeDsn } from '@sentry/utils'; +## Deprecate `Transaction` integration -const dsn = makeDsn(process.env.SENTRY_DSN); -console.log(dsnToString(dsn)); +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. -// Before: -import { Dsn } from '@sentry/utils'; +## Changed integration interface -const dsn = new Dsn(process.env.SENTRY_DSN); -console.log(dsn.toString()); -``` +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. -The internal API class was deprecated, and will be removed in the next major release. More details can be found in the -[PR that made this change](https://github.com/getsentry/sentry-javascript/pull/4281). To migrate, see the following -example. +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. -```js -// New in 6.17.0: -import { - initAPIDetails, - getEnvelopeEndpointWithUrlEncodedAuth, - getStoreEndpointWithUrlEncodedAuth, -} from '@sentry/core'; - -const dsn = initAPIDetails(dsn, metadata, tunnel); -const dsn = api.dsn; -const storeEndpoint = getStoreEndpointWithUrlEncodedAuth(api.dsn); -const envelopeEndpoint = getEnvelopeEndpointWithUrlEncodedAuth(api.dsn, api.tunnel); +## Deprecate `getIntegration()` and `getIntegrationById()` -// Before: -import { API } from '@sentry/core'; +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: -const api = new API(dsn, metadata, tunnel); -const dsn = api.getDsn(); -const storeEndpoint = api.getStoreEndpointWithUrlEncodedAuth(); -const envelopeEndpoint = api.getEnvelopeEndpointWithUrlEncodedAuth(); +```ts +const replay = getClient().getIntegrationByName('Replay'); ``` -## Enum changes - -The enums `Status`, `SpanStatus`, and `Severity` were deprecated, and we've detailed how to migrate away from them -below. We also deprecated the `TransactionMethod`, `Outcome` and `RequestSessionStatus` enums, but those are -internal-only APIs. If you are using them, we encourage you to take a look at the corresponding PRs to see how we've -changed our code as a result. - -- `TransactionMethod`: https://github.com/getsentry/sentry-javascript/pull/4314 -- `Outcome`: https://github.com/getsentry/sentry-javascript/pull/4315 -- `RequestSessionStatus`: https://github.com/getsentry/sentry-javascript/pull/4316 +## Deprecate `Hub` -#### Status +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". -We deprecated the `Status` enum in `@sentry/types` and it will be removed in the next major release. We recommend using -string literals to save on bundle size. [PR](https://github.com/getsentry/sentry-javascript/pull/4298). We also removed -the `Status.fromHttpCode` method. This was done to save on bundle size. +`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. -```js -// New in 6.17.0: -import { eventStatusFromHttpCode } from '@sentry/utils'; +If you are using the `Hub` right now, see the following table on how to migrate to the new API: -const status = eventStatusFromHttpCode(500); +| 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() | REMOVED - Use event processors or beforeSend instead | +| 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` | -// Before: -import { Status } from '@sentry/types'; +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: -const status = Status.fromHttpCode(500); +```ts +// OLD +const hub = new Hub(); +hub.bindClient(client); +makeMain(hub); ``` -#### SpanStatus - -We deprecated the `Status` enum in `@sentry/tracing` and it will be removed in the next major release. We recommend -using string literals to save on bundle size. [PR](https://github.com/getsentry/sentry-javascript/pull/4299). We also -removed the `SpanStatus.fromHttpCode` method. This was done to save on bundle size. - -```js -// New in 6.17.0: -import { spanStatusfromHttpCode } from '@sentry/tracing'; +instead initialize the client as follows: -const status = spanStatusfromHttpCode(403); +```ts +// NEW +Sentry.withIsolationScope(() => { + Sentry.setCurrentClient(client); + client.init(); +}); +``` -// Before: -import { SpanStatus } from '@sentry/tracing'; +If you are using the Hub to capture events like so: -const status = SpanStatus.fromHttpCode(403); +```ts +// OLD +const client = new Client(); +const hub = new Hub(client); +hub.captureException(); ``` -#### Severity, SeverityLevel, and SeverityLevels - -We deprecated the `Severity` enum in `@sentry/types` and it will be removed in the next major release. We recommend -using string literals (typed as `SeverityLevel`) to save on bundle size. +instead capture isolated events as follows: -```js -// New in 6.17.5: -import { SeverityLevel } from '@sentry/types'; +```ts +// NEW +const client = new Client(); +const scope = new Scope(); +scope.setClient(client); +scope.captureException(); +``` -const levelA = "error" as SeverityLevel; +## Deprecate `client.setupIntegrations()` -const levelB: SeverityLevel = "error" +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. -// Before: -import { Severity, SeverityLevel } from '@sentry/types'; +## Deprecate `scope.getSpan()` and `scope.setSpan()` -const levelA = Severity.error; +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()`. -const levelB: SeverityLevel = "error" -``` +## Deprecate `scope.setTransactionName()` -# Upgrading from 4.x to 5.x/6.x +Instead, either set this as attributes or tags, or use an event processor to set `event.transaction`. -In this version upgrade, there are a few breaking changes. This guide should help you update your code accordingly. +## Deprecate `scope.getTransaction()` and `getActiveTransaction()` -## Integrations +Instead, you should not rely on the active transaction, but just use `startSpan()` APIs, which handle this for you. -We moved optional integrations into their own package, called `@sentry/integrations`. Also, we made a few default -integrations now optional. This is probably the biggest breaking change regarding the upgrade. +## Deprecate arguments for `startSpan()` APIs -Integrations that are now opt-in and were default before: +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()`: -- Dedupe (responsible for sending the same error only once) -- ExtraErrorData (responsible for doing fancy magic, trying to extract data out of the error object using any - non-standard keys) +- `name` +- `attributes` +- `origin` +- `op` +- `startTime` +- `scope` -Integrations that were pluggable/optional before, that also live in this package: +## Deprecate `startTransaction()` & `span.startChild()` -- Angular (browser) -- Debug (browser/node) -- Ember (browser) -- ReportingObserver (browser) -- RewriteFrames (browser/node) -- Transaction (browser/node) -- Vue (browser) +In v8, the old performance API `startTransaction()` (and `hub.startTransaction()`), as well as `span.startChild()`, will +be removed. Instead, use the new performance APIs: -### How to use `@sentry/integrations`? +- `startSpan()` +- `startSpanManual()` +- `startInactiveSpan()` -Lets start with the approach if you install `@sentry/browser` / `@sentry/node` with `npm` or `yarn`. +You can [read more about the new performance APIs here](./docs/v8-new-performance-apis.md). -Given you have a `Vue` application running, in order to use the `Vue` integration you need to do the following: +## Deprecate variations of `Sentry.continueTrace()` -With `4.x`: +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. -```js -import * as Sentry from '@sentry/browser'; +Use `Sentry.continueTrace()` as follows: -Sentry.init({ - dsn: '___PUBLIC_DSN___', - integrations: [ - new Sentry.Integrations.Vue({ - Vue, - attachProps: true, - }), - ], +```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(); + }); + }, + ); + }); }); ``` -With `5.x` you need to install `@sentry/integrations` and change the import. +## Deprecate `Sentry.lastEventId()` and `hub.lastEventId()` + +`Sentry.lastEventId()` sometimes causes race conditions, so we are deprecating it in favour of the `beforeSend` +callback. ```js -import * as Sentry from '@sentry/browser'; -import * as Integrations from '@sentry/integrations'; +// Before Sentry.init({ - dsn: '___PUBLIC_DSN___', - integrations: [ - new Integrations.Vue({ - Vue, - attachProps: true, - }), - ], -}); -``` - -In case you are using the CDN version or the Loader, we provide a standalone file for every integration, you can use it -like this: - -```html - - - - - - - - -``` - -## New Scope functions + beforeSend(event, hint) { + const lastCapturedEventId = Sentry.lastEventId(); -We realized how annoying it is to set a whole object using `setExtra`, so there are now a few new methods on the -`Scope`. + // Do something with `lastCapturedEventId` here -```typescript -setTags(tags: { [key: string]: string | number | boolean | null | undefined }): this; -setExtras(extras: { [key: string]: any }): this; -clearBreadcrumbs(): this; -``` + return event; + }, +}); -So you can do this now: +// After +Sentry.init({ + beforeSend(event, hint) { + const lastCapturedEventId = event.event_id; -```js -// New in 5.x setExtras -Sentry.withScope(scope => { - scope.setExtras(errorInfo); - Sentry.captureException(error); -}); + // Do something with `lastCapturedEventId` here -// vs. 4.x -Sentry.withScope(scope => { - Object.keys(errorInfo).forEach(key => { - scope.setExtra(key, errorInfo[key]); - }); - Sentry.captureException(error); + return event; + }, }); ``` -## Less Async API - -We removed a lot of the internal async code since in certain situations it generated a lot of memory pressure. This -really only affects you if you where either using the `BrowserClient` or `NodeClient` directly. - -So all the `capture*` functions now instead of returning `Promise` return `string | undefined`. `string` in -this case is the `event_id`, in case the event will not be sent because of filtering it will return `undefined`. - -## `close` vs. `flush` - -In `4.x` we had both `close` and `flush` on the `Client` draining the internal queue of events, helpful when you were -using `@sentry/node` on a serverless infrastructure. +## Deprecated fields on `Span` and `Transaction` -Now `close` and `flush` work similar, with the difference that if you call `close` in addition to returning a `Promise` -that you can await it also **disables** the client so it will not send any future events. +In v8, the Span class is heavily reworked. The following properties & methods are thus deprecated: -# Migrating from `raven-js` to `@sentry/browser` +- `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 `getDynamicSamplingContextFromSpan` 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)`. -https://docs.sentry.io/platforms/javascript/#browser-table Here are some examples of how the new SDKs work. Please note -that the API for all JavaScript SDKs is the same. +## Deprecate `pushScope` & `popScope` in favor of `withScope` -#### Installation +Instead of manually pushing/popping a scope, you should use `Sentry.withScope(callback: (scope: Scope))` instead. -> [Docs](https://docs.sentry.io/platforms/javascript/#connecting-the-sdk-to-sentry) +## Deprecate `configureScope` in favor of using `getCurrentScope()` -_Old_: +Instead of updating the scope in a callback via `configureScope()`, you should access it via `getCurrentScope()` and +configure it directly: ```js -Raven.config('___PUBLIC_DSN___', { - release: '1.3.0', -}).install(); +Sentry.getCurrentScope().setTag('xx', 'yy'); ``` -_New_: +## Deprecate `addGlobalEventProcessor` in favor of `addEventProcessor` -```js -Sentry.init({ - dsn: '___PUBLIC_DSN___', - release: '1.3.0', -}); -``` +Instead of using `addGlobalEventProcessor`, you should use `addEventProcessor` which does not add the event processor +globally, but to the current client. -#### Set a global tag +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. -> [Docs](https://docs.sentry.io/platforms/javascript/#tagging-events) +In v8, we will remove the global event processors overall, as that allows us to avoid keeping global state that is not +necessary. -_Old_: +## Deprecate `extractTraceParentData` export from `@sentry/core` & downstream packages -```js -Raven.setTagsContext({ key: 'value' }); -``` +Instead, import this directly from `@sentry/utils`. -_New_: +Generally, in most cases you should probably use `continueTrace` instead, which abstracts this away from you and handles +scope propagation for you. -```js -Sentry.setTag('key', 'value'); -``` +## Deprecate `lastEventId()` -#### Set user context +Instead, if you need the ID of a recently captured event, we recommend using `beforeSend` instead: -_Old_: +```ts +import * as Sentry from '@sentry/browser'; -```js -Raven.setUserContext({ - id: '123', - email: 'david@example.com', -}); -``` +Sentry.init({ + dsn: '__DSN__', + beforeSend(event, hint) { + const lastCapturedEventId = event.event_id; -_New_: + // Do something with `lastCapturedEventId` here -```js -Sentry.setUser({ - id: '123', - email: 'david@example.com', + return event; + }, }); ``` -#### Capture custom exception - -> A scope must now be sent around a capture to add extra information. -> [Docs](https://docs.sentry.io/platforms/javascript/#unsetting-context) - -_Old_: - -```js -try { - throwingFunction(); -} catch (e) { - Raven.captureException(e, { extra: { debug: false } }); -} -``` - -_New_: - -```js -try { - throwingFunction(); -} catch (e) { - Sentry.withScope(scope => { - scope.setExtra('debug', false); - Sentry.captureException(e); - }); -} -``` +## Deprecate `timestampWithMs` export - #7878 -#### Capture a message +The `timestampWithMs` util is deprecated in favor of using `timestampInSeconds`. -> A scope must now be sent around a capture to add extra information. -> [Docs](https://docs.sentry.io/platforms/javascript/#unsetting-context) +## `addTracingExtensions` replaces `addExtensionMethods` (since 7.46.0) -_Old_: +Since the deprecation of `@sentry/tracing`, tracing extensions are now added by calling `addTracingExtensions` which is +exported from all framework SDKs. ```js -Raven.captureMessage('test1', 'info'); -Raven.captureMessage('test2', 'info', { extra: { debug: false } }); -``` - -_New_: +// Before +import * as Sentry from '@sentry/browser'; +import { addExtensionMethods } from '@sentry/tracing'; -```js -Sentry.captureMessage('test1', 'info'); -Sentry.withScope(scope => { - scope.setExtra('debug', false); - Sentry.captureMessage('test2', 'info'); +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, }); -``` - -#### Breadcrumbs -> [Docs](https://docs.sentry.io/platforms/javascript/#breadcrumbs) +addExtensionMethods(); -_Old_: +// After +import * as Sentry from '@sentry/browser'; -```js -Raven.captureBreadcrumb({ - message: 'Item added to shopping cart', - category: 'action', - data: { - isbn: '978-1617290541', - cartSize: '3', - }, +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, }); -``` - -_New_: -```js -Sentry.addBreadcrumb({ - message: 'Item added to shopping cart', - category: 'action', - data: { - isbn: '978-1617290541', - cartSize: '3', - }, -}); +Sentry.addTracingExtensions(); ``` -### Ignoring Urls +## Remove requirement for `@sentry/tracing` package (since 7.46.0) -> 'ignoreUrls' was renamed to 'denyUrls'. 'ignoreErrors', which has a similar name was not renamed. -> [Docs](https://docs.sentry.io/error-reporting/configuration/?platform=browser#deny-urls) and -> [Decluttering Sentry](https://docs.sentry.io/platforms/javascript/#decluttering-sentry) +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. -_Old_: +#### Browser: ```js -Raven.config('___PUBLIC_DSN___', { - ignoreUrls: ['https://www.baddomain.com', /graph\.facebook\.com/i], +// Before +import * as Sentry from '@sentry/browser'; +import { BrowserTracing } from '@sentry/tracing'; + +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, + integrations: [new BrowserTracing()], }); -``` -_New_: +// After +import * as Sentry from '@sentry/browser'; -```js Sentry.init({ - denyUrls: ['https://www.baddomain.com', /graph\.facebook\.com/i], + dsn: '__DSN__', + tracesSampleRate: 1.0, + integrations: [new Sentry.BrowserTracing()], }); ``` -### Ignoring Events (`shouldSendCallback`) - -> `shouldSendCallback` was renamed to `beforeSend` -> ([#2253](https://github.com/getsentry/sentry-javascript/issues/2253)). Instead of returning `false`, you must return -> `null` to omit sending the event. -> [Docs](https://docs.sentry.io/error-reporting/configuration/filtering/?platform=browser#before-send) - -_Old_: +#### Node: ```js -Raven.config('___PUBLIC_DSN___', { - shouldSendCallback(event) { - // Only send events that include user data - if (event.user) { - return true; - } - return false; - }, +// Before +const Sentry = require('@sentry/node'); +require('@sentry/tracing'); + +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, }); -``` -_New_: +// After +const Sentry = require('@sentry/node'); -```js Sentry.init({ - beforeSend(event) { - if (event.user) { - return event; - } - return null; - }, + dsn: '__DSN__', + tracesSampleRate: 1.0, + integrations: [ + // Automatically instrument Node.js libraries and frameworks + ...Sentry.autoDiscoverNodePerformanceMonitoringIntegrations(), + ], }); ``` -### Modifying Events (`dataCallback`) +**Note:** If you imported `stripUrlQueryAndFragment` from `@sentry/tracing`, you'll need to import it from +`@sentry/utils`, once you remove `@sentry/tracing`. -_Old_: +## Replay options changed (since 7.35.0) - #6645 -```js -Raven.config('___PUBLIC_DSN___', { - dataCallback(event) { - if (event.user) { - // Don't send user's email address - delete event.user.email; - } - return event; - }, -}); -``` +Some options for replay have been deprecated in favor of new APIs. See +[Replay Migration docs](./packages/replay/MIGRATION.md#upgrading-replay-from-7340-to-7350) for details. -_New_: +## Renaming of Next.js wrapper methods (since 7.31.0) - #6790 -```js -Sentry.init({ - beforeSend(event) { - if (event.user) { - delete event.user.email; - } - return event; - }, -}); -``` +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: -### Attaching Stacktraces +- `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` -> 'stacktrace' was renamed to 'attachStacktrace'. -> [Docs](https://docs.sentry.io/error-reporting/configuration/?platform=browser#attach-stacktrace) +## Deprecated `tracingOrigins` (since 7.19.0) - #6176 -_Old_: +The `tracingOrigins` option is deprecated in favor of using `shouldCreateSpanForRequest` and `tracePropagationTargets`. -```js -Raven.config('___PUBLIC_DSN___', { - stacktrace: true, -}); -``` +## Deprecate `componentTrackingPreprocessor` in Svelte SDK (since 7.16.0) - #5936 -_New_: +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. -```js -Sentry.init({ - attachStacktrace: true, -}); -``` +## Deprecate `getGlobalObject` in `@sentry/utils` (since 7.16.0) - #5949 -### Disabling Promises Handling +This is no longer used. -_Old_: +## Deprecate @sentry/hub (since 7.15.0) - #5823 -```js -Raven.config('___PUBLIC_DSN___', { - captureUnhandledRejections: false, -}); -``` +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. -_New_: +# Upgrading Sentry Replay (beta, 7.24.0) -```js -Sentry.init({ - integrations: [ - new Sentry.Integrations.GlobalHandlers({ - onunhandledrejection: false, - }), - ], -}); -``` +For details on upgrading Replay in its beta phase, please view the +[dedicated Replay MIGRATION docs](./packages/replay/MIGRATION.md). diff --git a/docs/migration/v4-to-v5_v6.md b/docs/migration/v4-to-v5_v6.md new file mode 100644 index 000000000000..6928022eef20 --- /dev/null +++ b/docs/migration/v4-to-v5_v6.md @@ -0,0 +1,404 @@ +# Upgrading from 4.x to 5.x/6.x + +We recommend upgrading from `4.x` to `6.x` directly. Migrating from `5.x` to `6.x` has no breaking changes to the SDK's API. + +In this version upgrade, there are a few breaking changes. This guide should help you update your code accordingly. + +## Integrations + +We moved optional integrations into their own package, called `@sentry/integrations`. Also, we made a few default +integrations now optional. This is probably the biggest breaking change regarding the upgrade. + +Integrations that are now opt-in and were default before: + +- Dedupe (responsible for sending the same error only once) +- ExtraErrorData (responsible for doing fancy magic, trying to extract data out of the error object using any + non-standard keys) + +Integrations that were pluggable/optional before, that also live in this package: + +- Angular (browser) +- Debug (browser/node) +- Ember (browser) +- ReportingObserver (browser) +- RewriteFrames (browser/node) +- Transaction (browser/node) +- Vue (browser) + +### How to use `@sentry/integrations`? + +Lets start with the approach if you install `@sentry/browser` / `@sentry/node` with `npm` or `yarn`. + +Given you have a `Vue` application running, in order to use the `Vue` integration you need to do the following: + +With `4.x`: + +```js +import * as Sentry from '@sentry/browser'; + +Sentry.init({ + dsn: '___PUBLIC_DSN___', + integrations: [ + new Sentry.Integrations.Vue({ + Vue, + attachProps: true, + }), + ], +}); +``` + +With `5.x` you need to install `@sentry/integrations` and change the import. + +```js +import * as Sentry from '@sentry/browser'; +import * as Integrations from '@sentry/integrations'; + +Sentry.init({ + dsn: '___PUBLIC_DSN___', + integrations: [ + new Integrations.Vue({ + Vue, + attachProps: true, + }), + ], +}); +``` + +In case you are using the CDN version or the Loader, we provide a standalone file for every integration, you can use it +like this: + +```html + + + + + + + + +``` + +## New Scope functions + +We realized how annoying it is to set a whole object using `setExtra`, so there are now a few new methods on the +`Scope`. + +```typescript +setTags(tags: { [key: string]: string | number | boolean | null | undefined }): this; +setExtras(extras: { [key: string]: any }): this; +clearBreadcrumbs(): this; +``` + +So you can do this now: + +```js +// New in 5.x setExtras +Sentry.withScope(scope => { + scope.setExtras(errorInfo); + Sentry.captureException(error); +}); + +// vs. 4.x +Sentry.withScope(scope => { + Object.keys(errorInfo).forEach(key => { + scope.setExtra(key, errorInfo[key]); + }); + Sentry.captureException(error); +}); +``` + +## Less Async API + +We removed a lot of the internal async code since in certain situations it generated a lot of memory pressure. This +really only affects you if you where either using the `BrowserClient` or `NodeClient` directly. + +So all the `capture*` functions now instead of returning `Promise` return `string | undefined`. `string` in +this case is the `event_id`, in case the event will not be sent because of filtering it will return `undefined`. + +## `close` vs. `flush` + +In `4.x` we had both `close` and `flush` on the `Client` draining the internal queue of events, helpful when you were +using `@sentry/node` on a serverless infrastructure. + +Now `close` and `flush` work similar, with the difference that if you call `close` in addition to returning a `Promise` +that you can await it also **disables** the client so it will not send any future events. + +# Migrating from `raven-js` to `@sentry/browser` + +https://docs.sentry.io/platforms/javascript/#browser-table Here are some examples of how the new SDKs work. Please note +that the API for all JavaScript SDKs is the same. + +#### Installation + +> [Docs](https://docs.sentry.io/platforms/javascript/#connecting-the-sdk-to-sentry) + +_Old_: + +```js +Raven.config('___PUBLIC_DSN___', { + release: '1.3.0', +}).install(); +``` + +_New_: + +```js +Sentry.init({ + dsn: '___PUBLIC_DSN___', + release: '1.3.0', +}); +``` + +#### Set a global tag + +> [Docs](https://docs.sentry.io/platforms/javascript/#tagging-events) + +_Old_: + +```js +Raven.setTagsContext({ key: 'value' }); +``` + +_New_: + +```js +Sentry.setTag('key', 'value'); +``` + +#### Set user context + +_Old_: + +```js +Raven.setUserContext({ + id: '123', + email: 'david@example.com', +}); +``` + +_New_: + +```js +Sentry.setUser({ + id: '123', + email: 'david@example.com', +}); +``` + +#### Capture custom exception + +> A scope must now be sent around a capture to add extra information. +> [Docs](https://docs.sentry.io/platforms/javascript/#unsetting-context) + +_Old_: + +```js +try { + throwingFunction(); +} catch (e) { + Raven.captureException(e, { extra: { debug: false } }); +} +``` + +_New_: + +```js +try { + throwingFunction(); +} catch (e) { + Sentry.withScope(scope => { + scope.setExtra('debug', false); + Sentry.captureException(e); + }); +} +``` + +#### Capture a message + +> A scope must now be sent around a capture to add extra information. +> [Docs](https://docs.sentry.io/platforms/javascript/#unsetting-context) + +_Old_: + +```js +Raven.captureMessage('test1', 'info'); +Raven.captureMessage('test2', 'info', { extra: { debug: false } }); +``` + +_New_: + +```js +Sentry.captureMessage('test1', 'info'); +Sentry.withScope(scope => { + scope.setExtra('debug', false); + Sentry.captureMessage('test2', 'info'); +}); +``` + +#### Breadcrumbs + +> [Docs](https://docs.sentry.io/platforms/javascript/#breadcrumbs) + +_Old_: + +```js +Raven.captureBreadcrumb({ + message: 'Item added to shopping cart', + category: 'action', + data: { + isbn: '978-1617290541', + cartSize: '3', + }, +}); +``` + +_New_: + +```js +Sentry.addBreadcrumb({ + message: 'Item added to shopping cart', + category: 'action', + data: { + isbn: '978-1617290541', + cartSize: '3', + }, +}); +``` + +### Ignoring Urls + +> 'ignoreUrls' was renamed to 'denyUrls'. 'ignoreErrors', which has a similar name was not renamed. +> [Docs](https://docs.sentry.io/error-reporting/configuration/?platform=browser#deny-urls) and +> [Decluttering Sentry](https://docs.sentry.io/platforms/javascript/#decluttering-sentry) + +_Old_: + +```js +Raven.config('___PUBLIC_DSN___', { + ignoreUrls: ['https://www.baddomain.com', /graph\.facebook\.com/i], +}); +``` + +_New_: + +```js +Sentry.init({ + denyUrls: ['https://www.baddomain.com', /graph\.facebook\.com/i], +}); +``` + +### Ignoring Events (`shouldSendCallback`) + +> `shouldSendCallback` was renamed to `beforeSend` +> ([#2253](https://github.com/getsentry/sentry-javascript/issues/2253)). Instead of returning `false`, you must return +> `null` to omit sending the event. +> [Docs](https://docs.sentry.io/error-reporting/configuration/filtering/?platform=browser#before-send) + +_Old_: + +```js +Raven.config('___PUBLIC_DSN___', { + shouldSendCallback(event) { + // Only send events that include user data + if (event.user) { + return true; + } + return false; + }, +}); +``` + +_New_: + +```js +Sentry.init({ + beforeSend(event) { + if (event.user) { + return event; + } + return null; + }, +}); +``` + +### Modifying Events (`dataCallback`) + +_Old_: + +```js +Raven.config('___PUBLIC_DSN___', { + dataCallback(event) { + if (event.user) { + // Don't send user's email address + delete event.user.email; + } + return event; + }, +}); +``` + +_New_: + +```js +Sentry.init({ + beforeSend(event) { + if (event.user) { + delete event.user.email; + } + return event; + }, +}); +``` + +### Attaching Stacktraces + +> 'stacktrace' was renamed to 'attachStacktrace'. +> [Docs](https://docs.sentry.io/error-reporting/configuration/?platform=browser#attach-stacktrace) + +_Old_: + +```js +Raven.config('___PUBLIC_DSN___', { + stacktrace: true, +}); +``` + +_New_: + +```js +Sentry.init({ + attachStacktrace: true, +}); +``` + +### Disabling Promises Handling + +_Old_: + +```js +Raven.config('___PUBLIC_DSN___', { + captureUnhandledRejections: false, +}); +``` + +_New_: + +```js +Sentry.init({ + integrations: [ + new Sentry.Integrations.GlobalHandlers({ + onunhandledrejection: false, + }), + ], +}); +``` diff --git a/docs/migration/v6-to-v7.md b/docs/migration/v6-to-v7.md new file mode 100644 index 000000000000..ac6ce0519e8e --- /dev/null +++ b/docs/migration/v6-to-v7.md @@ -0,0 +1,544 @@ +# Upgrading from 6.x to 7.x + +The v7 version of the JavaScript SDK requires a self-hosted version of Sentry 20.6.0 or higher. + +The main goal of version 7 is to reduce bundle size. This version is breaking because we removed deprecated APIs, +upgraded our build tooling, and restructured npm package contents. Below we will outline all the breaking changes you +should consider when upgrading. + +**TL;DR** If you only use basic features of Sentry, or you simply copy & pasted the setup examples from our docs, here's +what changed for you: + +- If you installed additional Sentry packages, such as`@sentry/tracing` alongside your Sentry SDK (e.g. `@sentry/react` + or `@sentry/node`), make sure to upgrade all of them to version 7. +- Our CDN bundles are now ES6 - you will need to [reconfigure your script tags](#renaming-of-cdn-bundles) if you want to + keep supporting ES5 and IE11 on the new SDK version. +- Distributed CommonJS files will be ES6. Use a transpiler if you need to support old node versions. +- We bumped the TypeScript version we generate our types with to 3.8.3. Please check if your TypeScript projects using + TypeScript version 3.7 or lower still compile. Otherwise, upgrade your TypeScript version. +- `whitelistUrls` and `blacklistUrls` have been renamed to `allowUrls` and `denyUrls` in the `Sentry.init()` options. +- The `UserAgent` integration is now called `HttpContext`. +- If you are using Performance Monitoring and with tracing enabled, you might have to + [make adjustments to your server's CORS settings](#propagation-of-baggage-header) + +## Dropping Support for Node.js v6 + +Node.js version 6 has reached end of life in April 2019. For Sentry JavaScript SDK version 7, we will no longer be +supporting version 6 of Node.js. + +As far as SDK development goes, dropping support means no longer running integration tests for Node.js version 6, and +also no longer handling edge cases specific to version 6. Running the new SDK version on Node.js v6 is therefore highly +discouraged. + +## Removal of `@sentry/minimal` + +The `@sentry/minimal` package was deleted and it's functionality was moved to `@sentry/hub`. All exports from +`@sentry/minimal` should be available in `@sentry/hub` other than `_callOnClient` function which was removed. + +```ts +// New in v7: +import { addBreadcrumb, captureException, configureScope, setTag } from '@sentry/hub'; + +// Before: +import { addBreadcrumb, captureException, configureScope, setTag } from '@sentry/minimal'; +``` + +## Explicit Client Options + +In v7, we've updated the `Client` to have options separate from the options passed into `Sentry.init`. This means that +constructing a client now requires 3 options: `integrations`, `transport` and `stackParser`. These can be customized as +you see fit. + +```ts +import { BrowserClient, defaultStackParser, defaultIntegrations, makeFetchTransport } from '@sentry/browser'; + +// New in v7: +const client = new BrowserClient({ + transport: makeFetchTransport, + stackParser: defaultStackParser, + integrations: defaultIntegrations, +}); + +// Before: +const client = new BrowserClient(); +``` + +Since you now explicitly pass in the dependencies of the client, you can also tree-shake out dependencies that you do +not use this way. For example, you can tree-shake out the SDK's default integrations and only use the ones that you want +like so: + +```ts +import { + BrowserClient, + Breadcrumbs, + Dedupe, + defaultStackParser, + GlobalHandlers, + Integrations, + makeFetchTransport, + LinkedErrors, +} from '@sentry/browser'; + +// New in v7: +const client = new BrowserClient({ + transport: makeFetchTransport, + stackParser: defaultStackParser, + integrations: [new Breadcrumbs(), new GlobalHandlers(), new LinkedErrors(), new Dedupe()], +}); +``` + +## Removal Of Old Platform Integrations From `@sentry/integrations` Package + +The following classes will be removed from the `@sentry/integrations` package and can no longer be used: + +- `Angular` +- `Ember` +- `Vue` + +These classes have been superseded and were moved into their own packages, `@sentry/angular`, `@sentry/ember`, and +`@sentry/vue` in a previous version. Refer to those packages if you want to integrate Sentry into your Angular, Ember, +or Vue application. + +## Moving To ES6 For CommonJS Files + +From version 7 onwards, the CommonJS files in Sentry JavaScript SDK packages will use ES6. + +If you need to support Internet Explorer 11 or old Node.js versions, we recommend using a preprocessing tool like +[Babel](https://babeljs.io/) to convert Sentry packages to ES5. + +## Renaming Of CDN Bundles + +CDN bundles will be ES6 by default. Files that followed the naming scheme `bundle.es6.min.js` were renamed to +`bundle.min.js` and any bundles using ES5 (files without `.es6`) turned into `bundle.es5.min.js`. + +See our [docs on CDN bundles](https://docs.sentry.io/platforms/javascript/install/cdn/) for more information. + +## Restructuring Of Package Content + +Up until v6.x, we have published our packages on npm with the following structure: + +- `build` folder contained CDN bundles +- `dist` folder contained CommonJS files and TypeScript declarations +- `esm` folder contained ESM files and TypeScript declarations + +Moving forward the JavaScript SDK packages will generally have the following structure: + +- `cjs` folder contains CommonJS files +- `esm` folder contains ESM files +- `types` folder contains TypeScript declarations + +**CDN bundles of version 7 or higher will no longer be distributed through our npm package.** This means that most +third-party CDNs like [unpkg](https://unpkg.com/) or [jsDelivr](https://www.jsdelivr.com/) will also not provide them. + +If you depend on any specific files in a Sentry JavaScript npm package, you will most likely need to update their +references. For example, imports on `@sentry/browser/dist/client` will become `@sentry/browser/cjs/client`. However, +directly importing from specific files is discouraged. + +## Removing the `API` class from `@sentry/core` + +The internal `API` class was removed in favor of using client options explicitly. + +```js +// New in v7: +import { + initAPIDetails, + getEnvelopeEndpointWithUrlEncodedAuth, + getStoreEndpointWithUrlEncodedAuth, +} from '@sentry/core'; + +const client = getCurrentHub().getClient(); +const dsn = client.getDsn(); +const options = client.getOptions(); +const envelopeEndpoint = getEnvelopeEndpointWithUrlEncodedAuth(dsn, options.tunnel); + +// Before: +import { API } from '@sentry/core'; + +const api = new API(dsn, metadata, tunnel); +const dsn = api.getDsn(); +const storeEndpoint = api.getStoreEndpointWithUrlEncodedAuth(); +const envelopeEndpoint = api.getEnvelopeEndpointWithUrlEncodedAuth(); +``` + +## Transport Changes + +The `Transport` API was simplified and some functionality (e.g. APIDetails and client reports) was refactored and moved +to the Client. To send data to Sentry, we switched from the previously used +[Store endpoint](https://develop.sentry.dev/sdk/store/) to the +[Envelopes endpoint](https://develop.sentry.dev/sdk/envelopes/). + +This example shows the new v7 and the v6 Transport API: + +```js +// New in v7: +export interface Transport { + /* Sends an envelope to the Envelope endpoint in Sentry */ + send(request: Envelope): PromiseLike; + /* Waits for all events to be sent or the timeout to expire, whichever comes first */ + flush(timeout?: number): PromiseLike; +} + +// Before: +export interface Transport { + /* Sends the event to the Store endpoint in Sentry */ + sendEvent(event: Event): PromiseLike; + /* Sends the session to the Envelope endpoint in Sentry */ + sendSession?(session: Session | SessionAggregates): PromiseLike; + /* Waits for all events to be sent or the timeout to expire, whichever comes first */ + close(timeout?: number): PromiseLike; + /* Increment the counter for the specific client outcome */ + recordLostEvent?(type: Outcome, category: SentryRequestType): void; +} +``` + +### Custom Transports + +If you rely on a custom transport, you will need to make some adjustments to how it is created when migrating to v7. +Note that we changed our transports from a class-based to a functional approach, meaning that the previously class-based +transports are now created via functions. This also means that custom transports are now passed by specifying a factory +function in the `Sentry.init` options object instead passing the custom transport's class. + +The following example shows how to create a custom transport in v7 vs. how it was done in v6: + +```js +// New in v7: +import { BaseTransportOptions, Transport, TransportMakeRequestResponse, TransportRequest } from '@sentry/types'; +import { createTransport } from '@sentry/core'; + +export function makeMyCustomTransport(options: BaseTransportOptions): Transport { + function makeRequest(request: TransportRequest): PromiseLike { + // this is where your sending logic goes + const myCustomRequest = { + body: request.body, + url: options.url + }; + // you define how `sendMyCustomRequest` works + return sendMyCustomRequest(myCustomRequest).then(response => ({ + headers: { + 'x-sentry-rate-limits': response.headers.get('X-Sentry-Rate-Limits'), + 'retry-after': response.headers.get('Retry-After'), + }, + })); + } + + // `createTransport` takes care of rate limiting and flushing + return createTransport(options, makeRequest); +} + +Sentry.init({ + dsn: '...', + transport: makeMyCustomTransport, // this function will be called when the client is initialized + ... +}) + +// Before: +class MyCustomTransport extends BaseTransport { + constructor(options: TransportOptions) { + // initialize your transport here + super(options); + } + + public sendEvent(event: Event): PromiseLike { + // this is where your sending logic goes + // `url` is decoded from dsn in BaseTransport + const myCustomRequest = createMyCustomRequestFromEvent(event, this.url); + return sendMyCustomRequest(myCustomRequest).then(() => resolve({status: 'success'})); + } + + public sendSession(session: Session): PromiseLike {...} + // ... +} + +Sentry.init({ + dsn: '...', + transport: MyCustomTransport, // the constructor was called when the client was initialized + ... +}) +``` + +Overall, the new way of transport creation allows you to create your custom sending implementation without having to +deal with the conversion of events or sessions to envelopes. We recommend calling using the `createTransport` function +from `@sentry/core` as demonstrated in the example above which, besides creating the `Transport` object with your custom +logic, will also take care of rate limiting and flushing. + +For a complete v7 transport implementation, take a look at our +[browser fetch transport](https://github.com/getsentry/sentry-javascript/blob/ebc938a03d6efe7d0c4bbcb47714e84c9a566a9c/packages/browser/src/transports/fetch.ts#L1-L34). + +### Node Transport Changes + +To clean up the options interface, we now require users to pass down transport related options under the +`transportOptions` key. The options that were changed were `caCerts`, `httpProxy`, and `httpsProxy`. In addition, +`httpProxy` and `httpsProxy` were unified to a single option under the `transportOptions` key, `proxy`. + +```ts +// New in v7: +Sentry.init({ + dsn: '...', + transportOptions: { + caCerts: getMyCaCert(), + proxy: 'http://example.com', + }, +}); + +// Before: +Sentry.init({ + dsn: '...', + caCerts: getMyCaCert(), + httpsProxy: 'http://example.com', +}); +``` + +## Enum Changes + +Given that enums have a high bundle-size impact, our long term goal is to eventually remove all enums from the SDK in +favor of string literals. + +### Removed Enums + +- The previously deprecated enum `Status` was removed (see + [#4891](https://github.com/getsentry/sentry-javascript/pull/4891)). +- The previously deprecated internal-only enum `RequestSessionStatus` was removed (see + [#4889](https://github.com/getsentry/sentry-javascript/pull/4889)) in favor of string literals. +- The previously deprecated internal-only enum `SessionStatus` was removed (see + [#4890](https://github.com/getsentry/sentry-javascript/pull/4890)) in favor of string literals. + +### Deprecated Enums + +The two enums `SpanStatus`, and `Severity` remain deprecated, as we decided to limit the number of high-impact breaking +changes in v7. They will be removed in the next major release which is why we strongly recommend moving to the +corresponding string literals. Here's how to adjust [`Severity`](#severity-severitylevel-and-severitylevels) and +[`SpanStatus`](#spanstatus). + +## Session Changes + +Note: These changes are not relevant for the majority of Sentry users but if you are building an SDK on top of the +Javascript SDK, you might need to make some adaptions. The internal `Session` class was refactored and replaced with a +more functional approach in [#5054](https://github.com/getsentry/sentry-javascript/pull/5054). Instead of the class, we +now export a `Session` interface from `@sentry/types` and three utility functions to create and update a `Session` +object from `@sentry/hub`. This short example shows what has changed and how to deal with the new functions: + +```js +// New in v7: +import { makeSession, updateSession, closeSession } from '@sentry/hub'; + +const session = makeSession({ release: 'v1.0' }); +updateSession(session, { environment: 'prod' }); +closeSession(session, 'ok'); + +// Before: +import { Session } from '@sentry/hub'; + +const session = new Session({ release: 'v1.0' }); +session.update({ environment: 'prod' }); +session.close('ok'); +``` + +## Propagation of Baggage Header + +We introduced a new way of propagating tracing and transaction-related information between services. This change adds +the [`baggage` HTTP header](https://www.w3.org/TR/baggage/) to outgoing requests if the instrumentation of requests is +enabled. Since this adds a header to your HTTP requests, you might need to adjust your Server's CORS settings to allow +this additional header. Take a look at the +[Sentry docs](https://docs.sentry.io/platforms/javascript/performance/connect-services/#navigation-and-other-xhr-requests) +for more in-depth instructions what to change. + +## General API Changes + +For our efforts to reduce bundle size of the SDK we had to remove and refactor parts of the package which introduced a +few changes to the API: + +- Remove support for deprecated `@sentry/apm` package. `@sentry/tracing` should be used instead. +- Remove deprecated `user` field from DSN. `publicKey` should be used instead. +- Remove deprecated `whitelistUrls` and `blacklistUrls` options from `Sentry.init`. They have been superseded by + `allowUrls` and `denyUrls` specifically. See + [our docs page on inclusive language](https://develop.sentry.dev/inclusion/) for more details. +- Gatsby SDK: Remove `Sentry` from `window` object. +- Remove deprecated `Status`, `SessionStatus`, and `RequestSessionStatus` enums. These were only part of an internal + API. If you are using these enums, we encourage you to to look at + [b177690d](https://github.com/getsentry/sentry-javascript/commit/b177690d89640aef2587039113c614672c07d2be), + [5fc3147d](https://github.com/getsentry/sentry-javascript/commit/5fc3147dfaaf1a856d5923e4ba409479e87273be), and + [f99bdd16](https://github.com/getsentry/sentry-javascript/commit/f99bdd16539bf6fac14eccf1a974a4988d586b28) to to see + the changes we've made to our code as result. We generally recommend using string literals instead of the removed + enums. +- Remove 'critical' severity. +- Remove deprecated `getActiveDomain` method and `DomainAsCarrier` type from `@sentry/hub`. +- Rename `registerRequestInstrumentation` to `instrumentOutgoingRequests` in `@sentry/tracing`. +- Remove `Backend` and port its functionality into `Client` (see + [#4911](https://github.com/getsentry/sentry-javascript/pull/4911) and + [#4919](https://github.com/getsentry/sentry-javascript/pull/4919)). `Backend` was an unnecessary abstraction which is + not present in other Sentry SDKs. For the sake of reducing complexity, increasing consistency with other Sentry SDKs + and decreasing bundle-size, `Backend` was removed. +- Remove support for Opera browser pre v15. +- Rename `UserAgent` integration to `HttpContext`. (see + [#5027](https://github.com/getsentry/sentry-javascript/pull/5027)) +- Remove `SDK_NAME` export from `@sentry/browser`, `@sentry/node`, `@sentry/tracing` and `@sentry/vue` packages. +- Removed `eventStatusFromHttpCode` to save on bundle size. +- Replace `BrowserTracing` `maxTransactionDuration` option with `finalTimeout` option +- Removed `ignoreSentryErrors` option from AWS lambda SDK. Errors originating from the SDK will now _always_ be caught + internally. +- Removed `Integrations.BrowserTracing` export from `@sentry/nextjs`. Please import `BrowserTracing` from + `@sentry/nextjs` directly. +- Removed static `id` property from `BrowserTracing` integration. +- Removed usage of deprecated `event.stacktrace` field + +## Sentry Angular SDK Changes + +The Sentry Angular SDK (`@sentry/angular`) is now compiled with the Angular compiler (see +[#4641](https://github.com/getsentry/sentry-javascript/pull/4641)). This change was necessary to fix a long-lasting bug +in the SDK (see [#3282](https://github.com/getsentry/sentry-javascript/issues/3282)): `TraceDirective` and `TraceModule` +can now be used again without risking an application compiler error or having to disable AOT compilation. + +### Angular Version Compatibility + +As in v6, we continue to list Angular 10-13 in our peer dependencies, meaning that these are the Angular versions we +officially support. If you are using v7 with Angular <10 in your project and you experience problems, we recommend +staying on the latest 6.x version until you can upgrade your Angular version. As v7 of our SDK is compiled with the +Angular 10 compiler and we upgraded our Typescript version, the SDK will work with Angular 10 and above. Tests have +shown that Angular 9 seems to work as well (use at your own risk) but we recommend upgrading to a more recent Angular +version. + +### Import Changes + +Due to the compiler change, our NPM package structure changed as well as it now conforms to the +[Angular Package Format v10](https://docs.google.com/document/d/1uh2D6XqaGh2yjjXwfF4SrJqWl1MBhMPntlNBBsk6rbw/edit). In +case you're importing from specific paths other than `@sentry/angular` you will have to adjust these paths. As an +example, `import ... from '@sentry/angular/esm/injex.js'` should be changed to +`import ... from '@sentry/angular/esm2015/index.js'`. Generally, we strongly recommend only importing from +`@sentry/angular`. + +# Upgrading from 6.17.x to 6.18.0 + +Version 6.18.0 deprecates the `frameContextLines` top-level option for the Node SDK. This option will be removed in an +upcoming major version. To migrate off of the top-level option, pass it instead to the new `ContextLines` integration. + +```js +// New in 6.18.0 +init({ + dsn: '__DSN__', + integrations: [new ContextLines({ frameContextLines: 10 })], +}); + +// Before: +init({ + dsn: '__DSN__', + frameContextLines: 10, +}); +``` + +# Upgrading from 6.x to 6.17.x + +You only need to make changes when migrating to `6.17.x` if you are using our internal `Dsn` class. Our internal API +class and typescript enums were deprecated, so we recommend you migrate them as well. + +The internal `Dsn` class was removed in `6.17.0`. For additional details, you can look at the +[PR where this change happened](https://github.com/getsentry/sentry-javascript/pull/4325). To migrate, see the following +example. + +```js +// New in 6.17.0: +import { dsnToString, makeDsn } from '@sentry/utils'; + +const dsn = makeDsn(process.env.SENTRY_DSN); +console.log(dsnToString(dsn)); + +// Before: +import { Dsn } from '@sentry/utils'; + +const dsn = new Dsn(process.env.SENTRY_DSN); +console.log(dsn.toString()); +``` + +The internal API class was deprecated, and will be removed in the next major release. More details can be found in the +[PR that made this change](https://github.com/getsentry/sentry-javascript/pull/4281). To migrate, see the following +example. + +```js +// New in 6.17.0: +import { + initAPIDetails, + getEnvelopeEndpointWithUrlEncodedAuth, + getStoreEndpointWithUrlEncodedAuth, +} from '@sentry/core'; + +const dsn = initAPIDetails(dsn, metadata, tunnel); +const dsn = api.dsn; +const storeEndpoint = getStoreEndpointWithUrlEncodedAuth(api.dsn); +const envelopeEndpoint = getEnvelopeEndpointWithUrlEncodedAuth(api.dsn, api.tunnel); + +// Before: +import { API } from '@sentry/core'; + +const api = new API(dsn, metadata, tunnel); +const dsn = api.getDsn(); +const storeEndpoint = api.getStoreEndpointWithUrlEncodedAuth(); +const envelopeEndpoint = api.getEnvelopeEndpointWithUrlEncodedAuth(); +``` + +## Enum changes + +The enums `Status`, `SpanStatus`, and `Severity` were deprecated, and we've detailed how to migrate away from them +below. We also deprecated the `TransactionMethod`, `Outcome` and `RequestSessionStatus` enums, but those are +internal-only APIs. If you are using them, we encourage you to take a look at the corresponding PRs to see how we've +changed our code as a result. + +- `TransactionMethod`: https://github.com/getsentry/sentry-javascript/pull/4314 +- `Outcome`: https://github.com/getsentry/sentry-javascript/pull/4315 +- `RequestSessionStatus`: https://github.com/getsentry/sentry-javascript/pull/4316 + +#### Status + +We deprecated the `Status` enum in `@sentry/types` and it will be removed in the next major release. We recommend using +string literals to save on bundle size. [PR](https://github.com/getsentry/sentry-javascript/pull/4298). We also removed +the `Status.fromHttpCode` method. This was done to save on bundle size. + +```js +// New in 6.17.0: +import { eventStatusFromHttpCode } from '@sentry/utils'; + +const status = eventStatusFromHttpCode(500); + +// Before: +import { Status } from '@sentry/types'; + +const status = Status.fromHttpCode(500); +``` + +#### SpanStatus + +We deprecated the `Status` enum in `@sentry/tracing` and it will be removed in the next major release. We recommend +using string literals to save on bundle size. [PR](https://github.com/getsentry/sentry-javascript/pull/4299). We also +removed the `SpanStatus.fromHttpCode` method. This was done to save on bundle size. + +```js +// New in 6.17.0: +import { spanStatusfromHttpCode } from '@sentry/tracing'; + +const status = spanStatusfromHttpCode(403); + +// Before: +import { SpanStatus } from '@sentry/tracing'; + +const status = SpanStatus.fromHttpCode(403); +``` + +#### Severity, SeverityLevel, and SeverityLevels + +We deprecated the `Severity` enum in `@sentry/types` and it will be removed in the next major release. We recommend +using string literals (typed as `SeverityLevel`) to save on bundle size. + +```js +// New in 6.17.5: +import { SeverityLevel } from '@sentry/types'; + +const levelA = "error" as SeverityLevel; + +const levelB: SeverityLevel = "error" + +// Before: +import { Severity, SeverityLevel } from '@sentry/types'; + +const levelA = Severity.error; + +const levelB: SeverityLevel = "error" +``` + From f2c6378bc75e092a279f82f14f076b696467362c Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Thu, 29 Feb 2024 10:15:28 -0500 Subject: [PATCH 2/3] address PR review --- MIGRATION.md | 74 +++++++++++++++++++++++++++------------------------- 1 file changed, 38 insertions(+), 36 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 7e28becbe2b4..be04748e9a7e 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -20,7 +20,7 @@ stable release of `8.x` comes out). ## 1. Version Support changes: -**Node.js**: We now official support Node 14+ for our CJS package, and Node 18.8+ for our ESM package. This applies to +**Node.js**: We now official support Node 14.8+ for our CJS package, and Node 18.8+ 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. @@ -62,7 +62,7 @@ We've removed the following packages: For Browser SDKs you can import `BrowserTracing` from the SDK directly: ```js -// Before +// Before (v7) import * as Sentry from '@sentry/browser'; import { BrowserTracing } from '@sentry/tracing'; @@ -72,7 +72,7 @@ Sentry.init({ integrations: [new BrowserTracing()], }); -// After +// After (v8) import * as Sentry from '@sentry/browser'; Sentry.init({ @@ -86,7 +86,7 @@ If you were importing `@sentry/tracing` for the side effect, you can now use `Se tracing extensions to the SDK. `addTracingExtensions` replaces the `addExtensionMethods` method from `@sentry/tracing`. ```js -// Before +// Before (v7) import * as Sentry from '@sentry/browser'; import '@sentry/tracing'; @@ -95,7 +95,7 @@ Sentry.init({ tracesSampleRate: 1.0, }); -// After +// After (v8) import * as Sentry from '@sentry/browser'; Sentry.addTracingExtensions(); @@ -103,14 +103,13 @@ Sentry.addTracingExtensions(); Sentry.init({ dsn: '__DSN__', tracesSampleRate: 1.0, - integrations: [new Sentry.BrowserTracing()], }); ``` For Node SDKs you no longer need the side effect import, you can remove all references to `@sentry/tracing`. ```js -// Before +// Before (v7) const Sentry = require('@sentry/node'); require('@sentry/tracing'); @@ -119,7 +118,7 @@ Sentry.init({ tracesSampleRate: 1.0, }); -// After +// Before (v8) const Sentry = require('@sentry/node'); Sentry.init({ @@ -135,28 +134,28 @@ package (`@sentry/integrations`) to `@sentry/browser` and `@sentry/node`. in add classes. ```js -// before +// Before (v7) import { RewriteFrames } from '@sentry/integrations'; -// after +// After (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`) +- `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_ +- `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. @@ -302,10 +301,10 @@ The `getIntegration()` and `getIntegrationById()` have been removed entirely, se [below](./MIGRATION.md#deprecate-getintegration-and-getintegrationbyid). ```js -// before +// Before (v7) const replay = Sentry.getIntegration(Replay); -// after +// After (v8) const replay = getClient().getIntegrationByName('Replay'); ``` @@ -317,16 +316,19 @@ 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 -// Before (Browser) +// Before (v7) Sentry.init({ dsn: '__DSN__', - integrations: [new Sentry.BrowserTracing({})], + integrations: [new Sentry.BrowserTracing({ tracingOrigins: ['localhost', 'example.com'] })], }); -// After +// After (v8) Sentry.init({ dsn: '__DSN__', + integrations: [Sentry.browserTracingIntegration()], tracePropagationTargets: ['localhost', 'example.com'], }); ``` @@ -336,7 +338,7 @@ Sentry.init({ The SDKs now support metrics features without any additional configuration. ```ts -// before +// Before (v7) // Server (Node/Deno/Bun) Sentry.init({ dsn: '__DSN__', @@ -345,13 +347,14 @@ Sentry.init({ }, }); +// Before (v7) // Browser Sentry.init({ dsn: '__DSN__', integrations: [Sentry.metricsAggregatorIntegration()], }); -// after +// After (v8) Sentry.init({ dsn: '__DSN__', }); @@ -363,14 +366,14 @@ In v7 we deprecated the `Severity` enum in favor of using the `SeverityLevel` ty this has been removed in v8. You should now use the `SeverityLevel` type directly. ```js -// Before: +// Before (v7) import { Severity, SeverityLevel } from '@sentry/types'; const levelA = Severity.error; const levelB: SeverityLevel = "error" -// After +// After (v8) import { SeverityLevel } from '@sentry/types'; const levelA = "error" as SeverityLevel; @@ -384,12 +387,12 @@ The top level `Sentry.configureScope` function has been removed. Instead, you sh to access and mutate the current scope. ```js -// Before +// Before (v7) Sentry.configureScope(scope => { scope.setTag('key', 'value'); }); -// After +// After (v8) Sentry.getCurrentScope().setTag('key', 'value'); ``` @@ -403,10 +406,10 @@ Internally, this class is now called `SentrySpan`, and it is no longer meant to In v8, we are removing the `spanStatusfromHttpCode` function in favor of `getSpanStatusFromHttpCode`. ```js -// before +// Before (v7) const spanStatus = spanStatusfromHttpCode(200); -// after +// After (v8) const spanStatus = getSpanStatusFromHttpCode(200); ``` @@ -415,13 +418,13 @@ const spanStatus = getSpanStatusFromHttpCode(200); In v8, we are removing the `addGlobalEventProcessor` function in favor of `addEventProcessor`. ```js -// before +// Before (v7) addGlobalEventProcessor(event => { delete event.extra; return event; }); -// after +// After (v8) addEventProcessor(event => { delete event.extra; return event; @@ -661,7 +664,7 @@ Sentry.init({ integrations: [Sentry.browserTracingIntegration()], }); -// You still need to add the Trace Service like before! +// You still need to add the TraceService like before! ``` ### `@sentry/remix` @@ -963,7 +966,6 @@ callback. ```js // Before - Sentry.init({ beforeSend(event, hint) { const lastCapturedEventId = Sentry.lastEventId(); From 486f63bfd1d4623c2059ef27083c67152a39be59 Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Thu, 29 Feb 2024 10:27:56 -0500 Subject: [PATCH 3/3] lint fix --- MIGRATION.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index be04748e9a7e..30206739b42e 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -504,14 +504,15 @@ The following previously deprecated API has been removed from the `@sentry/nextj #### 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: +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 + headers: false, }, }), ], @@ -574,7 +575,9 @@ Sentry was actually initialized, using `getClient()` will thus not work anymore. #### 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. +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. # Deprecations in 7.x