diff --git a/MIGRATION.md b/MIGRATION.md index 0ab76f759ab7..30206739b42e 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -1,300 +1,724 @@ -# 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.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. -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 (v7) +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 (v8) +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 (v7) +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 (v8) +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, +}); +``` -`@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 (v7) +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) +// Before (v8) +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 (v7) +import { RewriteFrames } from '@sentry/integrations'; -We moved pluggable integrations from their own package (`@sentry/integrations`) to `@sentry/browser` and `@sentry/node`. +// After (v8) +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) + +### Performance Monitoring API + +The APIs for Performance Monitoring in the SDK have been revamped to align with OpenTelemetry, an open standard for +tracing and metrics. This allows us to provide a more consistent and powerful API for performance monitoring, and adds +support for a variety of new integrations out of the box for our Node SDK. + +Instead of using `startTransaction` and `span.startChild`, you rely on new helper methods to create spans top level +helpers to create spans. + +```js +// Measure how long a callback takes, `startSpan` returns the value of the callback. +// The span will become the "active span" for the duration of the callback. +const value = Sentry.startSpan({ name: 'mySpan' }, span => { + span.setAttribute('key', 'value'); + return expensiveFunction(); +}); + +// `startSpan` works with async callbacks as well - just make sure to return a promise! +const value = await Sentry.startSpan({ name: 'mySpan' }, async span => { + span.setAttribute('key', 'value'); + return await expensiveFunction(); +}); + +// You can nest spans via more `startSpan` calls. +const value = Sentry.startSpan({ name: 'mySpan' }, span => { + span.setAttribute('key1', 'value1'); + + // `nestedSpan` becomes the child of `mySpan`. + return Sentry.startSpan({ name: 'nestedSpan' }, nestedSpan => { + nestedSpan.setAttribute('key2', 'value2'); + return expensiveFunction(); + }); +}); + +// You can also create an inactive span that does not take a callback. +// Useful when you need to pass a span reference into another closure (like measuring duration between hooks). +const span = Sentry.startInactiveSpan({ name: 'mySpan' }); + +// Use `startSpanManual` if you want to manually control when to end the span +// Useful when you need to hook into event emitters or similar. +function middleware(res, req, next) { + return Sentry.startSpanManual({ name: 'mySpan' }, span => { + res.on('finish', () => { + span.end(); + }); + return next(); + }); +} ``` -This will let you select which updates to run, and automatically update your code. Make sure to still review all code -changes! +You can [read more about the new performance APIs here](./docs/v8-new-performance-apis.md). -## Depreacted `BrowserTracing` integration +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()` -The `BrowserTracing` integration, together with the custom routing instrumentations passed to it, are deprecated in v8. -Instead, you should use `Sentry.browserTracingIntegration()`. +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. -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: +See [Deprecate Hub](./MIGRATION.md#deprecate-hub) for details on how to replace existing usage of the Hub APIs. -### `@sentry/browser`, `@sentry/svelte`, `@sentry/gatsby` +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/browser'; +// Before (v7) +const replay = Sentry.getIntegration(Replay); + +// After (v8) +const replay = getClient().getIntegrationByName('Replay'); +``` + +#### `tracingOrigins` has been replaced by `tracePropagationTargets` + +`tracingOrigins` is now removed in favor of the `tracePropagationTargets` option. The `tracePropagationTargets` option +should be set in the `Sentry.init()` options, or in your custom `Client`s option if you create them. We've also updated +the behavior of the `tracePropagationTargets` option for Browser SDKs, see +[below](./MIGRATION.md/#updated-behaviour-of-tracepropagationtargets-in-the-browser-http-tracing-headers--cors) for more +details. + +For example for the Browser SDKs: +```ts +// Before (v7) +Sentry.init({ + dsn: '__DSN__', + integrations: [new Sentry.BrowserTracing({ tracingOrigins: ['localhost', 'example.com'] })], +}); + +// After (v8) Sentry.init({ + dsn: '__DSN__', integrations: [Sentry.browserTracingIntegration()], + tracePropagationTargets: ['localhost', 'example.com'], }); ``` -### `@sentry/react` +#### Removal of the `MetricsAggregator` integration class and `metricsAggregatorIntegration` -```js -import * as Sentry from '@sentry/react'; +The SDKs now support metrics features without any additional configuration. +```ts +// Before (v7) +// Server (Node/Deno/Bun) 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, - }), - ], + dsn: '__DSN__', + _experiments: { + metricsAggregator: true, + }, }); -``` - -### `@sentry/vue` -```js -import * as Sentry from '@sentry/vue'; +// Before (v7) +// Browser +Sentry.init({ + dsn: '__DSN__', + integrations: [Sentry.metricsAggregatorIntegration()], +}); +// After (v8) Sentry.init({ - integrations: [ - Sentry.browserTracingIntegration({ - // pass router in, if applicable - router, - }), - ], + dsn: '__DSN__', }); ``` -### `@sentry/angular` & `@sentry/angular-ivy` +#### Removal of Severity Enum + +In v7 we deprecated the `Severity` enum in favor of using the `SeverityLevel` type as this helps save bundle size, and +this has been removed in v8. You should now use the `SeverityLevel` type directly. ```js -import * as Sentry from '@sentry/angular'; +// Before (v7) +import { Severity, SeverityLevel } from '@sentry/types'; -Sentry.init({ - integrations: [Sentry.browserTracingIntegration()], +const levelA = Severity.error; + +const levelB: SeverityLevel = "error" + +// After (v8) +import { SeverityLevel } from '@sentry/types'; + +const levelA = "error" as SeverityLevel; + +const levelB: SeverityLevel = "error" +``` + +#### Removal of `Sentry.configureScope` method + +The top level `Sentry.configureScope` function has been removed. Instead, you should use the `Sentry.getCurrentScope()` +to access and mutate the current scope. + +```js +// Before (v7) +Sentry.configureScope(scope => { + scope.setTag('key', 'value'); }); -// You still need to add the Trace Service like before! +// After (v8) +Sentry.getCurrentScope().setTag('key', 'value'); ``` -### `@sentry/remix` +#### Removal of `Span` class export from SDK packages + +In v8, we are no longer exporting the `Span` class from SDK packages (e.g. `@sentry/browser` or `@sentry/node`). +Internally, this class is now called `SentrySpan`, and it is no longer meant to be used by users directly. + +#### Removal of `spanStatusfromHttpCode` in favour of `getSpanStatusFromHttpCode` + +In v8, we are removing the `spanStatusfromHttpCode` function in favor of `getSpanStatusFromHttpCode`. ```js -import * as Sentry from '@sentry/remix'; +// Before (v7) +const spanStatus = spanStatusfromHttpCode(200); -Sentry.init({ - integrations: [ - Sentry.browserTracingIntegration({ - useEffect, - useLocation, - useMatches, - }), - ], -}); +// After (v8) +const spanStatus = getSpanStatusFromHttpCode(200); ``` -### `@sentry/nextjs`, `@sentry/astro`, `@sentry/sveltekit` +#### Removal of `addGlobalEventProcessor` in favour of `addEventProcessor` -Browser tracing is automatically set up for you in these packages. If you need to customize the options, you can do it -like this: +In v8, we are removing the `addGlobalEventProcessor` function in favor of `addEventProcessor`. ```js -import * as Sentry from '@sentry/nextjs'; +// Before (v7) +addGlobalEventProcessor(event => { + delete event.extra; + return event; +}); -Sentry.init({ - integrations: [ - Sentry.browserTracingIntegration({ - // add custom options here - }), - ], +// After (v8) +addEventProcessor(event => { + delete event.extra; + return event; }); ``` -### `@sentry/ember` +#### Removal of `lastEventId()` method -Browser tracing is automatically set up for you. You can configure it as before through configuration. +The `lastEventId` function has been removed. See [below](./MIGRATION.md#deprecate-lasteventid) for more details. -## Deprecated `transactionContext` passed to `tracesSampler` +### Browser SDK (Browser, React, Vue, Angular, Ember, etc.) -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). +Removed top-level exports: `Offline`, `makeXHRTransport`, `BrowserTracing` -## Deprecate using `getClient()` to check if the SDK was initialized +- [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) -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. +#### Removal of the `BrowserTracing` integration + +The `BrowserTracing` integration, together with the custom routing instrumentations passed to it, are deprecated in v8. +Instead, you should use `Sentry.browserTracingIntegration()`. See examples +[below](./MIGRATION.md#deprecated-browsertracing-integration) + +#### Removal of the `Offline` integration + +The `Offline` integration has been removed in favor of the +[offline transport wrapper](http://docs.sentry.io/platforms/javascript/configuration/transports/#offline-caching). + +#### Removal of `makeXHRTransport` transport + +The `makeXHRTransport` transport has been removed. Only `makeFetchTransport` is available now. This means that the +Sentry SDK requires the fetch API to be available in the environment. + +### Server-side SDKs (Node, Deno, Bun, etc.) + +Removed top-level exports: `enableAnrDetection`, `Anr`, `deepReadDirSync` + +- [Removal of `enableAnrDetection` and `Anr` class](./MIGRATION.md#removal-of-enableanrdetection-and-anr-class) +- [Removal of `deepReadDirSync` method](./MIGRATION.md#removal-of-deepreaddirsync-method) + +#### Removal of `enableAnrDetection` and `Anr` class + +The `enableAnrDetection` and `Anr` class have been removed. See the +[docs](https://docs.sentry.io/platforms/node/configuration/application-not-responding/) for more details. PR: + +#### Removal of `deepReadDirSync` method + +The `deepReadDirSync` method has been removed. There is no replacement API. + +### Next.js SDK + +Removed top-level exports: `withSentryApi`, `withSentryAPI`, `withSentryGetServerSideProps`, `withSentryGetStaticProps`, +`withSentryServerSideGetInitialProps`, `withSentryServerSideAppGetInitialProps`, +`withSentryServerSideDocumentGetInitialProps`, `withSentryServerSideErrorGetInitialProps`, `nextRouterInstrumentation`, +`IS_BUILD`, `isBuild` + +- [Removal of deprecated API in `@sentry/nextjs`](./MIGRATION.md#removal-of-deprecated-api-in-sentrynextjs) + +#### Removal of deprecated API in `@sentry/nextjs` + +The following previously deprecated API has been removed from the `@sentry/nextjs` package: + +- `withSentryApi` (Replacement: `wrapApiHandlerWithSentry`) +- `withSentryAPI` (Replacement: `wrapApiHandlerWithSentry`) +- `withSentryGetServerSideProps` (Replacement: `wrapGetServerSidePropsWithSentry`) +- `withSentryGetStaticProps` (Replacement: `wrapGetStaticPropsWithSentry`) +- `withSentryServerSideGetInitialProps` (Replacement: `wrapGetInitialPropsWithSentry`) +- `withSentryServerSideAppGetInitialProps` (Replacement: `wrapAppGetInitialPropsWithSentry`) +- `withSentryServerSideDocumentGetInitialProps` (Replacement: `wrapDocumentGetInitialPropsWithSentry`) +- `withSentryServerSideErrorGetInitialProps` was renamed to `wrapErrorGetInitialPropsWithSentry` +- `nextRouterInstrumentation` (Replaced by using `browserTracingIntegration`) +- `IS_BUILD` +- `isBuild` + +### Astro SDK + +#### Removal of `trackHeaders` option for Astro middleware + +Instead of opting-in via the middleware config, you can configure if headers should be captured via +`requestDataIntegration` options, which defaults to `true` but can be disabled like this: + +```js +Sentry.init({ + integrations: [ + Sentry.requestDataIntegration({ + include: { + headers: false, + }, + }), + ], +}); +``` + +## 5. Behaviour Changes + +- [Updated behaviour of `tracePropagationTargets` in the browser](./MIGRATION.md#updated-behaviour-of-tracepropagationtargets-in-the-browser-http-tracing-headers--cors) +- [Updated behaviour of `extraErrorDataIntegration`](./MIGRATION.md#extraerrordataintegration-changes) +- [Updated behaviour of `transactionContext` passed to `tracesSampler`](./MIGRATION.md#transactioncontext-no-longer-passed-to-tracessampler) +- [Updated behaviour of `getClient()`](./MIGRATION.md#getclient-always-returns-a-client) +- [Removal of Client-Side health check transaction filters](./MIGRATION.md#removal-of-client-side-health-check-transaction-filters) + +#### Updated behaviour of `tracePropagationTargets` in the browser (HTTP tracing headers & CORS) + +We updated the behaviour of the SDKs when no `tracePropagationTargets` option was defined. As a reminder, you can +provide a list of strings or RegExes that will be matched against URLs to tell the SDK, to which outgoing requests +tracing HTTP headers should be attached to. These tracing headers are used for distributed tracing. + +Previously, on the browser, when `tracePropagationTargets` were not defined, they defaulted to the following: +`['localhost', /^\/(?!\/)/]`. This meant that all request targets to that had "localhost" in the URL, or started with a +`/` were equipped with tracing headers. This default was chosen to prevent CORS errors in your browser applications. +However, this default had a few flaws. + +Going forward, when the `tracePropagationTargets` option is not set, tracing headers will be attached to all outgoing +requests on the same origin. For example, if you're on `https://example.com/` and you send a request to +`https://example.com/api`, the request will be traced (ie. will have trace headers attached). Requests to +`https://api.example.com/` will not, because it is on a different origin. The same goes for all applications running on +`localhost`. + +When you provide a `tracePropagationTargets` option, all of the entries you defined will now be matched be matched +against the full URL of the outgoing request. Previously, it was only matched against what you called request APIs with. +For example, if you made a request like `fetch("/api/posts")`, the provided `tracePropagationTargets` were only compared +against `"/api/posts"`. Going forward they will be matched against the entire URL, for example, if you were on the page +`https://example.com/` and you made the same request, it would be matched against `"https://example.com/api/posts"`. + +But that is not all. Because it would be annoying having to create matchers for the entire URL, if the request is a +same-origin request, we also match the `tracePropagationTargets` against the resolved `pathname` of the request. +Meaning, a matcher like `/^\/api/` would match a request call like `fetch('/api/posts')`, or +`fetch('https://same-origin.com/api/posts')` but not `fetch('https://different-origin.com/api/posts')`. + +#### `extraErrorDataIntegration` changes + +The `extraErrorDataIntegration` integration now looks at +[`error.cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause) by +default. + +#### `transactionContext` no longer passed to `tracesSampler` + +Instead of an `transactionContext` being passed to the `tracesSampler` callback, the callback will directly receive +`name` and `attributes` going forward. Note that the `attributes` are only the attributes at span creation time, and +some attributes may only be set later during the span lifecycle (and thus not be available during sampling). + +#### `getClient()` always returns a client + +`getClient()` now always returns a client if `Sentry.init()` was called. For cases where this may be used to check if +Sentry was actually initialized, using `getClient()` will thus not work anymore. Instead, you should use the new +`Sentry.isInitialized()` utility to check this. + +#### 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. + +# Deprecations in 7.x + +You can use the **Experimental** [@sentry/migr8](https://www.npmjs.com/package/@sentry/migr8) to automatically update +your SDK usage and fix most deprecations. This requires Node 18+. + +```bash +npx @sentry/migr8@latest +``` + +This will let you select which updates to run, and automatically update your code. Make sure to still review all code +changes! + +## Deprecated `BrowserTracing` integration + +The `BrowserTracing` integration, together with the custom routing instrumentations passed to it, are deprecated in v8. +Instead, you should use `Sentry.browserTracingIntegration()`. + +Package-specific browser tracing integrations are available directly. In most cases, there is a single integration +provided for each package, which will make sure to set up performance tracing correctly for the given SDK. For react, we +provide multiple integrations to cover different router integrations: + +### `@sentry/browser`, `@sentry/svelte`, `@sentry/gatsby` + +```js +import * as Sentry from '@sentry/browser'; + +Sentry.init({ + integrations: [Sentry.browserTracingIntegration()], +}); +``` + +### `@sentry/react` + +```js +import * as Sentry from '@sentry/react'; + +Sentry.init({ + integrations: [ + // No react router + Sentry.browserTracingIntegration(), + // OR, if you are using react router, instead use one of the following: + Sentry.reactRouterV6BrowserTracingIntegration({ + useEffect, + useLocation, + useNavigationType, + createRoutesFromChildren, + matchRoutes, + stripBasename, + }), + Sentry.reactRouterV5BrowserTracingIntegration({ + history, + }), + Sentry.reactRouterV4BrowserTracingIntegration({ + history, + }), + Sentry.reactRouterV3BrowserTracingIntegration({ + history, + routes, + match, + }), + ], +}); +``` + +### `@sentry/vue` + +```js +import * as Sentry from '@sentry/vue'; + +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration({ + // pass router in, if applicable + router, + }), + ], +}); +``` + +### `@sentry/angular` & `@sentry/angular-ivy` + +```js +import * as Sentry from '@sentry/angular'; + +Sentry.init({ + integrations: [Sentry.browserTracingIntegration()], +}); + +// You still need to add the TraceService like before! +``` + +### `@sentry/remix` + +```js +import * as Sentry from '@sentry/remix'; + +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration({ + useEffect, + useLocation, + useMatches, + }), + ], +}); +``` + +### `@sentry/nextjs`, `@sentry/astro`, `@sentry/sveltekit` + +Browser tracing is automatically set up for you in these packages. If you need to customize the options, you can do it +like this: + +```js +import * as Sentry from '@sentry/nextjs'; + +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration({ + // add custom options here + }), + ], +}); +``` + +### `@sentry/ember` + +Browser tracing is automatically set up for you. You can configure it as before through configuration. + +## Deprecated `transactionContext` passed to `tracesSampler` + +Instead of an `transactionContext` being passed to the `tracesSampler` callback, the callback will directly receive +`name` and `attributes` going forward. You can use these to make your sampling decisions, while `transactionContext` +will be removed in v8. Note that the `attributes` are only the attributes at span creation time, and some attributes may +only be set later during the span lifecycle (and thus not be available during sampling). + +## Deprecate using `getClient()` to check if the SDK was initialized + +In v8, `getClient()` will stop returning `undefined` if `Sentry.init()` was not called. For cases where this may be used +to check if Sentry was actually initialized, using `getClient()` will thus not work anymore. Instead, you should use the +new `Sentry.isInitialized()` utility to check this. ## Deprecate `getCurrentHub()` @@ -314,6 +738,8 @@ integrations from the `Integrations.XXX` hash, is deprecated in favor of using t The following list shows how integrations should be migrated: +### List of integrations and their replacements + | Old | New | Packages | | ---------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------- | | `new BrowserTracing()` | `browserTracingIntegration()` | `@sentry/browser` | @@ -543,7 +969,6 @@ callback. ```js // Before - Sentry.init({ beforeSend(event, hint) { const lastCapturedEventId = Sentry.lastEventId(); @@ -783,948 +1208,3 @@ This release deprecates `@sentry/hub` and all of it's exports. All of the `@sent For details on upgrading Replay in its beta phase, please view the [dedicated Replay MIGRATION docs](./packages/replay/MIGRATION.md). - -# Upgrading from 6.x to 7.x - -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" -``` - -# Upgrading from 4.x to 5.x/6.x - -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/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" +``` +