feat(angular/v8): Change decorator naming and add name parameter (#11057)

closes #11038

Author: s1gr1d

MIGRATION.md

@@ -777,6 +777,35 @@ The SDK no longer filters out health check transactions by default. Instead, the
 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.
 
+#### Angular Tracing Decorator renaming
+
+The usage of `TraceClassDecorator` and the `TraceMethodDecorator` already implies that those are decorators. The word
+`Decorator` is now removed from the names to avoid multiple mentioning.
+
+Additionally, the `TraceClass` and `TraceMethod` decorators accept an optional `name` parameter to set the transaction
+name. This was added because Angular minifies class and method names, and you might want to set a more descriptive name.
+If nothing provided, the name defaults to `'unnamed'`.
+
+```js
+// v7
+@Sentry.TraceClassDecorator()
+export class HeaderComponent {
+  @Sentry.TraceMethodDecorator()
+  ngOnChanges(changes: SimpleChanges) {}
+}
+```
+
+```js
+// v8
+@Sentry.TraceClass({ name: 'HeaderComponent' })
+export class HeaderComponent {
+  @Sentry.TraceMethod({ name: 'ngOnChanges' })
+  ngOnChanges(changes: SimpleChanges) {}
+}
+```
+
+---
+
 # Deprecations in 7.x
 
 You can use the **Experimental** [@sentry/migr8](https://www.npmjs.com/package/@sentry/migr8) to automatically update

dev-packages/e2e-tests/test-applications/angular-17/src/app/component-tracking/component-tracking.components.ts

@@ -1,5 +1,5 @@
 import { AfterViewInit, Component, OnInit } from '@angular/core';
-import { TraceClassDecorator, TraceMethodDecorator, TraceModule } from '@sentry/angular-ivy';
+import { TraceClass, TraceMethod, TraceModule } from '@sentry/angular-ivy';
 import { SampleComponent } from '../sample-component/sample-component.components';
 
 @Component({
@@ -8,11 +8,11 @@ import { SampleComponent } from '../sample-component/sample-component.components
   imports: [TraceModule, SampleComponent],
   template: `<app-sample-component [trace]="'sample-component'"></app-sample-component>`,
 })
-@TraceClassDecorator()
+@TraceClass({ name: 'ComponentTrackingComponent' })
 export class ComponentTrackingComponent implements OnInit, AfterViewInit {
-  @TraceMethodDecorator()
+  @TraceMethod({ name: 'ngOnInit' })
   ngOnInit() {}
 
-  @TraceMethodDecorator()
+  @TraceMethod()
   ngAfterViewInit() {}
 }

dev-packages/e2e-tests/test-applications/angular-17/tests/performance.test.ts

@@ -222,7 +222,7 @@ test.describe('TraceDirective', () => {
   });
 });
 
-test.describe('TraceClassDecorator', () => {
+test.describe('TraceClass Decorator', () => {
   test('adds init span for decorated class', async ({ page }) => {
     const navigationTxnPromise = waitForTransaction('angular-17', async transactionEvent => {
       return !!transactionEvent?.transaction && transactionEvent.contexts?.trace?.op === 'navigation';
@@ -244,8 +244,7 @@ test.describe('TraceClassDecorator', () => {
           [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'ui.angular.init',
           [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.ui.angular.trace_class_decorator',
         },
-        // todo: right now, it shows the minified version of the component name - we will add a name input to the Decorator
-        description: expect.any(String),
+        description: '<ComponentTrackingComponent>',
         op: 'ui.angular.init',
         origin: 'auto.ui.angular.trace_class_decorator',
         start_timestamp: expect.any(Number),
@@ -255,8 +254,8 @@ test.describe('TraceClassDecorator', () => {
   });
 });
 
-test.describe('TraceMethodDecorator', () => {
-  test('instruments decorated methods (`ngOnInit` and `ngAfterViewInit`)', async ({ page }) => {
+test.describe('TraceMethod Decorator', () => {
+  test('adds name to span description of decorated method `ngOnInit`', async ({ page }) => {
     const navigationTxnPromise = waitForTransaction('angular-17', async transactionEvent => {
       return !!transactionEvent?.transaction && transactionEvent.contexts?.trace?.op === 'navigation';
     });
@@ -267,7 +266,6 @@ test.describe('TraceMethodDecorator', () => {
     const [_, navigationTxn] = await Promise.all([page.locator('#componentTracking').click(), navigationTxnPromise]);
 
     const ngInitSpan = navigationTxn.spans?.find(span => span.op === 'ui.angular.ngOnInit');
-    const ngAfterViewInitSpan = navigationTxn.spans?.find(span => span.op === 'ui.angular.ngAfterViewInit');
 
     expect(ngInitSpan).toBeDefined();
     expect(ngInitSpan).toEqual(
@@ -276,14 +274,26 @@ test.describe('TraceMethodDecorator', () => {
           [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'ui.angular.ngOnInit',
           [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.ui.angular.trace_method_decorator',
         },
-        // todo: right now, it shows the minified version of the component name - we will add a name input to the Decorator
-        description: expect.any(String),
+        description: '<ngOnInit>',
         op: 'ui.angular.ngOnInit',
         origin: 'auto.ui.angular.trace_method_decorator',
         start_timestamp: expect.any(Number),
         timestamp: expect.any(Number),
       }),
     );
+  });
+
+  test('adds fallback name to span description of decorated method `ngAfterViewInit`', async ({ page }) => {
+    const navigationTxnPromise = waitForTransaction('angular-17', async transactionEvent => {
+      return !!transactionEvent?.transaction && transactionEvent.contexts?.trace?.op === 'navigation';
+    });
+
+    await page.goto(`/`);
+
+    // immediately navigate to a different route
+    const [_, navigationTxn] = await Promise.all([page.locator('#componentTracking').click(), navigationTxnPromise]);
+
+    const ngAfterViewInitSpan = navigationTxn.spans?.find(span => span.op === 'ui.angular.ngAfterViewInit');
 
     expect(ngAfterViewInitSpan).toBeDefined();
     expect(ngAfterViewInitSpan).toEqual(
@@ -292,8 +302,7 @@ test.describe('TraceMethodDecorator', () => {
           [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'ui.angular.ngAfterViewInit',
           [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.ui.angular.trace_method_decorator',
         },
-        // todo: right now, it shows the minified version of the component name - we will add a name input to the Decorator
-        description: expect.any(String),
+        description: '<unnamed>',
         op: 'ui.angular.ngAfterViewInit',
         origin: 'auto.ui.angular.trace_method_decorator',
         start_timestamp: expect.any(Number),

packages/angular-ivy/README.md

@@ -181,34 +181,34 @@ Then, inside your component's template (keep in mind that the directive's name a
 <app-footer trace="footer"></app-footer>
 ```
 
-_TraceClassDecorator:_ used to track a duration between `OnInit` and `AfterViewInit` lifecycle hooks in components:
+_TraceClass:_ used to track a duration between `OnInit` and `AfterViewInit` lifecycle hooks in components:
 
 ```javascript
 import { Component } from '@angular/core';
-import { TraceClassDecorator } from '@sentry/angular-ivy';
+import { TraceClass } from '@sentry/angular-ivy';
 
 @Component({
   selector: 'layout-header',
   templateUrl: './header.component.html',
 })
-@TraceClassDecorator()
+@TraceClass()
 export class HeaderComponent {
   // ...
 }
 ```
 
-_TraceMethodDecorator:_ used to track a specific lifecycle hooks as point-in-time spans in components:
+_TraceMethod:_ used to track a specific lifecycle hooks as point-in-time spans in components:
 
 ```javascript
 import { Component, OnInit } from '@angular/core';
-import { TraceMethodDecorator } from '@sentry/angular-ivy';
+import { TraceMethod } from '@sentry/angular-ivy';
 
 @Component({
   selector: 'app-footer',
   templateUrl: './footer.component.html',
 })
 export class FooterComponent implements OnInit {
-  @TraceMethodDecorator()
+  @TraceMethod()
   ngOnInit() {}
 }
 ```

packages/angular/README.md

@@ -181,34 +181,34 @@ Then, inside your component's template (keep in mind that the directive's name a
 <app-footer trace="footer"></app-footer>
 ```
 
-_TraceClassDecorator:_ used to track a duration between `OnInit` and `AfterViewInit` lifecycle hooks in components:
+_TraceClass:_ used to track a duration between `OnInit` and `AfterViewInit` lifecycle hooks in components:
 
 ```javascript
 import { Component } from '@angular/core';
-import { TraceClassDecorator } from '@sentry/angular';
+import { TraceClass } from '@sentry/angular';
 
 @Component({
   selector: 'layout-header',
   templateUrl: './header.component.html',
 })
-@TraceClassDecorator()
+@TraceClass()
 export class HeaderComponent {
   // ...
 }
 ```
 
-_TraceMethodDecorator:_ used to track a specific lifecycle hooks as point-in-time spans in components:
+_TraceMethod:_ used to track a specific lifecycle hooks as point-in-time spans in components:
 
 ```javascript
 import { Component, OnInit } from '@angular/core';
-import { TraceMethodDecorator } from '@sentry/angular';
+import { TraceMethod } from '@sentry/angular';
 
 @Component({
   selector: 'app-footer',
   templateUrl: './footer.component.html',
 })
 export class FooterComponent implements OnInit {
-  @TraceMethodDecorator()
+  @TraceMethod()
   ngOnInit() {}
 }
 ```

packages/angular/src/index.ts

@@ -6,8 +6,8 @@ export { init } from './sdk';
 export { createErrorHandler, SentryErrorHandler } from './errorhandler';
 export {
   browserTracingIntegration,
-  TraceClassDecorator,
-  TraceMethodDecorator,
+  TraceClass,
+  TraceMethod,
   TraceDirective,
   TraceModule,
   TraceService,

packages/angular/src/tracing.ts

@@ -280,10 +280,17 @@ export class TraceDirective implements OnInit, AfterViewInit {
 })
 export class TraceModule {}
 
+interface TraceClassOptions {
+  /**
+   * Name of the class
+   */
+  name?: string;
+}
+
 /**
  * Decorator function that can be used to capture initialization lifecycle of the whole component.
  */
-export function TraceClassDecorator(): ClassDecorator {
+export function TraceClass(options?: TraceClassOptions): ClassDecorator {
   let tracingSpan: Span;
 
   /* eslint-disable @typescript-eslint/no-unsafe-member-access */
@@ -293,7 +300,7 @@ export function TraceClassDecorator(): ClassDecorator {
     target.prototype.ngOnInit = function (...args: any[]): ReturnType<typeof originalOnInit> {
       tracingSpan = startInactiveSpan({
         onlyIfParent: true,
-        name: `<${target.name}>`,
+        name: `<${options && options.name ? options.name : 'unnamed'}>`,
         op: ANGULAR_INIT_OP,
         attributes: {
           [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.ui.angular.trace_class_decorator',
@@ -319,10 +326,17 @@ export function TraceClassDecorator(): ClassDecorator {
   /* eslint-enable @typescript-eslint/no-unsafe-member-access */
 }
 
+interface TraceMethodOptions {
+  /**
+   * Name of the method (is added to the tracing span)
+   */
+  name?: string;
+}
+
 /**
  * Decorator function that can be used to capture a single lifecycle methods of the component.
  */
-export function TraceMethodDecorator(): MethodDecorator {
+export function TraceMethod(options?: TraceMethodOptions): MethodDecorator {
   // eslint-disable-next-line @typescript-eslint/ban-types
   return (target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
     const originalMethod = descriptor.value;
@@ -332,7 +346,7 @@ export function TraceMethodDecorator(): MethodDecorator {
 
       startInactiveSpan({
         onlyIfParent: true,
-        name: `<${target.constructor.name}>`,
+        name: `<${options && options.name ? options.name : 'unnamed'}>`,
         op: `${ANGULAR_OP}.${String(propertyKey)}`,
         startTime: now,
         attributes: {