feat(core): Deprecate transaction metadata in favor of attributes

MIGRATION.md

@@ -89,6 +89,8 @@ In v8, the Span class is heavily reworked. The following properties & methods ar
 * `span.traceId`: Use `span.spanContext().traceId` instead.
 * `span.name`: Use `spanToJSON(span).description` instead.
 * `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.
 
 ## Deprecate `pushScope` & `popScope` in favor of `withScope`
 

dev-packages/browser-integration-tests/suites/public-api/startTransaction/circular_data/subject.js

@@ -2,10 +2,8 @@ const chicken = {};
 const egg = { contains: chicken };
 chicken.lays = egg;
 
-const circularObject = chicken;
-
-const transaction = Sentry.startTransaction({ name: 'circular_object_test_transaction', data: circularObject });
-const span = transaction.startChild({ op: 'circular_object_test_span', data: circularObject });
+const transaction = Sentry.startTransaction({ name: 'circular_object_test_transaction', data: { chicken } });
+const span = transaction.startChild({ op: 'circular_object_test_span', data: { chicken } });
 
 span.end();
 transaction.end();

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

@@ -17,12 +17,12 @@ sentryTest('should be able to handle circular data', async ({ getLocalTestPath,
 
   expect(eventData.contexts).toMatchObject({
     trace: {
-      data: { lays: { contains: '[Circular ~]' } },
+      data: { chicken: { lays: { contains: '[Circular ~]' } } },
     },
   });
 
   expect(eventData?.spans?.[0]).toMatchObject({
-    data: { lays: { contains: '[Circular ~]' } },
+    data: { chicken: { lays: { contains: '[Circular ~]' } } },
     op: 'circular_object_test_span',
   });
 

dev-packages/node-integration-tests/suites/express/sentry-trace/baggage-transaction-name/server.ts

@@ -1,4 +1,5 @@
 import http from 'http';
+import { SEMANTIC_ATTRIBUTE_SENTRY_SOURCE } from '@sentry/core';
 import * as Sentry from '@sentry/node';
 import * as Tracing from '@sentry/tracing';
 import cors from 'cors';
@@ -34,7 +35,7 @@ app.get('/test/express', (_req, res) => {
   if (transaction) {
     // eslint-disable-next-line deprecation/deprecation
     transaction.traceId = '86f39e84263a4de99c326acab3bfe3bd';
-    transaction.setMetadata({ source: 'route' });
+    transaction.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
   }
   const headers = http.get('http://somewhere.not.sentry/').getHeaders();
 

packages/angular-ivy/ng-package.json

@@ -5,9 +5,10 @@
     "entryFile": "src/index.ts",
     "umdModuleIds": {
       "@sentry/browser": "Sentry",
-      "@sentry/utils": "Sentry.util"
+      "@sentry/utils": "Sentry.util",
+      "@sentry/core": "Sentry.core"
     }
   },
-  "allowedNonPeerDependencies": ["@sentry/browser", "@sentry/utils", "@sentry/types", "tslib"],
+  "allowedNonPeerDependencies": ["@sentry/browser", "@sentry/core", "@sentry/utils", "@sentry/types", "tslib"],
   "assets": ["README.md", "LICENSE"]
 }

packages/angular-ivy/package.json

@@ -22,6 +22,7 @@
   },
   "dependencies": {
     "@sentry/browser": "7.92.0",
+    "@sentry/core": "7.92.0",
     "@sentry/types": "7.92.0",
     "@sentry/utils": "7.92.0",
     "tslib": "^2.4.1"

packages/angular/ng-package.json

@@ -5,9 +5,10 @@
     "entryFile": "src/index.ts",
     "umdModuleIds": {
       "@sentry/browser": "Sentry",
-      "@sentry/utils": "Sentry.util"
+      "@sentry/utils": "Sentry.util",
+      "@sentry/core": "Sentry.core"
     }
   },
-  "whitelistedNonPeerDependencies": ["@sentry/browser", "@sentry/utils", "@sentry/types", "tslib"],
+  "whitelistedNonPeerDependencies": ["@sentry/browser", "@sentry/core", "@sentry/utils", "@sentry/types", "tslib"],
   "assets": ["README.md", "LICENSE"]
 }

packages/angular/package.json

@@ -22,6 +22,7 @@
   },
   "dependencies": {
     "@sentry/browser": "7.92.0",
+    "@sentry/core": "7.92.0",
     "@sentry/types": "7.92.0",
     "@sentry/utils": "7.92.0",
     "tslib": "^2.4.1"

packages/angular/src/tracing.ts

@@ -8,6 +8,7 @@ import type { ActivatedRouteSnapshot, Event, RouterState } from '@angular/router
 import { NavigationCancel, NavigationError, Router } from '@angular/router';
 import { NavigationEnd, NavigationStart, ResolveEnd } from '@angular/router';
 import { WINDOW, getCurrentScope } from '@sentry/browser';
+import { SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, spanToJSON } from '@sentry/core';
 import type { Span, Transaction, TransactionContext } from '@sentry/types';
 import { logger, stripUrlQueryAndFragment, timestampInSeconds } from '@sentry/utils';
 import type { Observable } from 'rxjs';
@@ -39,7 +40,9 @@ export function routingInstrumentation(
       name: WINDOW.location.pathname,
       op: 'pageload',
       origin: 'auto.pageload.angular',
-      metadata: { source: 'url' },
+      attributes: {
+        [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'url',
+      },
     });
   }
 }
@@ -80,7 +83,9 @@ export class TraceService implements OnDestroy {
           name: strippedUrl,
           op: 'navigation',
           origin: 'auto.navigation.angular',
-          metadata: { source: 'url' },
+          attributes: {
+            [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'url',
+          },
         });
       }
 
@@ -123,9 +128,10 @@ export class TraceService implements OnDestroy {
       // eslint-disable-next-line deprecation/deprecation
       const transaction = getActiveTransaction();
       // TODO (v8 / #5416): revisit the source condition. Do we want to make the parameterized route the default?
-      if (transaction && transaction.metadata.source === 'url') {
+      const attributes = (transaction && spanToJSON(transaction).data) || {};
+      if (transaction && attributes[SEMANTIC_ATTRIBUTE_SENTRY_SOURCE] === 'url') {
         transaction.updateName(route);
-        transaction.setMetadata({ source: 'route' });
+        transaction.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
       }
     }),
   );

packages/angular/test/tracing.test.ts

@@ -1,5 +1,6 @@
 import { Component } from '@angular/core';
 import type { ActivatedRouteSnapshot, CanActivate, RouterStateSnapshot } from '@angular/router';
+import { SEMANTIC_ATTRIBUTE_SENTRY_SOURCE } from '@sentry/core';
 
 import { TraceClassDecorator, TraceDirective, TraceMethodDecorator, instrumentAngularRouting } from '../src';
 import { getParameterizedRouteFromSnapshot } from '../src/tracing';
@@ -11,7 +12,14 @@ const defaultStartTransaction = (ctx: any) => {
   transaction = {
     ...ctx,
     updateName: jest.fn(name => (transaction.name = name)),
-    setMetadata: jest.fn(),
+    setAttribute: jest.fn(),
+    toJSON: () => ({
+      data: {
+        [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'custom',
+        ...ctx.data,
+        ...ctx.attributes,
+      },
+    }),
   };
 
   return transaction;
@@ -45,7 +53,7 @@ describe('Angular Tracing', () => {
         name: '/',
         op: 'pageload',
         origin: 'auto.pageload.angular',
-        metadata: { source: 'url' },
+        attributes: { [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'url' },
       });
     });
   });
@@ -107,11 +115,15 @@ describe('Angular Tracing', () => {
       const customStartTransaction = jest.fn((ctx: any) => {
         transaction = {
           ...ctx,
-          metadata: {
-            ...ctx.metadata,
-            source: 'custom',
-          },
+          toJSON: () => ({
+            data: {
+              ...ctx.data,
+              [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'custom',
+            },
+          }),
+          metadata: ctx.metadata,
           updateName: jest.fn(name => (transaction.name = name)),
+          setAttribute: jest.fn(),
         };
 
         return transaction;
@@ -135,12 +147,12 @@ describe('Angular Tracing', () => {
         name: url,
         op: 'pageload',
         origin: 'auto.pageload.angular',
-        metadata: { source: 'url' },
+        attributes: { [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'url' },
       });
 
       expect(transaction.updateName).toHaveBeenCalledTimes(0);
       expect(transaction.name).toEqual(url);
-      expect(transaction.metadata.source).toBe('custom');
+      expect(transaction.toJSON().data).toEqual({ [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'custom' });
 
       env.destroy();
     });
@@ -326,10 +338,10 @@ describe('Angular Tracing', () => {
           name: url,
           op: 'navigation',
           origin: 'auto.navigation.angular',
-          metadata: { source: 'url' },
+          attributes: { [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'url' },
         });
         expect(transaction.updateName).toHaveBeenCalledWith(result);
-        expect(transaction.setMetadata).toHaveBeenCalledWith({ source: 'route' });
+        expect(transaction.setAttribute).toHaveBeenCalledWith(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
 
         env.destroy();
       });

packages/astro/src/server/middleware.ts

@@ -1,3 +1,4 @@
+import { SEMANTIC_ATTRIBUTE_SENTRY_SOURCE } from '@sentry/core';
 import {
   captureException,
   continueTrace,
@@ -111,6 +112,7 @@ async function instrumentRequest(
 
   try {
     const interpolatedRoute = interpolateRouteFromUrlAndParams(ctx.url.pathname, ctx.params);
+    const source = interpolatedRoute ? 'route' : 'url';
     // storing res in a variable instead of directly returning is necessary to
     // invoke the catch block if next() throws
     const res = await startSpan(
@@ -121,12 +123,13 @@ async function instrumentRequest(
         origin: 'auto.http.astro',
         status: 'ok',
         metadata: {
+          // eslint-disable-next-line deprecation/deprecation
           ...traceCtx?.metadata,
-          source: interpolatedRoute ? 'route' : 'url',
         },
         data: {
           method,
           url: stripUrlQueryAndFragment(ctx.url.href),
+          [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: source,
           ...(ctx.url.search && { 'http.query': ctx.url.search }),
           ...(ctx.url.hash && { 'http.fragment': ctx.url.hash }),
           ...(options.trackHeaders && { headers: allHeaders }),

packages/astro/test/server/middleware.test.ts

@@ -1,3 +1,4 @@
+import { SEMANTIC_ATTRIBUTE_SENTRY_SOURCE } from '@sentry/core';
 import * as SentryNode from '@sentry/node';
 import type { Client } from '@sentry/types';
 import { vi } from 'vitest';
@@ -57,10 +58,9 @@ describe('sentryMiddleware', () => {
         data: {
           method: 'GET',
           url: 'https://mydomain.io/users/123/details',
+          [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'route',
         },
-        metadata: {
-          source: 'route',
-        },
+        metadata: {},
         name: 'GET /users/[id]/details',
         op: 'http.server',
         origin: 'auto.http.astro',
@@ -94,10 +94,9 @@ describe('sentryMiddleware', () => {
         data: {
           method: 'GET',
           url: 'http://localhost:1234/a%xx',
+          [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'url',
         },
-        metadata: {
-          source: 'url',
-        },
+        metadata: {},
         name: 'GET a%xx',
         op: 'http.server',
         origin: 'auto.http.astro',
@@ -159,8 +158,10 @@ describe('sentryMiddleware', () => {
 
     expect(startSpanSpy).toHaveBeenCalledWith(
       expect.objectContaining({
+        data: expect.objectContaining({
+          [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'route',
+        }),
         metadata: {
-          source: 'route',
           dynamicSamplingContext: {
             release: '1.0.0',
           },

packages/bun/src/integrations/bunserver.ts

@@ -1,4 +1,5 @@
 import {
+  SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
   Transaction,
   captureException,
   continueTrace,
@@ -54,6 +55,7 @@ function instrumentBunServeOptions(serveOptions: Parameters<typeof Bun.serve>[0]
         const parsedUrl = parseUrl(request.url);
         const data: Record<string, unknown> = {
           'http.request.method': request.method || 'GET',
+          [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'url',
         };
         if (parsedUrl.search) {
           data['http.query'] = parsedUrl.search;
@@ -72,8 +74,8 @@ function instrumentBunServeOptions(serveOptions: Parameters<typeof Bun.serve>[0]
                 ...ctx,
                 data,
                 metadata: {
+                  // eslint-disable-next-line deprecation/deprecation
                   ...ctx.metadata,
-                  source: 'url',
                   request: {
                     url,
                     method: request.method,

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

@@ -82,6 +82,7 @@ describe('Bun Serve Integration', () => {
       expect(transaction.parentSpanId).toBe(PARENT_SPAN_ID);
       expect(transaction.isRecording()).toBe(true);
 
+      // eslint-disable-next-line deprecation/deprecation
       expect(transaction.metadata?.dynamicSamplingContext).toStrictEqual({ version: '1.0', environment: 'production' });
     });
 

packages/core/src/index.ts

@@ -5,6 +5,7 @@ export type { ServerRuntimeClientOptions } from './server-runtime-client';
 export type { RequestDataIntegrationOptions } from './integrations/requestdata';
 
 export * from './tracing';
+export * from './semanticAttributes';
 export { createEventEnvelope, createSessionEnvelope } from './envelope';
 export {
   addBreadcrumb,

packages/core/src/semanticAttributes.ts

@@ -0,0 +1,11 @@
+/**
+ * Use this attribute to represent the source of a span.
+ * Should be one of: custom, url, route, view, component, task, unknown
+ *
+ */
+export const SEMANTIC_ATTRIBUTE_SENTRY_SOURCE = 'sentry.source';
+
+/**
+ * Use this attribute to represent the sample rate used for a span.
+ */
+export const SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE = 'sentry.sample_rate';

packages/core/src/tracing/sampling.ts

@@ -2,6 +2,7 @@ import type { Options, SamplingContext } from '@sentry/types';
 import { isNaN, logger } from '@sentry/utils';
 
 import { DEBUG_BUILD } from '../debug-build';
+import { SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE } from '../semanticAttributes';
 import { hasTracingEnabled } from '../utils/hasTracingEnabled';
 import { spanToJSON } from '../utils/spanUtils';
 import type { Transaction } from './transaction';
@@ -30,10 +31,8 @@ export function sampleTransaction<T extends Transaction>(
   // if the user has forced a sampling decision by passing a `sampled` value in their transaction context, go with that
   // eslint-disable-next-line deprecation/deprecation
   if (transaction.sampled !== undefined) {
-    transaction.setMetadata({
-      // eslint-disable-next-line deprecation/deprecation
-      sampleRate: Number(transaction.sampled),
-    });
+    // eslint-disable-next-line deprecation/deprecation
+    transaction.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE, Number(transaction.sampled));
     return transaction;
   }
 
@@ -42,22 +41,16 @@ export function sampleTransaction<T extends Transaction>(
   let sampleRate;
   if (typeof options.tracesSampler === 'function') {
     sampleRate = options.tracesSampler(samplingContext);
-    transaction.setMetadata({
-      sampleRate: Number(sampleRate),
-    });
+    transaction.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE, Number(sampleRate));
   } else if (samplingContext.parentSampled !== undefined) {
     sampleRate = samplingContext.parentSampled;
   } else if (typeof options.tracesSampleRate !== 'undefined') {
     sampleRate = options.tracesSampleRate;
-    transaction.setMetadata({
-      sampleRate: Number(sampleRate),
-    });
+    transaction.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE, Number(sampleRate));
   } else {
     // When `enableTracing === true`, we use a sample rate of 100%
     sampleRate = 1;
-    transaction.setMetadata({
-      sampleRate,
-    });
+    transaction.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE, sampleRate);
   }
 
   // Since this is coming from the user (or from a function provided by the user), who knows what we might get. (The