feat(browser): Deprecate BrowserTracing integration

MIGRATION.md

@@ -10,6 +10,122 @@ 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!
 
+## Depreacted `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 Trace Service 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
@@ -43,6 +159,7 @@ The following list shows how integrations should be migrated:
 
 | Old                          | New                                 | Packages                                                                                                |
 | ---------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `new BrowserTracing()`       | `browserTracingIntegration()`       | `@sentry/browser`                                                                                       |
 | `new InboundFilters()`       | `inboundFiltersIntegration()`       | `@sentry/core`, `@sentry/browser`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge` |
 | `new FunctionToString()`     | `functionToStringIntegration()`     | `@sentry/core`, `@sentry/browser`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge` |
 | `new LinkedErrors()`         | `linkedErrorsIntegration()`         | `@sentry/core`, `@sentry/browser`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge` |
@@ -75,8 +192,8 @@ The following list shows how integrations should be migrated:
 | `new OnUncaughtException()`  | `onUncaughtExceptionIntegration()`  | `@sentry/node`                                                                                          |
 | `new OnUnhandledRejection()` | `onUnhandledRejectionIntegration()` | `@sentry/node`                                                                                          |
 | `new LocalVariables()`       | `localVariablesIntegration()`       | `@sentry/node`                                                                                          |
-| `new Spotlight()`            | `spotlightIntergation()`            | `@sentry/node`                                                                                          |
-| `new Anr()`                  | `anrIntergation()`                  | `@sentry/node`                                                                                          |
+| `new Spotlight()`            | `spotlightIntegration()`            | `@sentry/node`                                                                                          |
+| `new Anr()`                  | `anrIntegration()`                  | `@sentry/node`                                                                                          |
 | `new Hapi()`                 | `hapiIntegration()`                 | `@sentry/node`                                                                                          |
 | `new Undici()`               | `nativeNodeFetchIntegration()`      | `@sentry/node`                                                                                          |
 | `new Http()`                 | `httpIntegration()`                 | `@sentry/node`                                                                                          |

packages/astro/src/client/sdk.ts

@@ -1,6 +1,6 @@
 import type { BrowserOptions } from '@sentry/browser';
 import {
-  BrowserTracing,
+  browserTracingIntegration,
   getDefaultIntegrations as getBrowserDefaultIntegrations,
   init as initBrowserSdk,
   setTag,
@@ -34,7 +34,7 @@ function getDefaultIntegrations(options: BrowserOptions): Integration[] | undefi
   // in which case everything inside will get treeshaken away
   if (typeof __SENTRY_TRACING__ === 'undefined' || __SENTRY_TRACING__) {
     if (hasTracingEnabled(options)) {
-      return [...getBrowserDefaultIntegrations(options), new BrowserTracing()];
+      return [...getBrowserDefaultIntegrations(options), browserTracingIntegration()];
     }
   }
 

packages/astro/test/client/sdk.test.ts

@@ -104,12 +104,14 @@ describe('Sentry client SDK', () => {
       it('Overrides the automatically default BrowserTracing instance with a a user-provided BrowserTracing instance', () => {
         init({
           dsn: 'https://[email protected]/1337',
+          // eslint-disable-next-line deprecation/deprecation
           integrations: [new BrowserTracing({ finalTimeout: 10, startTransactionOnLocationChange: false })],
           enableTracing: true,
         });
 
         const integrationsToInit = browserInit.mock.calls[0][0]?.defaultIntegrations;
 
+        // eslint-disable-next-line deprecation/deprecation
         const browserTracing = getClient<BrowserClient>()?.getIntegrationByName('BrowserTracing') as BrowserTracing;
         const options = browserTracing.options;
 
@@ -120,7 +122,7 @@ describe('Sentry client SDK', () => {
         expect(options.finalTimeout).toEqual(10);
       });
 
-      it('Overrides the automatically default BrowserTracing instance with a a user-provided browserTracingIntergation instance', () => {
+      it('Overrides the automatically default BrowserTracing instance with a a user-provided browserTracingIntegration instance', () => {
         init({
           dsn: 'https://[email protected]/1337',
           integrations: [

packages/browser/src/helpers.ts

@@ -201,6 +201,7 @@ export function bundleBrowserTracingIntegration(
   options: Parameters<typeof browserTracingIntegration>[0] = {},
 ): Integration {
   // Migrate some options from the old integration to the new one
+  // eslint-disable-next-line deprecation/deprecation
   const opts: ConstructorParameters<typeof BrowserTracing>[0] = options;
 
   if (typeof options.markBackgroundSpan === 'boolean') {
@@ -215,5 +216,6 @@ export function bundleBrowserTracingIntegration(
     opts.startTransactionOnLocationChange = options.instrumentNavigation;
   }
 
+  // eslint-disable-next-line deprecation/deprecation
   return new BrowserTracing(opts);
 }

packages/browser/src/index.bundle.feedback.ts

@@ -14,10 +14,12 @@ import * as Sentry from './index.bundle.base';
 // eslint-disable-next-line deprecation/deprecation
 Sentry.Integrations.Replay = Replay;
 
+// eslint-disable-next-line deprecation/deprecation
 Sentry.Integrations.BrowserTracing = BrowserTracing;
 
 export * from './index.bundle.base';
 export {
+  // eslint-disable-next-line deprecation/deprecation
   BrowserTracing,
   browserTracingIntegration,
   addTracingExtensions,

packages/browser/src/index.bundle.replay.ts

@@ -14,10 +14,12 @@ import * as Sentry from './index.bundle.base';
 // eslint-disable-next-line deprecation/deprecation
 Sentry.Integrations.Replay = Replay;
 
+// eslint-disable-next-line deprecation/deprecation
 Sentry.Integrations.BrowserTracing = BrowserTracing;
 
 export * from './index.bundle.base';
 export {
+  // eslint-disable-next-line deprecation/deprecation
   BrowserTracing,
   browserTracingIntegration,
   addTracingExtensions,

packages/browser/src/index.bundle.tracing.replay.feedback.ts

@@ -11,6 +11,7 @@ import * as Sentry from './index.bundle.base';
 // eslint-disable-next-line deprecation/deprecation
 Sentry.Integrations.Replay = Replay;
 
+// eslint-disable-next-line deprecation/deprecation
 Sentry.Integrations.BrowserTracing = BrowserTracing;
 
 // We are patching the global object with our hub extension methods
@@ -23,6 +24,7 @@ export {
   Replay,
   feedbackIntegration,
   replayIntegration,
+  // eslint-disable-next-line deprecation/deprecation
   BrowserTracing,
   browserTracingIntegration,
   Span,

packages/browser/src/index.bundle.tracing.replay.ts

@@ -11,6 +11,7 @@ import * as Sentry from './index.bundle.base';
 // eslint-disable-next-line deprecation/deprecation
 Sentry.Integrations.Replay = Replay;
 
+// eslint-disable-next-line deprecation/deprecation
 Sentry.Integrations.BrowserTracing = BrowserTracing;
 
 // We are patching the global object with our hub extension methods
@@ -23,6 +24,7 @@ export {
   Replay,
   replayIntegration,
   feedbackIntegration,
+  // eslint-disable-next-line deprecation/deprecation
   BrowserTracing,
   browserTracingIntegration,
   Span,

packages/browser/src/index.bundle.tracing.ts

@@ -11,6 +11,7 @@ import * as Sentry from './index.bundle.base';
 // eslint-disable-next-line deprecation/deprecation
 Sentry.Integrations.Replay = Replay;
 
+// eslint-disable-next-line deprecation/deprecation
 Sentry.Integrations.BrowserTracing = BrowserTracing;
 
 // We are patching the global object with our hub extension methods
@@ -23,6 +24,7 @@ export {
   Replay,
   feedbackIntegration,
   replayIntegration,
+  // eslint-disable-next-line deprecation/deprecation
   BrowserTracing,
   browserTracingIntegration,
   Span,

packages/browser/src/index.bundle.ts

@@ -15,10 +15,12 @@ import * as Sentry from './index.bundle.base';
 // eslint-disable-next-line deprecation/deprecation
 Sentry.Integrations.Replay = Replay;
 
+// eslint-disable-next-line deprecation/deprecation
 Sentry.Integrations.BrowserTracing = BrowserTracing;
 
 export * from './index.bundle.base';
 export {
+  // eslint-disable-next-line deprecation/deprecation
   BrowserTracing,
   addTracingExtensions,
   // eslint-disable-next-line deprecation/deprecation

packages/browser/src/index.ts

@@ -54,6 +54,7 @@ export {
 } from '@sentry-internal/feedback';
 
 export {
+  // eslint-disable-next-line deprecation/deprecation
   BrowserTracing,
   defaultRequestInstrumentationOptions,
   instrumentOutgoingRequests,

packages/deno/src/integrations/globalhandlers.ts

@@ -48,7 +48,7 @@ export const globalHandlersIntegration = defineIntegration(_globalHandlersIntegr
 
 /**
  * Global handlers.
- * @deprecated Use `globalHandlersIntergation()` instead.
+ * @deprecated Use `globalHandlersIntegration()` instead.
  */
 // eslint-disable-next-line deprecation/deprecation
 export const GlobalHandlers = convertIntegrationFnToClass(

packages/ember/addon/instance-initializers/sentry-performance.ts

@@ -109,7 +109,11 @@ export function _instrumentEmberRouter(
     return;
   }
 
-  if (url && browserTracingOptions.startTransactionOnPageLoad !== false) {
+  if (
+    url &&
+    browserTracingOptions.startTransactionOnPageLoad !== false &&
+    browserTracingOptions.instrumentPageLoad !== false
+  ) {
     const routeInfo = routerService.recognize(url);
     Sentry.startBrowserTracingPageLoadSpan(client, {
       name: `route:${routeInfo.name}`,
@@ -132,7 +136,10 @@ export function _instrumentEmberRouter(
     getBackburner().off('end', finishActiveTransaction);
   };
 
-  if (browserTracingOptions.startTransactionOnLocationChange === false) {
+  if (
+    browserTracingOptions.startTransactionOnLocationChange === false &&
+    browserTracingOptions.instrumentNavigation === false
+  ) {
     return;
   }
 

packages/ember/addon/types.ts

@@ -1,7 +1,9 @@
-import type { BrowserOptions, BrowserTracing } from '@sentry/browser';
+import type { BrowserOptions, BrowserTracing, browserTracingIntegration } from '@sentry/browser';
 import type { Transaction, TransactionContext } from '@sentry/types';
 
-type BrowserTracingOptions = ConstructorParameters<typeof BrowserTracing>[0];
+type BrowserTracingOptions = Parameters<typeof browserTracingIntegration>[0] &
+  // eslint-disable-next-line deprecation/deprecation
+  ConstructorParameters<typeof BrowserTracing>[0];
 
 export type EmberSentryConfig = {
   sentry: BrowserOptions & { browserTracingOptions?: BrowserTracingOptions };

packages/gatsby/src/utils/integrations.ts

@@ -1,5 +1,5 @@
 import { hasTracingEnabled } from '@sentry/core';
-import { BrowserTracing } from '@sentry/react';
+import { browserTracingIntegration } from '@sentry/react';
 import type { Integration } from '@sentry/types';
 
 import type { GatsbyOptions } from './types';
@@ -31,8 +31,8 @@ export function getIntegrationsFromOptions(options: GatsbyOptions): UserIntegrat
  * @param isTracingEnabled Whether the user has enabled tracing.
  */
 function getIntegrationsFromArray(userIntegrations: Integration[], isTracingEnabled: boolean): Integration[] {
-  if (isTracingEnabled && !userIntegrations.some(integration => integration.name === BrowserTracing.name)) {
-    userIntegrations.push(new BrowserTracing());
+  if (isTracingEnabled && !userIntegrations.some(integration => integration.name === 'BrowserTracing')) {
+    userIntegrations.push(browserTracingIntegration());
   }
   return userIntegrations;
 }

packages/gatsby/test/gatsby-browser.test.ts

@@ -2,7 +2,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
 import { onClientEntry } from '../gatsby-browser';
-import { BrowserTracing } from '../src/index';
+import { browserTracingIntegration } from '../src/index';
 
 (global as any).__SENTRY_RELEASE__ = '683f3a6ab819d47d23abfca9a914c81f0524d35b';
 (global as any).__SENTRY_DSN__ = 'https://[email protected]/0';
@@ -141,7 +141,7 @@ describe('onClientEntry', () => {
   });
 
   it('only defines a single `BrowserTracing` integration', () => {
-    const integrations = [new BrowserTracing()];
+    const integrations = [browserTracingIntegration()];
     onClientEntry(undefined, { tracesSampleRate: 0.5, integrations });
 
     expect(sentryInit).toHaveBeenLastCalledWith(