feat(core): Deprecate span name and description

Instead, users should use `spanGetName(span)`.

Author: mydea

dev-packages/browser-integration-tests/suites/public-api/startSpan/basic/test.ts

@@ -29,6 +29,7 @@ sentryTest('should report finished spans as children of the root transaction', a
   expect(transaction.spans).toHaveLength(1);
 
   const span_1 = transaction.spans?.[0];
+  // eslint-disable-next-line deprecation/deprecation
   expect(span_1?.description).toBe('child_span');
   expect(span_1?.parentSpanId).toEqual(rootSpanId);
 });

dev-packages/browser-integration-tests/suites/tracing/metrics/web-vitals-fid/test.ts

@@ -21,6 +21,7 @@ sentryTest('should capture a FID vital.', async ({ browserName, getLocalTestPath
   expect(eventData.measurements).toBeDefined();
   expect(eventData.measurements?.fid?.value).toBeDefined();
 
+  // eslint-disable-next-line deprecation/deprecation
   const fidSpan = eventData.spans?.filter(({ description }) => description === 'first input delay')[0];
 
   expect(fidSpan).toBeDefined();

dev-packages/browser-integration-tests/suites/tracing/metrics/web-vitals-fp-fcp/test.ts

@@ -16,6 +16,7 @@ sentryTest('should capture FP vital.', async ({ browserName, getLocalTestPath, p
   expect(eventData.measurements).toBeDefined();
   expect(eventData.measurements?.fp?.value).toBeDefined();
 
+  // eslint-disable-next-line deprecation/deprecation
   const fpSpan = eventData.spans?.filter(({ description }) => description === 'first-paint')[0];
 
   expect(fpSpan).toBeDefined();
@@ -34,6 +35,7 @@ sentryTest('should capture FCP vital.', async ({ getLocalTestPath, page }) => {
   expect(eventData.measurements).toBeDefined();
   expect(eventData.measurements?.fcp?.value).toBeDefined();
 
+  // eslint-disable-next-line deprecation/deprecation
   const fcpSpan = eventData.spans?.filter(({ description }) => description === 'first-contentful-paint')[0];
 
   expect(fcpSpan).toBeDefined();

packages/browser/src/profiling/hubextensions.ts

@@ -1,4 +1,5 @@
 /* eslint-disable complexity */
+import { spanGetName } from '@sentry/core';
 import type { Transaction } from '@sentry/types';
 import { logger, timestampInSeconds, uuid4 } from '@sentry/utils';
 
@@ -56,7 +57,7 @@ export function startProfileForTransaction(transaction: Transaction): Transactio
   }
 
   if (DEBUG_BUILD) {
-    logger.log(`[Profiling] started profiling transaction: ${transaction.name || transaction.description}`);
+    logger.log(`[Profiling] started profiling transaction: ${spanGetName(transaction)}`);
   }
 
   // We create "unique" transaction names to avoid concurrent transactions with same names
@@ -87,11 +88,7 @@ export function startProfileForTransaction(transaction: Transaction): Transactio
     }
     if (processedProfile) {
       if (DEBUG_BUILD) {
-        logger.log(
-          '[Profiling] profile for:',
-          transaction.name || transaction.description,
-          'already exists, returning early',
-        );
+        logger.log('[Profiling] profile for:', spanGetName(transaction), 'already exists, returning early');
       }
       return null;
     }
@@ -105,14 +102,14 @@ export function startProfileForTransaction(transaction: Transaction): Transactio
         }
 
         if (DEBUG_BUILD) {
-          logger.log(`[Profiling] stopped profiling of transaction: ${transaction.name || transaction.description}`);
+          logger.log(`[Profiling] stopped profiling of transaction: ${spanGetName(transaction)}`);
         }
 
         // In case of an overlapping transaction, stopProfiling may return null and silently ignore the overlapping profile.
         if (!profile) {
           if (DEBUG_BUILD) {
             logger.log(
-              `[Profiling] profiler returned null profile for: ${transaction.name || transaction.description}`,
+              `[Profiling] profiler returned null profile for: ${spanGetName(transaction)}`,
               'this may indicate an overlapping transaction or a call to stopProfiling with a profile title that was never started',
             );
           }
@@ -133,10 +130,7 @@ export function startProfileForTransaction(transaction: Transaction): Transactio
   // Enqueue a timeout to prevent profiles from running over max duration.
   let maxDurationTimeoutID: number | undefined = WINDOW.setTimeout(() => {
     if (DEBUG_BUILD) {
-      logger.log(
-        '[Profiling] max profile duration elapsed, stopping profiling for:',
-        transaction.name || transaction.description,
-      );
+      logger.log('[Profiling] max profile duration elapsed, stopping profiling for:', spanGetName(transaction));
     }
     // If the timeout exceeds, we want to stop profiling, but not finish the transaction
     // eslint-disable-next-line @typescript-eslint/no-floating-promises

packages/bun/test/integrations/bunserver.test.ts

@@ -1,5 +1,5 @@
 import { beforeAll, beforeEach, describe, expect, test } from 'bun:test';
-import { Hub, makeMain } from '@sentry/core';
+import { Hub, makeMain, spanGetName } from '@sentry/core';
 
 import { BunClient } from '../../src/client';
 import { instrumentBunServe } from '../../src/integrations/bunserver';
@@ -30,7 +30,7 @@ describe('Bun Serve Integration', () => {
         'http.status_code': '200',
       });
       expect(transaction.op).toEqual('http.server');
-      expect(transaction.name).toEqual('GET /');
+      expect(spanGetName(transaction)).toEqual('GET /');
     });
 
     const server = Bun.serve({
@@ -52,7 +52,7 @@ describe('Bun Serve Integration', () => {
         'http.status_code': '200',
       });
       expect(transaction.op).toEqual('http.server');
-      expect(transaction.name).toEqual('POST /');
+      expect(spanGetName(transaction)).toEqual('POST /');
     });
 
     const server = Bun.serve({

packages/core/src/index.ts

@@ -71,7 +71,7 @@ export { createCheckInEnvelope } from './checkin';
 export { hasTracingEnabled } from './utils/hasTracingEnabled';
 export { isSentryRequestUrl } from './utils/isSentryRequestUrl';
 export { handleCallbackErrors } from './utils/handleCallbackErrors';
-export { spanToTraceHeader } from './utils/spanUtils';
+export { spanToTraceHeader, spanGetName } from './utils/spanUtils';
 export { DEFAULT_ENVIRONMENT } from './constants';
 export { ModuleMetadata } from './integrations/metadata';
 export { RequestData } from './integrations/requestdata';

packages/core/src/integrations/requestdata.ts

@@ -2,6 +2,7 @@ import type { Client, IntegrationFn, Transaction } from '@sentry/types';
 import type { AddRequestDataToEventOptions, TransactionNamingScheme } from '@sentry/utils';
 import { addRequestDataToEvent, extractPathForTransaction } from '@sentry/utils';
 import { convertIntegrationFnToClass } from '../integration';
+import { spanGetName } from '../utils/spanUtils';
 
 export type RequestDataIntegrationOptions = {
   /**
@@ -105,18 +106,20 @@ const requestDataIntegration: IntegrationFn = (options: RequestDataIntegrationOp
       const reqWithTransaction = req as { _sentryTransaction?: Transaction };
       const transaction = reqWithTransaction._sentryTransaction;
       if (transaction) {
+        const name = spanGetName(transaction);
+
         // TODO (v8): Remove the nextjs check and just base it on `transactionNamingScheme` for all SDKs. (We have to
         // keep it the way it is for the moment, because changing the names of transactions in Sentry has the potential
         // to break things like alert rules.)
         const shouldIncludeMethodInTransactionName =
           getSDKName(client) === 'sentry.javascript.nextjs'
-            ? transaction.name.startsWith('/api')
+            ? name.startsWith('/api')
             : transactionNamingScheme !== 'path';
 
         const [transactionValue] = extractPathForTransaction(req, {
           path: true,
           method: shouldIncludeMethodInTransactionName,
-          customRoute: transaction.name,
+          customRoute: name,
         });
 
         processedEvent.transaction = transactionValue;

packages/core/src/metrics/exports.ts

@@ -3,6 +3,7 @@ import { logger } from '@sentry/utils';
 import type { BaseClient } from '../baseclient';
 import { DEBUG_BUILD } from '../debug-build';
 import { getClient, getCurrentScope } from '../exports';
+import { spanGetName } from '../utils/spanUtils';
 import { COUNTER_METRIC_TYPE, DISTRIBUTION_METRIC_TYPE, GAUGE_METRIC_TYPE, SET_METRIC_TYPE } from './constants';
 import { MetricsAggregator } from './integration';
 import type { MetricType } from './types';
@@ -38,7 +39,7 @@ function addToMetricsAggregator(
       metricTags.environment = environment;
     }
     if (transaction) {
-      metricTags.transaction = transaction.name;
+      metricTags.transaction = spanGetName(transaction);
     }
 
     DEBUG_BUILD && logger.log(`Adding value of ${value} to ${metricType} metric ${name}`);

packages/core/src/tracing/sampling.ts

@@ -3,6 +3,7 @@ import { isNaN, logger } from '@sentry/utils';
 
 import { DEBUG_BUILD } from '../debug-build';
 import { hasTracingEnabled } from '../utils/hasTracingEnabled';
+import { spanGetName } from '../utils/spanUtils';
 import type { Transaction } from './transaction';
 
 /**
@@ -93,7 +94,7 @@ export function sampleTransaction<T extends Transaction>(
     return transaction;
   }
 
-  DEBUG_BUILD && logger.log(`[Tracing] starting ${transaction.op} transaction - ${transaction.name}`);
+  DEBUG_BUILD && logger.log(`[Tracing] starting ${transaction.op} transaction - ${spanGetName(transaction)}`);
   return transaction;
 }
 

packages/core/src/tracing/span.ts

@@ -13,7 +13,7 @@ import type {
 import { dropUndefinedKeys, logger, timestampInSeconds, uuid4 } from '@sentry/utils';
 
 import { DEBUG_BUILD } from '../debug-build';
-import { spanToTraceContext, spanToTraceHeader } from '../utils/spanUtils';
+import { spanGetName, spanToTraceContext, spanToTraceHeader } from '../utils/spanUtils';
 import { ensureTimestampInSeconds } from './utils';
 
 /**
@@ -91,11 +91,6 @@ export class Span implements SpanInterface {
    */
   public op?: string;
 
-  /**
-   * @inheritDoc
-   */
-  public description?: string;
-
   /**
    * @inheritDoc
    */
@@ -132,6 +127,8 @@ export class Span implements SpanInterface {
    */
   public origin?: SpanOrigin;
 
+  protected _name?: string;
+
   /**
    * You should never call the constructor manually, always use `Sentry.startTransaction()`
    * or call `startChild()` on an existing span.
@@ -148,6 +145,8 @@ export class Span implements SpanInterface {
     this.attributes = spanContext.attributes || {};
     this.instrumenter = spanContext.instrumenter || 'sentry';
     this.origin = spanContext.origin || 'manual';
+    // eslint-disable-next-line deprecation/deprecation
+    this._name = spanContext.name || spanContext.description;
 
     if (spanContext.parentSpanId) {
       this.parentSpanId = spanContext.parentSpanId;
@@ -159,12 +158,6 @@ export class Span implements SpanInterface {
     if (spanContext.op) {
       this.op = spanContext.op;
     }
-    if (spanContext.description) {
-      this.description = spanContext.description;
-    }
-    if (spanContext.name) {
-      this.description = spanContext.name;
-    }
     if (spanContext.status) {
       this.status = spanContext.status;
     }
@@ -173,8 +166,15 @@ export class Span implements SpanInterface {
     }
   }
 
-  /** An alias for `description` of the Span. */
+  // This rule conflicts with another rule :()
+  /* eslint-disable @typescript-eslint/member-ordering */
+
+  /**
+   * An alias for `description` of the Span.
+   * @deprecated Use `spanGetName(span)` instead.
+   */
   public get name(): string {
+    // eslint-disable-next-line deprecation/deprecation
     return this.description || '';
   }
   /**
@@ -184,6 +184,24 @@ export class Span implements SpanInterface {
     this.updateName(name);
   }
 
+  /**
+   * Get the description of the Span.
+   * @deprecated Use `spanGetName(span)` instead.
+   */
+  public get description(): string | undefined {
+    return this._name;
+  }
+
+  /**
+   * Get the description of the Span.
+   * @deprecated Use `spanGetName(span)` instead.
+   */
+  public set description(description: string | undefined) {
+    this._name = description;
+  }
+
+  /* eslint-enable @typescript-eslint/member-ordering */
+
   /**
    * @inheritDoc
    */
@@ -206,7 +224,7 @@ export class Span implements SpanInterface {
 
     if (DEBUG_BUILD && childSpan.transaction) {
       const opStr = (spanContext && spanContext.op) || '< unknown op >';
-      const nameStr = childSpan.transaction.name || '< unknown name >';
+      const nameStr = spanGetName(childSpan) || '< unknown name >';
       const idStr = childSpan.transaction.spanId;
 
       const logMessage = `[Tracing] Starting '${opStr}' span on transaction '${nameStr}' (${idStr}).`;
@@ -279,7 +297,7 @@ export class Span implements SpanInterface {
    * @inheritDoc
    */
   public updateName(name: string): this {
-    this.description = name;
+    this._name = name;
     return this;
   }
 
@@ -330,7 +348,7 @@ export class Span implements SpanInterface {
   public toContext(): SpanContext {
     return dropUndefinedKeys({
       data: this._getData(),
-      description: this.description,
+      description: this._name,
       endTimestamp: this.endTimestamp,
       op: this.op,
       parentSpanId: this.parentSpanId,
@@ -348,7 +366,8 @@ export class Span implements SpanInterface {
    */
   public updateWithContext(spanContext: SpanContext): this {
     this.data = spanContext.data || {};
-    this.description = spanContext.description;
+    // eslint-disable-next-line deprecation/deprecation
+    this._name = spanContext.name || spanContext.description;
     this.endTimestamp = spanContext.endTimestamp;
     this.op = spanContext.op;
     this.parentSpanId = spanContext.parentSpanId;
@@ -388,7 +407,7 @@ export class Span implements SpanInterface {
   } {
     return dropUndefinedKeys({
       data: this._getData(),
-      description: this.description,
+      description: this._name,
       op: this.op,
       parent_span_id: this.parentSpanId,
       span_id: this.spanId,