feat(core): Decouple scope.transactionName from root spans

Author: Lms24

packages/core/src/scope.ts

@@ -81,6 +81,9 @@ export class Scope implements ScopeInterface {
 
   /**
    * Transaction Name
+   *
+   * IMPORTANT: The transaction name on the scope has nothing to do with root spans/transaction objects.
+   * It's purpose is to assign a transaction to the scope that's added to non-transaction events.
    */
   protected _transactionName?: string;
 
@@ -278,7 +281,7 @@ export class Scope implements ScopeInterface {
   }
 
   /**
-   * Sets the transaction name on the scope for future events.
+   * @inheritDoc
    */
   public setTransactionName(name?: string): this {
     this._transactionName = name;

packages/core/src/utils/applyScopeDataToEvent.ts

@@ -39,7 +39,6 @@ export function mergeScopeData(data: ScopeData, mergeData: ScopeData): void {
     eventProcessors,
     attachments,
     propagationContext,
-    // eslint-disable-next-line deprecation/deprecation
     transactionName,
     span,
   } = mergeData;
@@ -55,7 +54,6 @@ export function mergeScopeData(data: ScopeData, mergeData: ScopeData): void {
   }
 
   if (transactionName) {
-    // eslint-disable-next-line deprecation/deprecation
     data.transactionName = transactionName;
   }
 
@@ -119,15 +117,7 @@ export function mergeArray<Prop extends 'breadcrumbs' | 'fingerprint'>(
 }
 
 function applyDataToEvent(event: Event, data: ScopeData): void {
-  const {
-    extra,
-    tags,
-    user,
-    contexts,
-    level,
-    // eslint-disable-next-line deprecation/deprecation
-    transactionName,
-  } = data;
+  const { extra, tags, user, contexts, level, transactionName } = data;
 
   const cleanedExtra = dropUndefinedKeys(extra);
   if (cleanedExtra && Object.keys(cleanedExtra).length) {
@@ -153,7 +143,7 @@ function applyDataToEvent(event: Event, data: ScopeData): void {
     event.level = level;
   }
 
-  if (transactionName) {
+  if (transactionName && event.type !== 'transaction') {
     event.transaction = transactionName;
   }
 }
@@ -180,7 +170,7 @@ function applySpanToEvent(event: Event, span: Span): void {
     };
 
     const transactionName = spanToJSON(rootSpan).description;
-    if (transactionName && !event.transaction) {
+    if (transactionName && !event.transaction && event.type === 'transaction') {
       event.transaction = transactionName;
     }
   }

packages/core/test/lib/utils/applyScopeDataToEvent.test.ts

@@ -1,5 +1,11 @@
-import type { Attachment, Breadcrumb, EventProcessor, ScopeData } from '@sentry/types';
-import { mergeAndOverwriteScopeData, mergeArray, mergeScopeData } from '../../../src/utils/applyScopeDataToEvent';
+import type { Attachment, Breadcrumb, Event, EventProcessor, EventType, ScopeData } from '@sentry/types';
+import { startInactiveSpan } from '../../../src';
+import {
+  applyScopeDataToEvent,
+  mergeAndOverwriteScopeData,
+  mergeArray,
+  mergeScopeData,
+} from '../../../src/utils/applyScopeDataToEvent';
 
 describe('mergeArray', () => {
   it.each([
@@ -158,3 +164,72 @@ describe('mergeScopeData', () => {
     });
   });
 });
+
+describe('applyScopeDataToEvent', () => {
+  it("doesn't apply scope.transactionName to transaction events", () => {
+    const data: ScopeData = {
+      eventProcessors: [],
+      breadcrumbs: [],
+      user: {},
+      tags: {},
+      extra: {},
+      contexts: {},
+      attachments: [],
+      propagationContext: { spanId: '1', traceId: '1' },
+      sdkProcessingMetadata: {},
+      fingerprint: [],
+      transactionName: 'foo',
+    };
+    const event: Event = { type: 'transaction', transaction: '/users/:id' };
+
+    applyScopeDataToEvent(event, data);
+
+    expect(event.transaction).toBe('/users/:id');
+  });
+
+  it("doesn't the root span name to non-transaction events", () => {
+    const data: ScopeData = {
+      eventProcessors: [],
+      breadcrumbs: [],
+      user: {},
+      tags: {},
+      extra: {},
+      contexts: {},
+      attachments: [],
+      propagationContext: { spanId: '1', traceId: '1' },
+      sdkProcessingMetadata: {},
+      fingerprint: [],
+      transactionName: '/users/:id',
+      span: startInactiveSpan({ name: 'foo' }),
+    };
+    const event: Event = { type: undefined };
+
+    applyScopeDataToEvent(event, data);
+
+    expect(event.transaction).toBe('/users/:id');
+  });
+
+  it.each([undefined, 'profile', 'replay_event', 'feedback'])(
+    'applies scope.transactionName to event with type %s',
+    type => {
+      const data: ScopeData = {
+        eventProcessors: [],
+        breadcrumbs: [],
+        user: {},
+        tags: {},
+        extra: {},
+        contexts: {},
+        attachments: [],
+        propagationContext: { spanId: '1', traceId: '1' },
+        sdkProcessingMetadata: {},
+        fingerprint: [],
+        transactionName: 'foo',
+      };
+      const event: Event = { type: type as EventType, transaction: '/users/:id' };
+
+      applyScopeDataToEvent(event, data);
+
+      expect(event.transaction).toBe('foo');
+    },
+  );
+});

packages/types/src/scope.ts

@@ -40,7 +40,6 @@ export interface ScopeData {
   sdkProcessingMetadata: { [key: string]: unknown };
   fingerprint: string[];
   level?: SeverityLevel;
-  /** @deprecated This will be removed in v8. */
   transactionName?: string;
   span?: Span;
 }
@@ -127,7 +126,15 @@ export interface Scope {
   setLevel(level: SeverityLevel): this;
 
   /**
-   * Sets the transaction name on the scope for future events.
+   * Sets the transaction name on the scope so that the name of the transaction
+   * (e.g. taken server route or page location) is attached to future events.
+   *
+   * IMPORTANT: Calling this function does NOT change the name of the currently active
+   * span. If you want to change the name of the active span, use `span.updateName()`
+   * instead.
+   *
+   * By default, the SDK updates the scope's transaction name automatically on sensible
+   * occasions, such as a page navigation or when handling a new request on the server.
    */
   setTransactionName(name?: string): this;