feat(browser): Deprecate BrowserTracing in favor of browserTracingIntegration (#10304)

Step by step...

Author: mydea

MIGRATION.md

@@ -46,6 +46,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` |

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

@@ -1,7 +1,7 @@
-import type { BrowserClient } from '@sentry/browser';
+import type { BrowserClient, BrowserTracing } from '@sentry/browser';
 import { getCurrentScope } from '@sentry/browser';
 import * as SentryBrowser from '@sentry/browser';
-import { BrowserTracing, SDK_VERSION, WINDOW, getClient } from '@sentry/browser';
+import { SDK_VERSION, WINDOW, browserTracingIntegration, getClient } from '@sentry/browser';
 import { vi } from 'vitest';
 
 import { init } from '../../../astro/src/client/sdk';
@@ -103,12 +103,13 @@ describe('Sentry client SDK', () => {
       it('Overrides the automatically default BrowserTracing instance with a a user-provided instance', () => {
         init({
           dsn: 'https://[email protected]/1337',
-          integrations: [new BrowserTracing({ finalTimeout: 10, startTransactionOnLocationChange: false })],
+          integrations: [browserTracingIntegration({ 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;
 

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

@@ -1,18 +1,27 @@
 // This is exported so the loader does not fail when switching off Replay/Tracing
 import { Feedback, feedbackIntegration } from '@sentry-internal/feedback';
-import { BrowserTracing, Replay, addTracingExtensions, replayIntegration } from '@sentry-internal/integration-shims';
+import {
+  BrowserTracing,
+  Replay,
+  addTracingExtensions,
+  browserTracingIntegration,
+  replayIntegration,
+} from '@sentry-internal/integration-shims';
 
 import * as Sentry from './index.bundle.base';
 
 // TODO (v8): Remove this as it was only needed for backwards compatibility
 // 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,
   // eslint-disable-next-line deprecation/deprecation
   Replay,

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

@@ -3,6 +3,7 @@ import {
   BrowserTracing,
   Feedback,
   addTracingExtensions,
+  browserTracingIntegration,
   feedbackIntegration,
 } from '@sentry-internal/integration-shims';
 import { Replay, replayIntegration } from '@sentry/replay';
@@ -13,11 +14,14 @@ 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,
   // eslint-disable-next-line deprecation/deprecation
   Replay,

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

@@ -1,5 +1,5 @@
 import { Feedback, feedbackIntegration } from '@sentry-internal/feedback';
-import { BrowserTracing, Span, addExtensionMethods } from '@sentry-internal/tracing';
+import { BrowserTracing, Span, addExtensionMethods, browserTracingIntegration } from '@sentry-internal/tracing';
 import { Replay, replayIntegration } from '@sentry/replay';
 
 import * as Sentry from './index.bundle.base';
@@ -10,6 +10,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
@@ -22,7 +23,9 @@ export {
   Replay,
   feedbackIntegration,
   replayIntegration,
+  // eslint-disable-next-line deprecation/deprecation
   BrowserTracing,
+  browserTracingIntegration,
   Span,
   addExtensionMethods,
 };

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

@@ -1,5 +1,5 @@
 import { Feedback, feedbackIntegration } from '@sentry-internal/integration-shims';
-import { BrowserTracing, Span, addExtensionMethods } from '@sentry-internal/tracing';
+import { BrowserTracing, Span, addExtensionMethods, browserTracingIntegration } from '@sentry-internal/tracing';
 import { Replay, replayIntegration } from '@sentry/replay';
 
 import * as Sentry from './index.bundle.base';
@@ -10,6 +10,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
@@ -22,7 +23,9 @@ export {
   Replay,
   replayIntegration,
   feedbackIntegration,
+  // eslint-disable-next-line deprecation/deprecation
   BrowserTracing,
+  browserTracingIntegration,
   Span,
   addExtensionMethods,
 };

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

@@ -1,6 +1,6 @@
 // This is exported so the loader does not fail when switching off Replay
 import { Feedback, Replay, feedbackIntegration, replayIntegration } from '@sentry-internal/integration-shims';
-import { BrowserTracing, Span, addExtensionMethods } from '@sentry-internal/tracing';
+import { BrowserTracing, Span, addExtensionMethods, browserTracingIntegration } from '@sentry-internal/tracing';
 
 import * as Sentry from './index.bundle.base';
 
@@ -10,6 +10,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
@@ -22,7 +23,9 @@ export {
   Replay,
   feedbackIntegration,
   replayIntegration,
+  // eslint-disable-next-line deprecation/deprecation
   BrowserTracing,
+  browserTracingIntegration,
   Span,
   addExtensionMethods,
 };

packages/browser/src/index.bundle.ts

@@ -4,6 +4,7 @@ import {
   Feedback,
   Replay,
   addTracingExtensions,
+  browserTracingIntegration,
   feedbackIntegration,
   replayIntegration,
 } from '@sentry-internal/integration-shims';
@@ -14,16 +15,19 @@ 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
   Replay,
   // eslint-disable-next-line deprecation/deprecation
   Feedback,
+  browserTracingIntegration,
   feedbackIntegration,
   replayIntegration,
 };

packages/browser/src/index.ts

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

packages/browser/test/unit/profiling/integration.test.ts

@@ -44,7 +44,7 @@ describe('BrowserProfilingIntegration', () => {
           send,
         };
       },
-      integrations: [new Sentry.BrowserTracing(), new BrowserProfilingIntegration()],
+      integrations: [Sentry.browserTracingIntegration(), new BrowserProfilingIntegration()],
     });
 
     const client = Sentry.getClient<BrowserClient>();

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

@@ -404,11 +404,11 @@ export async function instrumentForPerformance(appInstance: ApplicationInstance)
   // Maintaining backwards compatibility with config.browserTracingOptions, but passing it with Sentry options is preferred.
   const browserTracingOptions = config.browserTracingOptions || config.sentry.browserTracingOptions || {};
 
-  const { BrowserTracing } = await import('@sentry/browser');
+  const { browserTracingIntegration } = await import('@sentry/browser');
 
   const idleTimeout = config.transitionTimeout || 5000;
 
-  const browserTracing = new BrowserTracing({
+  const browserTracing = browserTracingIntegration({
     routingInstrumentation: (customStartTransaction, startTransactionOnPageLoad) => {
       // eslint-disable-next-line ember/no-private-routing-service
       const routerMain = appInstance.lookup('router:main') as EmberRouterMain;

packages/ember/addon/types.ts

@@ -1,7 +1,7 @@
-import type { BrowserOptions, BrowserTracing } from '@sentry/browser';
+import type { BrowserOptions, browserTracingIntegration } from '@sentry/browser';
 import type { Transaction, TransactionContext } from '@sentry/types';
 
-type BrowserTracingOptions = ConstructorParameters<typeof BrowserTracing>[0];
+type BrowserTracingOptions = Parameters<typeof browserTracingIntegration>[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(

packages/gatsby/test/sdk.test.ts

@@ -1,4 +1,4 @@
-import { BrowserTracing, SDK_VERSION, init } from '@sentry/react';
+import { SDK_VERSION, browserTracingIntegration, init } from '@sentry/react';
 import type { Integration } from '@sentry/types';
 
 import { init as gatsbyInit } from '../src/sdk';
@@ -68,27 +68,27 @@ describe('Integrations from options', () => {
     [
       'tracing disabled, with BrowserTracing as an array',
       [],
-      { integrations: [new BrowserTracing()] },
+      { integrations: [browserTracingIntegration()] },
       ['BrowserTracing'],
     ],
     [
       'tracing disabled, with BrowserTracing as a function',
       [],
       {
-        integrations: () => [new BrowserTracing()],
+        integrations: () => [browserTracingIntegration()],
       },
       ['BrowserTracing'],
     ],
     [
       'tracing enabled, with BrowserTracing as an array',
       [],
-      { tracesSampleRate: 1, integrations: [new BrowserTracing()] },
+      { tracesSampleRate: 1, integrations: [browserTracingIntegration()] },
       ['BrowserTracing'],
     ],
     [
       'tracing enabled, with BrowserTracing as a function',
       [],
-      { tracesSampleRate: 1, integrations: () => [new BrowserTracing()] },
+      { tracesSampleRate: 1, integrations: () => [browserTracingIntegration()] },
       ['BrowserTracing'],
     ],
   ] as TestArgs[])(

packages/integration-shims/src/BrowserTracing.ts

@@ -5,6 +5,8 @@ import { consoleSandbox } from '@sentry/utils';
  * This is a shim for the BrowserTracing integration.
  * It is needed in order for the CDN bundles to continue working when users add/remove tracing
  * from it, without changing their config. This is necessary for the loader mechanism.
+ *
+ * @deprecated Use `browserTracingIntegration()` instead.
  */
 class BrowserTracingShim implements Integration {
   /**
@@ -19,6 +21,7 @@ class BrowserTracingShim implements Integration {
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   public constructor(_options: any) {
+    // eslint-disable-next-line deprecation/deprecation
     this.name = BrowserTracingShim.id;
 
     consoleSandbox(() => {
@@ -33,7 +36,21 @@ class BrowserTracingShim implements Integration {
   }
 }
 
-export { BrowserTracingShim as BrowserTracing };
+/**
+ * This is a shim for the BrowserTracing integration.
+ * It is needed in order for the CDN bundles to continue working when users add/remove tracing
+ * from it, without changing their config. This is necessary for the loader mechanism.
+ */
+function browserTracingIntegrationShim(): Integration {
+  // eslint-disable-next-line deprecation/deprecation
+  return new BrowserTracingShim({});
+}
+
+export {
+  // eslint-disable-next-line deprecation/deprecation
+  BrowserTracingShim as BrowserTracing,
+  browserTracingIntegrationShim as browserTracingIntegration,
+};
 
 /** Shim function */
 export function addTracingExtensions(): void {

packages/integration-shims/src/index.ts

@@ -3,9 +3,16 @@ export {
   Feedback,
   feedbackIntegration,
 } from './Feedback';
+
 export {
   // eslint-disable-next-line deprecation/deprecation
   Replay,
   replayIntegration,
 } from './Replay';
-export { BrowserTracing, addTracingExtensions } from './BrowserTracing';
+
+export {
+  // eslint-disable-next-line deprecation/deprecation
+  BrowserTracing,
+  browserTracingIntegration,
+  addTracingExtensions,
+} from './BrowserTracing';