feat(core): Deprecate span name and description (#10056)

Instead, users should use `spanToJSON(span).description`.

In reality, users should mostly not actually need this - most usages are
internal things, or tests, right now.

While at this, I also updated the `TraceContext` type to not have a
`description`. This started failing in a bunch of tests, because while
in theory the trace context has a `description` field, in praxis we
always used to set `description` to `undefined` for transactions,
leading to this never being set. The work in this PR unifies the
name/description handling between span and transaction, which lead to
`description` not being undefined for transactions anymore, leading to
this actually showing up in the trace context.

Author: mydea

MIGRATION.md

@@ -71,6 +71,8 @@ In v8, the Span class is heavily reworked. The following properties & methods ar
 * `span.sampled`: Use `span.isRecording()` instead.
 * `span.spanId`: Use `span.spanContext().spanId` instead.
 * `span.traceId`: Use `span.spanContext().traceId` instead.
+* `span.name`: Use `spanToJSON(span).description` instead.
+* `span.description`: Use `spanToJSON(span).description` instead.
 
 ## Deprecate `pushScope` & `popScope` in favor of `withScope`
 

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 { spanToJSON } 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: ${spanToJSON(transaction).description}`);
   }
 
   // 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:', spanToJSON(transaction).description, '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: ${spanToJSON(transaction).description}`);
         }
 
         // 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: ${spanToJSON(transaction).description}`,
               'this may indicate an overlapping transaction or a call to stopProfiling with a profile title that was never started',
             );
           }
@@ -135,7 +132,7 @@ export function startProfileForTransaction(transaction: Transaction): Transactio
     if (DEBUG_BUILD) {
       logger.log(
         '[Profiling] max profile duration elapsed, stopping profiling for:',
-        transaction.name || transaction.description,
+        spanToJSON(transaction).description,
       );
     }
     // If the timeout exceeds, we want to stop profiling, but not finish the transaction

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, spanToJSON } 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(spanToJSON(transaction).description).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(spanToJSON(transaction).description).toEqual('POST /');
     });
 
     const server = Bun.serve({

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 { spanToJSON } 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 = spanToJSON(transaction).description || '';
+
         // 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 { spanToJSON } 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 = spanToJSON(transaction).description || '';
     }
 
     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 { spanToJSON } from '../utils/spanUtils';
 import type { Transaction } from './transaction';
 
 /**
@@ -100,7 +101,8 @@ 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 - ${spanToJSON(transaction).description}`);
   return transaction;
 }
 

packages/core/src/tracing/span.ts

@@ -20,6 +20,7 @@ import {
   TRACE_FLAG_NONE,
   TRACE_FLAG_SAMPLED,
   spanTimeInputToSeconds,
+  spanToJSON,
   spanToTraceContext,
   spanToTraceHeader,
 } from '../utils/spanUtils';
@@ -84,11 +85,6 @@ export class Span implements SpanInterface {
    */
   public op?: string;
 
-  /**
-   * @inheritDoc
-   */
-  public description?: string;
-
   /**
    * @inheritDoc
    */
@@ -128,6 +124,7 @@ export class Span implements SpanInterface {
   protected _traceId: string;
   protected _spanId: string;
   protected _sampled: boolean | undefined;
+  protected _name?: string;
 
   /**
    * You should never call the constructor manually, always use `Sentry.startTransaction()`
@@ -145,6 +142,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;
@@ -156,12 +155,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;
     }
@@ -170,20 +163,40 @@ export class Span implements SpanInterface {
     }
   }
 
-  // This conflicts with another eslint rule :(
+  // This rule conflicts with another rule :(
   /* eslint-disable @typescript-eslint/member-ordering */
 
-  /** An alias for `description` of the Span. */
+  /**
+   * An alias for `description` of the Span.
+   * @deprecated Use `spanToJSON(span).description` instead.
+   */
   public get name(): string {
-    return this.description || '';
+    return this._name || '';
   }
   /**
    * Update the name of the span.
+   * @deprecated Use `spanToJSON(span).description` instead.
    */
   public set name(name: string) {
     this.updateName(name);
   }
 
+  /**
+   * Get the description of the Span.
+   * @deprecated Use `spanToJSON(span).description` instead.
+   */
+  public get description(): string | undefined {
+    return this._name;
+  }
+
+  /**
+   * Get the description of the Span.
+   * @deprecated Use `spanToJSON(span).description` instead.
+   */
+  public set description(description: string | undefined) {
+    this._name = description;
+  }
+
   /**
    * The ID of the trace.
    * @deprecated Use `spanContext().traceId` instead.
@@ -269,7 +282,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 = spanToJSON(childSpan).description || '< unknown name >';
       const idStr = childSpan.transaction.spanContext().spanId;
 
       const logMessage = `[Tracing] Starting '${opStr}' span on transaction '${nameStr}' (${idStr}).`;
@@ -342,7 +355,7 @@ export class Span implements SpanInterface {
    * @inheritDoc
    */
   public updateName(name: string): this {
-    this.description = name;
+    this._name = name;
     return this;
   }
 
@@ -392,7 +405,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,
@@ -410,7 +423,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;
@@ -437,7 +451,7 @@ export class Span implements SpanInterface {
   public getSpanJSON(): SpanJSON {
     return dropUndefinedKeys({
       data: this._getData(),
-      description: this.description,
+      description: this._name,
       op: this.op,
       parent_span_id: this.parentSpanId,
       span_id: this._spanId,

packages/core/src/tracing/trace.ts

@@ -39,12 +39,11 @@ export function trace<T>(
   // eslint-disable-next-line @typescript-eslint/no-empty-function
   afterFinish: () => void = () => {},
 ): T {
-  const ctx = normalizeContext(context);
-
   const hub = getCurrentHub();
   const scope = getCurrentScope();
   const parentSpan = scope.getSpan();
 
+  const ctx = normalizeContext(context);
   const activeSpan = createChildSpanOrTransaction(hub, parentSpan, ctx);
 
   scope.setSpan(activeSpan);
@@ -259,16 +258,12 @@ function createChildSpanOrTransaction(
  * Eventually the StartSpanOptions will be more aligned with OpenTelemetry.
  */
 function normalizeContext(context: StartSpanOptions): TransactionContext {
-  const ctx = { ...context };
-  // If a name is set and a description is not, set the description to the name.
-  if (ctx.name !== undefined && ctx.description === undefined) {
-    ctx.description = ctx.name;
-  }
-
   if (context.startTime) {
+    const ctx = { ...context };
     ctx.startTimestamp = spanTimeInputToSeconds(context.startTime);
     delete ctx.startTime;
+    return ctx;
   }
 
-  return ctx;
+  return context;
 }