feat(tracing): Implement new browserTracingIntegration()

MIGRATION.md

@@ -10,6 +10,33 @@ 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!
 
+## Deprecate `new BrowserTracing()` in favor of `browserTracingIntegration()`
+
+In v8, you have to use the functional style for the browser tracing integration. This works mostly the same, but some of
+the options have changed:
+
+- `startTransactionOnPageLoad` --> `instrumentPageLoad`
+- `startTransactionOnLocationChange` --> `instrumentNavigation`
+- `markBackgroundTransactions` --> `markBackgroundSpan`
+- `beforeNavigate` --> `beforeStartSpan`
+
+Finally, instead of `routingInstrumentation`, you have to disable instrumentation via e.g.
+`instrumentNavigation: false`, and can then manually emit events like this:
+
+```js
+// Example router event
+router.on('routeChange', route => {
+  Sentry.getClient().emit('startNavigationSpan', {
+    name: route.name,
+    op: 'navigation',
+  });
+
+  const activeSpan = Sentry.getActiveSpan(); // <-- this will hold the navigation span
+});
+```
+
+The new `browserTracingIntegration()` will pick these up and create the correct spans.
+
 ## 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

packages/angular/README.md

@@ -93,14 +93,13 @@ Registering a Trace Service is a 3-step process.
    instrumentation:
 
 ```javascript
-import { init, instrumentAngularRouting, BrowserTracing } from '@sentry/angular';
+import { init, browserTracingIntegration } from '@sentry/angular';
 
 init({
   dsn: '__DSN__',
   integrations: [
-    new BrowserTracing({
+    browserTracingIntegration({
       tracingOrigins: ['localhost', 'https://yourserver.io/api'],
-      routingInstrumentation: instrumentAngularRouting,
     }),
   ],
   tracesSampleRate: 1,

packages/angular/src/index.ts

@@ -10,6 +10,7 @@ export {
   // TODO `instrumentAngularRouting` is just an alias for `routingInstrumentation`; deprecate the latter at some point
   instrumentAngularRouting, // new name
   routingInstrumentation, // legacy name
+  browserTracingIntegration,
   TraceClassDecorator,
   TraceMethodDecorator,
   TraceDirective,

packages/angular/src/tracing.ts

@@ -7,9 +7,14 @@ import type { ActivatedRouteSnapshot, Event, RouterState } from '@angular/router
 // eslint-disable-next-line @typescript-eslint/consistent-type-imports
 import { NavigationCancel, NavigationError, Router } from '@angular/router';
 import { NavigationEnd, NavigationStart, ResolveEnd } from '@angular/router';
-import { WINDOW, getCurrentScope } from '@sentry/browser';
-import { SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, spanToJSON } from '@sentry/core';
-import type { Span, Transaction, TransactionContext } from '@sentry/types';
+import {
+  WINDOW,
+  browserTracingIntegration as originalBrowserTracingIntegration,
+  browserTracingStartNavigationSpan,
+  getCurrentScope,
+} from '@sentry/browser';
+import { SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, getActiveSpan, spanToJSON, startInactiveSpan } from '@sentry/core';
+import type { Integration, Span, Transaction, TransactionContext } from '@sentry/types';
 import { logger, stripUrlQueryAndFragment, timestampInSeconds } from '@sentry/utils';
 import type { Observable } from 'rxjs';
 import { Subscription } from 'rxjs';
@@ -23,6 +28,8 @@ let instrumentationInitialized: boolean;
 let stashedStartTransaction: (context: TransactionContext) => Transaction | undefined;
 let stashedStartTransactionOnLocationChange: boolean;
 
+let hooksBasedInstrumentation = false;
+
 /**
  * Creates routing instrumentation for Angular Router.
  */
@@ -49,6 +56,23 @@ export function routingInstrumentation(
 
 export const instrumentAngularRouting = routingInstrumentation;
 
+/**
+ * A custom BrowserTracing integration for Angular.
+ */
+export function browserTracingIntegration(
+  options?: Parameters<typeof originalBrowserTracingIntegration>[0],
+): Integration {
+  instrumentationInitialized = true;
+  hooksBasedInstrumentation = true;
+
+  return originalBrowserTracingIntegration({
+    ...options,
+    instrumentPageLoad: true,
+    // We handle this manually
+    instrumentNavigation: false,
+  });
+}
+
 /**
  * Grabs active transaction off scope.
  *
@@ -74,7 +98,43 @@ export class TraceService implements OnDestroy {
         return;
       }
 
+      if (this._routingSpan) {
+        this._routingSpan.end();
+        this._routingSpan = null;
+      }
+
       const strippedUrl = stripUrlQueryAndFragment(navigationEvent.url);
+
+      if (hooksBasedInstrumentation) {
+        if (!getActiveSpan()) {
+          browserTracingStartNavigationSpan({
+            name: strippedUrl,
+            op: 'navigation',
+            origin: 'auto.navigation.angular',
+            attributes: {
+              [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'url',
+            },
+          });
+        }
+
+        // eslint-disable-next-line deprecation/deprecation
+        this._routingSpan =
+          startInactiveSpan({
+            name: `${navigationEvent.url}`,
+            op: ANGULAR_ROUTING_OP,
+            origin: 'auto.ui.angular',
+            tags: {
+              'routing.instrumentation': '@sentry/angular',
+              url: strippedUrl,
+              ...(navigationEvent.navigationTrigger && {
+                navigationTrigger: navigationEvent.navigationTrigger,
+              }),
+            },
+          }) || null;
+
+        return;
+      }
+
       // eslint-disable-next-line deprecation/deprecation
       let activeTransaction = getActiveTransaction();
 
@@ -90,9 +150,6 @@ export class TraceService implements OnDestroy {
       }
 
       if (activeTransaction) {
-        if (this._routingSpan) {
-          this._routingSpan.end();
-        }
         // eslint-disable-next-line deprecation/deprecation
         this._routingSpan = activeTransaction.startChild({
           description: `${navigationEvent.url}`,

packages/browser/src/index.ts

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

packages/core/src/baseclient.ts

@@ -26,6 +26,7 @@ import type {
   SessionAggregates,
   Severity,
   SeverityLevel,
+  StartSpanOptions,
   Transaction,
   TransactionEvent,
   Transport,
@@ -481,6 +482,12 @@ export abstract class BaseClient<O extends ClientOptions> implements Client<O> {
     callback: (feedback: FeedbackEvent, options?: { includeReplay: boolean }) => void,
   ): void;
 
+  /** @inheritdoc */
+  public on(hook: 'startPageLoadSpan', callback: (options: StartSpanOptions) => void): void;
+
+  /** @inheritdoc */
+  public on(hook: 'startNavigationSpan', callback: (options: StartSpanOptions) => void): void;
+
   /** @inheritdoc */
   public on(hook: string, callback: unknown): void {
     if (!this._hooks[hook]) {
@@ -521,6 +528,12 @@ export abstract class BaseClient<O extends ClientOptions> implements Client<O> {
   /** @inheritdoc */
   public emit(hook: 'beforeSendFeedback', feedback: FeedbackEvent, options?: { includeReplay: boolean }): void;
 
+  /** @inheritdoc */
+  public emit(hook: 'startPageLoadSpan', options: StartSpanOptions): void;
+
+  /** @inheritdoc */
+  public emit(hook: 'startNavigationSpan', options: StartSpanOptions): void;
+
   /** @inheritdoc */
   public emit(hook: string, ...rest: unknown[]): void {
     if (this._hooks[hook]) {

packages/core/src/tracing/trace.ts

@@ -1,15 +1,5 @@
-import type {
-  Instrumenter,
-  Primitive,
-  Scope,
-  Span,
-  SpanTimeInput,
-  TransactionContext,
-  TransactionMetadata,
-} from '@sentry/types';
-import type { SpanAttributes } from '@sentry/types';
-import type { SpanOrigin } from '@sentry/types';
-import type { TransactionSource } from '@sentry/types';
+import type { Span, SpanTimeInput, StartSpanOptions, TransactionContext } from '@sentry/types';
+
 import { dropUndefinedKeys, logger, tracingContextFromHeaders } from '@sentry/utils';
 
 import { DEBUG_BUILD } from '../debug-build';
@@ -20,105 +10,6 @@ import { handleCallbackErrors } from '../utils/handleCallbackErrors';
 import { hasTracingEnabled } from '../utils/hasTracingEnabled';
 import { spanTimeInputToSeconds, spanToJSON } from '../utils/spanUtils';
 
-interface StartSpanOptions extends TransactionContext {
-  /** A manually specified start time for the created `Span` object. */
-  startTime?: SpanTimeInput;
-
-  /** If defined, start this span off this scope instead off the current scope. */
-  scope?: Scope;
-
-  /** The name of the span. */
-  name: string;
-
-  /** An op for the span. This is a categorization for spans. */
-  op?: string;
-
-  /** The origin of the span - if it comes from auto instrumenation or manual instrumentation. */
-  origin?: SpanOrigin;
-
-  /** Attributes for the span. */
-  attributes?: SpanAttributes;
-
-  // All remaining fields are deprecated
-
-  /**
-   * @deprecated Manually set the end timestamp instead.
-   */
-  trimEnd?: boolean;
-
-  /**
-   * @deprecated This cannot be set manually anymore.
-   */
-  parentSampled?: boolean;
-
-  /**
-   * @deprecated Use attributes or set data on scopes instead.
-   */
-  metadata?: Partial<TransactionMetadata>;
-
-  /**
-   * The name thingy.
-   * @deprecated Use `name` instead.
-   */
-  description?: string;
-
-  /**
-   * @deprecated Use `span.setStatus()` instead.
-   */
-  status?: string;
-
-  /**
-   * @deprecated Use `scope` instead.
-   */
-  parentSpanId?: string;
-
-  /**
-   * @deprecated You cannot manually set the span to sampled anymore.
-   */
-  sampled?: boolean;
-
-  /**
-   * @deprecated You cannot manually set the spanId anymore.
-   */
-  spanId?: string;
-
-  /**
-   * @deprecated You cannot manually set the traceId anymore.
-   */
-  traceId?: string;
-
-  /**
-   * @deprecated Use an attribute instead.
-   */
-  source?: TransactionSource;
-
-  /**
-   * @deprecated Use attributes or set tags on the scope instead.
-   */
-  tags?: { [key: string]: Primitive };
-
-  /**
-   * @deprecated Use attributes instead.
-   */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  data?: { [key: string]: any };
-
-  /**
-   * @deprecated Use `startTime` instead.
-   */
-  startTimestamp?: number;
-
-  /**
-   * @deprecated Use `span.end()` instead.
-   */
-  endTimestamp?: number;
-
-  /**
-   * @deprecated You cannot set the instrumenter manually anymore.
-   */
-  instrumenter?: Instrumenter;
-}
-
 /**
  * Wraps a function with a transaction/span and finishes the span after the function is done.
  *