feat(angular): Export custom browserTracingIntegration()

Also deprecate the routing Instrumentation.

Author: mydea

packages/angular-ivy/README.md

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

packages/angular/README.md

@@ -93,16 +93,14 @@ 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({
-      tracingOrigins: ['localhost', 'https://yourserver.io/api'],
-      routingInstrumentation: instrumentAngularRouting,
-    }),
+    browserTracingIntegration(),
   ],
+  tracePropagationTargets: ['localhost', 'https://yourserver.io/api'],
   tracesSampleRate: 1,
 });
 ```

packages/angular/src/index.ts

@@ -7,9 +7,11 @@ export { createErrorHandler, SentryErrorHandler } from './errorhandler';
 export {
   // eslint-disable-next-line deprecation/deprecation
   getActiveTransaction,
-  // TODO `instrumentAngularRouting` is just an alias for `routingInstrumentation`; deprecate the latter at some point
+  // eslint-disable-next-line deprecation/deprecation
   instrumentAngularRouting, // new name
+  // eslint-disable-next-line deprecation/deprecation
   routingInstrumentation, // legacy name
+  browserTracingIntegration,
   TraceClassDecorator,
   TraceMethodDecorator,
   TraceDirective,

packages/angular/src/tracing.ts

@@ -7,9 +7,15 @@ 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,
+  disableDefaultBrowserTracingNavigationSpan,
+  getCurrentScope,
+  startBrowserTracingNavigationSpan,
+} 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,8 +29,12 @@ let instrumentationInitialized: boolean;
 let stashedStartTransaction: (context: TransactionContext) => Transaction | undefined;
 let stashedStartTransactionOnLocationChange: boolean;
 
+let hooksBasedInstrumentation = false;
+
 /**
  * Creates routing instrumentation for Angular Router.
+ *
+ * @deprecated Use `browserTracingIntegration()` instead, which includes Angular-specific instrumentation out of the box.
  */
 export function routingInstrumentation(
   customStartTransaction: (context: TransactionContext) => Transaction | undefined,
@@ -47,8 +57,30 @@ export function routingInstrumentation(
   }
 }
 
+/**
+ * Creates routing instrumentation for Angular Router.
+ *
+ * @deprecated Use `browserTracingIntegration()` instead, which includes Angular-specific instrumentation out of the box.
+ */
+// eslint-disable-next-line deprecation/deprecation
 export const instrumentAngularRouting = routingInstrumentation;
 
+/**
+ * A custom BrowserTracing integration for Angular.
+ *
+ * Use this integration in combination with `TraceService`
+ */
+export function browserTracingIntegration(
+  options?: Parameters<typeof originalBrowserTracingIntegration>[0],
+): Integration {
+  instrumentationInitialized = true;
+  hooksBasedInstrumentation = true;
+
+  disableDefaultBrowserTracingNavigationSpan();
+
+  return originalBrowserTracingIntegration(options);
+}
+
 /**
  * Grabs active transaction off scope.
  *
@@ -74,7 +106,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()) {
+          startBrowserTracingNavigationSpan({
+            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 +158,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/angular/test/tracing.test.ts

@@ -44,6 +44,7 @@ describe('Angular Tracing', () => {
     transaction = undefined;
   });
 
+  /* eslint-disable deprecation/deprecation */
   describe('instrumentAngularRouting', () => {
     it('should attach the transaction source on the pageload transaction', () => {
       const startTransaction = jest.fn();
@@ -57,6 +58,7 @@ describe('Angular Tracing', () => {
       });
     });
   });
+  /* eslint-enable deprecation/deprecation */
 
   describe('getParameterizedRouteFromSnapshot', () => {
     it.each([

packages/angular/test/utils/index.ts

@@ -50,6 +50,7 @@ export class TestEnv {
     useTraceService?: boolean;
     additionalProviders?: Provider[];
   }): Promise<TestEnv> {
+    // eslint-disable-next-line deprecation/deprecation
     instrumentAngularRouting(
       conf.customStartTransaction || jest.fn(),
       conf.startTransactionOnPageLoad !== undefined ? conf.startTransactionOnPageLoad : true,