feat(core): Deprecate span tags, data, context & setters (#10053)

Also deprecate direct access to `span.attributes` (instead use
`spanToJSON(span)`).

There are a few usages that we still need to figure out how we will
replace them...!

MIGRATION.md

@@ -100,6 +100,11 @@ In v8, the Span class is heavily reworked. The following properties & methods ar
 * `span.description`: Use `spanToJSON(span).description` instead.
 * `transaction.setMetadata()`: Use attributes instead, or set data on the scope.
 * `transaction.metadata`: Use attributes instead, or set data on the scope.
+* `span.tags`: Set tags on the surrounding scope instead, or use attributes.
+* `span.data`: Use `spanToJSON(span).data` instead.
+* `span.setTag()`: Use `span.setAttribute()` instead or set tags on the surrounding scope.
+* `span.setData()`: Use `span.setAttribute()` instead.
+* `transaction.setContext()`: Set context on the surrounding scope instead.
 
 ## Deprecate `pushScope` & `popScope` in favor of `withScope`
 

dev-packages/browser-integration-tests/suites/public-api/startTransaction/basic_usage/test.ts

@@ -31,6 +31,7 @@ sentryTest('should report finished spans as children of the root transaction', a
   const span_1 = transaction.spans?.[0];
   expect(span_1?.op).toBe('span_1');
   expect(span_1?.parentSpanId).toEqual(rootSpanId);
+  // eslint-disable-next-line deprecation/deprecation
   expect(span_1?.data).toMatchObject({ foo: 'bar', baz: [1, 2, 3] });
 
   const span_3 = transaction.spans?.[1];

dev-packages/e2e-tests/test-applications/nextjs-app-dir/tests/transactions.test.ts

@@ -130,9 +130,9 @@ test('Should send a transaction for instrumented server actions', async ({ page
   await page.getByText('Run Action').click();
 
   expect(await serverComponentTransactionPromise).toBeDefined();
-  expect((await serverComponentTransactionPromise).contexts?.trace?.data?.['server_action_form_data']).toEqual(
-    expect.objectContaining({ 'some-text-value': 'some-default-value' }),
-  );
+  expect(
+    (await serverComponentTransactionPromise).contexts?.trace?.data?.['server_action_form_data.some-text-value'],
+  ).toEqual('some-default-value');
   expect((await serverComponentTransactionPromise).contexts?.trace?.data?.['server_action_result']).toEqual({
     city: 'Vienna',
   });

dev-packages/node-integration-tests/suites/tracing-new/auto-instrument/mysql/withoutCallback/scenario.ts

@@ -32,10 +32,10 @@ const query = connection.query('SELECT 1 + 1 AS solution');
 const query2 = connection.query('SELECT NOW()', ['1', '2']);
 
 query.on('end', () => {
-  transaction.setTag('result_done', 'yes');
+  transaction.setAttribute('result_done', 'yes');
 
   query2.on('end', () => {
-    transaction.setTag('result_done2', 'yes');
+    transaction.setAttribute('result_done2', 'yes');
 
     // Wait a bit to ensure the queries completed
     setTimeout(() => {

dev-packages/node-integration-tests/suites/tracing-new/auto-instrument/mysql/withoutCallback/test.ts

@@ -7,11 +7,15 @@ test('should auto-instrument `mysql` package when using query without callback',
   expect(envelope).toHaveLength(3);
 
   assertSentryTransaction(envelope[2], {
-    transaction: 'Test Transaction',
-    tags: {
-      result_done: 'yes',
-      result_done2: 'yes',
+    contexts: {
+      trace: {
+        data: {
+          result_done: 'yes',
+          result_done2: 'yes',
+        },
+      },
     },
+    transaction: 'Test Transaction',
     spans: [
       {
         description: 'SELECT 1 + 1 AS solution',

docs/v8-new-performance-apis.md

@@ -50,8 +50,8 @@ below to see which things used to exist, and how they can/should be mapped going
 | `status`              | use utility method TODO                              |
 | `sampled`             | `spanIsSampled(span)`                                |
 | `startTimestamp`      | `startTime` - note that this has a different format! |
-| `tags`                | `spanGetAttributes(span)`, or set tags on the scope  |
-| `data`                | `spanGetAttributes(span)`                            |
+| `tags`                | use attributes, or set tags on the scope             |
+| `data`                | `spanToJSON(span).data`                              |
 | `transaction`         | ??? Removed                                          |
 | `instrumenter`        | Removed                                              |
 | `finish()`            | `end()`                                              |
@@ -72,13 +72,13 @@ In addition, a transaction has this API:
 
 | Old name                    | Replace with                                     |
 | --------------------------- | ------------------------------------------------ |
-| `name`                      | `spanGetName(span)` (TODO)                       |
+| `name`                      | `spanToJSON(span).description`                   |
 | `trimEnd`                   | Removed                                          |
 | `parentSampled`             | `spanIsSampled(span)` & `spanContext().isRemote` |
-| `metadata`                  | `spanGetMetadata(span)`                          |
+| `metadata`                  | Use attributes instead or set on scope           |
 | `setContext()`              | Set context on scope instead                     |
 | `setMeasurement()`          | ??? TODO                                         |
-| `setMetadata()`             | `spanSetMetadata(span, metadata)`                |
+| `setMetadata()`             | Use attributes instead or set on scope           |
 | `getDynamicSamplingContext` | ??? TODO                                         |
 
 ### Attributes vs. Data vs. Tags vs. Context

packages/browser/src/profiling/hubextensions.ts

@@ -156,6 +156,8 @@ export function startProfileForTransaction(transaction: Transaction): Transactio
     // Always call onProfileHandler to ensure stopProfiling is called and the timeout is cleared.
     void onProfileHandler().then(
       () => {
+        // TODO: Can we rewrite this to use attributes?
+        // eslint-disable-next-line deprecation/deprecation
         transaction.setContext('profile', { profile_id: profileId, start_timestamp: startTimestamp });
         originalEnd();
       },

packages/bun/src/integrations/bunserver.ts

@@ -4,6 +4,7 @@ import {
   captureException,
   continueTrace,
   convertIntegrationFnToClass,
+  getCurrentScope,
   runWithAsyncContext,
   startSpan,
 } from '@sentry/core';
@@ -90,9 +91,10 @@ function instrumentBunServeOptions(serveOptions: Parameters<typeof Bun.serve>[0]
                   >);
                   if (response && response.status) {
                     span?.setHttpStatus(response.status);
-                    span?.setData('http.response.status_code', response.status);
+                    span?.setAttribute('http.response.status_code', response.status);
                     if (span instanceof Transaction) {
-                      span.setContext('response', {
+                      const scope = getCurrentScope();
+                      scope.setContext('response', {
                         headers: response.headers.toJSON(),
                         status_code: response.status,
                       });

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

@@ -26,6 +26,7 @@ describe('Bun Serve Integration', () => {
   test('generates a transaction around a request', async () => {
     client.on('finishTransaction', transaction => {
       expect(transaction.status).toBe('ok');
+      // eslint-disable-next-line deprecation/deprecation
       expect(transaction.tags).toEqual({
         'http.status_code': '200',
       });
@@ -48,6 +49,7 @@ describe('Bun Serve Integration', () => {
   test('generates a post transaction', async () => {
     client.on('finishTransaction', transaction => {
       expect(transaction.status).toBe('ok');
+      // eslint-disable-next-line deprecation/deprecation
       expect(transaction.tags).toEqual({
         'http.status_code': '200',
       });

packages/core/src/tracing/idletransaction.ts

@@ -146,7 +146,7 @@ export class IdleTransaction extends Transaction {
     this.activities = {};
 
     if (this.op === 'ui.action.click') {
-      this.setTag(FINISH_REASON_TAG, this._finishReason);
+      this.setAttribute(FINISH_REASON_TAG, this._finishReason);
     }
 
     if (this.spanRecorder) {

packages/core/src/tracing/span.ts

@@ -86,21 +86,18 @@ export class Span implements SpanInterface {
   public op?: string;
 
   /**
-   * @inheritDoc
+   * Tags for the span.
+   * @deprecated Use `getSpanAttributes(span)` instead.
    */
   public tags: { [key: string]: Primitive };
 
   /**
-   * @inheritDoc
+   * Data for the span.
+   * @deprecated Use `getSpanAttributes(span)` instead.
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   public data: { [key: string]: any };
 
-  /**
-   * @inheritDoc
-   */
-  public attributes: SpanAttributes;
-
   /**
    * List of spans that were finalized
    */
@@ -125,6 +122,7 @@ export class Span implements SpanInterface {
   protected _spanId: string;
   protected _sampled: boolean | undefined;
   protected _name?: string;
+  protected _attributes: SpanAttributes;
 
   private _logMessage?: string;
 
@@ -139,9 +137,11 @@ export class Span implements SpanInterface {
     this._traceId = spanContext.traceId || uuid4();
     this._spanId = spanContext.spanId || uuid4().substring(16);
     this.startTimestamp = spanContext.startTimestamp || timestampInSeconds();
+    // eslint-disable-next-line deprecation/deprecation
     this.tags = spanContext.tags ? { ...spanContext.tags } : {};
+    // eslint-disable-next-line deprecation/deprecation
     this.data = spanContext.data ? { ...spanContext.data } : {};
-    this.attributes = spanContext.attributes ? { ...spanContext.attributes } : {};
+    this._attributes = spanContext.attributes ? { ...spanContext.attributes } : {};
     this.instrumenter = spanContext.instrumenter || 'sentry';
     this.origin = spanContext.origin || 'manual';
     // eslint-disable-next-line deprecation/deprecation
@@ -165,7 +165,7 @@ export class Span implements SpanInterface {
     }
   }
 
-  // This rule conflicts with another rule :(
+  // This rule conflicts with another eslint rule :(
   /* eslint-disable @typescript-eslint/member-ordering */
 
   /**
@@ -175,6 +175,7 @@ export class Span implements SpanInterface {
   public get name(): string {
     return this._name || '';
   }
+
   /**
    * Update the name of the span.
    * @deprecated Use `spanToJSON(span).description` instead.
@@ -247,6 +248,22 @@ export class Span implements SpanInterface {
     this._sampled = sampled;
   }
 
+  /**
+   * Attributes for the span.
+   * @deprecated Use `getSpanAttributes(span)` instead.
+   */
+  public get attributes(): SpanAttributes {
+    return this._attributes;
+  }
+
+  /**
+   * Attributes for the span.
+   * @deprecated Use `setAttributes()` instead.
+   */
+  public set attributes(attributes: SpanAttributes) {
+    this._attributes = attributes;
+  }
+
   /* eslint-enable @typescript-eslint/member-ordering */
 
   /** @inheritdoc */
@@ -296,18 +313,29 @@ export class Span implements SpanInterface {
   }
 
   /**
-   * @inheritDoc
+   * Sets the tag attribute on the current span.
+   *
+   * Can also be used to unset a tag, by passing `undefined`.
+   *
+   * @param key Tag key
+   * @param value Tag value
+   * @deprecated Use `setAttribute()` instead.
    */
   public setTag(key: string, value: Primitive): this {
+    // eslint-disable-next-line deprecation/deprecation
     this.tags = { ...this.tags, [key]: value };
     return this;
   }
 
   /**
-   * @inheritDoc
+   * Sets the data attribute on the current span
+   * @param key Data key
+   * @param value Data value
+   * @deprecated Use `setAttribute()` instead.
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   public setData(key: string, value: any): this {
+    // eslint-disable-next-line deprecation/deprecation
     this.data = { ...this.data, [key]: value };
     return this;
   }
@@ -316,9 +344,9 @@ export class Span implements SpanInterface {
   public setAttribute(key: string, value: SpanAttributeValue | undefined): void {
     if (value === undefined) {
       // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
-      delete this.attributes[key];
+      delete this._attributes[key];
     } else {
-      this.attributes[key] = value;
+      this._attributes[key] = value;
     }
   }
 
@@ -339,7 +367,9 @@ export class Span implements SpanInterface {
    * @inheritDoc
    */
   public setHttpStatus(httpStatus: number): this {
+    // eslint-disable-next-line deprecation/deprecation
     this.setTag('http.status_code', String(httpStatus));
+    // eslint-disable-next-line deprecation/deprecation
     this.setData('http.response.status_code', httpStatus);
     const spanStatus = spanStatusfromHttpCode(httpStatus);
     if (spanStatus !== 'unknown_error') {
@@ -415,6 +445,7 @@ export class Span implements SpanInterface {
       spanId: this._spanId,
       startTimestamp: this.startTimestamp,
       status: this.status,
+      // eslint-disable-next-line deprecation/deprecation
       tags: this.tags,
       traceId: this._traceId,
     });
@@ -424,6 +455,7 @@ export class Span implements SpanInterface {
    * @inheritDoc
    */
   public updateWithContext(spanContext: SpanContext): this {
+    // eslint-disable-next-line deprecation/deprecation
     this.data = spanContext.data || {};
     // eslint-disable-next-line deprecation/deprecation
     this._name = spanContext.name || spanContext.description;
@@ -434,6 +466,7 @@ export class Span implements SpanInterface {
     this._spanId = spanContext.spanId || this._spanId;
     this.startTimestamp = spanContext.startTimestamp || this.startTimestamp;
     this.status = spanContext.status;
+    // eslint-disable-next-line deprecation/deprecation
     this.tags = spanContext.tags || {};
     this._traceId = spanContext.traceId || this._traceId;
 
@@ -459,6 +492,7 @@ export class Span implements SpanInterface {
       span_id: this._spanId,
       start_timestamp: this.startTimestamp,
       status: this.status,
+      // eslint-disable-next-line deprecation/deprecation
       tags: Object.keys(this.tags).length > 0 ? this.tags : undefined,
       timestamp: this.endTimestamp,
       trace_id: this._traceId,
@@ -490,7 +524,8 @@ export class Span implements SpanInterface {
         [key: string]: any;
       }
     | undefined {
-    const { data, attributes } = this;
+    // eslint-disable-next-line deprecation/deprecation
+    const { data, _attributes: attributes } = this;
 
     const hasData = Object.keys(data).length > 0;
     const hasAttributes = Object.keys(attributes).length > 0;

packages/core/src/tracing/transaction.ts

@@ -110,11 +110,11 @@ export class Transaction extends SpanClass implements TransactionInterface {
       ...this._metadata,
 
       // From attributes
-      ...(this.attributes[SEMANTIC_ATTRIBUTE_SENTRY_SOURCE] && {
-        source: this.attributes[SEMANTIC_ATTRIBUTE_SENTRY_SOURCE] as TransactionMetadata['source'],
+      ...(this._attributes[SEMANTIC_ATTRIBUTE_SENTRY_SOURCE] && {
+        source: this._attributes[SEMANTIC_ATTRIBUTE_SENTRY_SOURCE] as TransactionMetadata['source'],
       }),
-      ...(this.attributes[SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE] && {
-        sampleRate: this.attributes[SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE] as TransactionMetadata['sampleRate'],
+      ...(this._attributes[SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE] && {
+        sampleRate: this._attributes[SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE] as TransactionMetadata['sampleRate'],
       }),
     };
   }
@@ -157,7 +157,8 @@ export class Transaction extends SpanClass implements TransactionInterface {
   }
 
   /**
-   * @inheritDoc
+   * Set the context of a transaction event.
+   * @deprecated Use either `.setAttribute()`, or set the context on the scope before creating the transaction.
    */
   public setContext(key: string, context: Context | null): void {
     if (context === null) {
@@ -334,6 +335,7 @@ export class Transaction extends SpanClass implements TransactionInterface {
       // TODO: Pass spans serialized via `spanToJSON()` here instead in v8.
       spans: finishedSpans,
       start_timestamp: this.startTimestamp,
+      // eslint-disable-next-line deprecation/deprecation
       tags: this.tags,
       timestamp: this.endTimestamp,
       transaction: this._name,

packages/core/src/utils/prepareEvent.ts

@@ -15,6 +15,7 @@ import { DEFAULT_ENVIRONMENT } from '../constants';
 import { getGlobalEventProcessors, notifyEventProcessors } from '../eventProcessors';
 import { Scope, getGlobalScope } from '../scope';
 import { applyScopeDataToEvent, mergeScopeData } from './applyScopeDataToEvent';
+import { spanToJSON } from './spanUtils';
 
 /**
  * This type makes sure that we get either a CaptureContext, OR an EventHint.
@@ -326,10 +327,14 @@ function normalizeEvent(event: Event | null, depth: number, maxBreadth: number):
   // event.spans[].data may contain circular/dangerous data so we need to normalize it
   if (event.spans) {
     normalized.spans = event.spans.map(span => {
-      // We cannot use the spread operator here because `toJSON` on `span` is non-enumerable
-      if (span.data) {
-        span.data = normalize(span.data, depth, maxBreadth);
+      const data = spanToJSON(span).data;
+
+      if (data) {
+        // This is a bit weird, as we generally have `Span` instances here, but to be safe we do not assume so
+        // eslint-disable-next-line deprecation/deprecation
+        span.data = normalize(data, depth, maxBreadth);
       }
+
       return span;
     });
   }