feat(core): Add span.spanContext() (#10037)

This will replace `spanId`, `traceId` and `sampled` lookups.
Because the bitwise format of OTEL is a bit weird IMHO to check if a
span is sampled, I also added a utility `spanIsSampled(span)` method to
abstract this away.

Author: mydea

MIGRATION.md

@@ -69,6 +69,8 @@ In v8, the Span class is heavily reworked. The following properties & methods ar
 * `span.toTraceparent()`: use `spanToTraceHeader(span)` util instead.
 * `span.getTraceContext()`: Use `spanToTraceContext(span)` utility function instead.
 * `span.sampled`: Use `span.isRecording()` instead.
+* `span.spanId`: Use `span.spanContext().spanId` instead.
+* `span.traceId`: Use `span.spanContext().traceId` instead.
 
 ## Deprecate `pushScope` & `popScope` in favor of `withScope`
 

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

@@ -39,5 +39,6 @@ sentryTest('should report finished spans as children of the root transaction', a
 
   const span_5 = transaction.spans?.[2];
   expect(span_5?.op).toBe('span_5');
+  // eslint-disable-next-line deprecation/deprecation
   expect(span_5?.parentSpanId).toEqual(span_3?.spanId);
 });

dev-packages/node-integration-tests/suites/express/sentry-trace/baggage-header-out/server.ts

@@ -28,6 +28,7 @@ app.use(cors());
 app.get('/test/express', (_req, res) => {
   const transaction = Sentry.getCurrentHub().getScope().getTransaction();
   if (transaction) {
+    // eslint-disable-next-line deprecation/deprecation
     transaction.traceId = '86f39e84263a4de99c326acab3bfe3bd';
   }
   const headers = http.get('http://somewhere.not.sentry/').getHeaders();

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

@@ -31,6 +31,7 @@ app.use(cors());
 app.get('/test/express', (_req, res) => {
   const transaction = Sentry.getCurrentHub().getScope().getTransaction();
   if (transaction) {
+    // eslint-disable-next-line deprecation/deprecation
     transaction.traceId = '86f39e84263a4de99c326acab3bfe3bd';
     transaction.setMetadata({ source: 'route' });
   }

packages/astro/test/server/meta.test.ts

@@ -3,10 +3,17 @@ import { vi } from 'vitest';
 
 import { getTracingMetaTags, isValidBaggageString } from '../../src/server/meta';
 
+const TRACE_FLAG_SAMPLED = 0x1;
+
 const mockedSpan = {
   isRecording: () => true,
-  traceId: '12345678901234567890123456789012',
-  spanId: '1234567890123456',
+  spanContext: () => {
+    return {
+      traceId: '12345678901234567890123456789012',
+      spanId: '1234567890123456',
+      traceFlags: TRACE_FLAG_SAMPLED,
+    };
+  },
   transaction: {
     getDynamicSamplingContext: () => ({
       environment: 'production',
@@ -71,8 +78,13 @@ describe('getTracingMetaTags', () => {
       // @ts-expect-error - only passing a partial span object
       {
         isRecording: () => true,
-        traceId: '12345678901234567890123456789012',
-        spanId: '1234567890123456',
+        spanContext: () => {
+          return {
+            traceId: '12345678901234567890123456789012',
+            spanId: '1234567890123456',
+            traceFlags: TRACE_FLAG_SAMPLED,
+          };
+        },
         transaction: undefined,
       },
       mockedScope,
@@ -84,7 +96,7 @@ describe('getTracingMetaTags', () => {
     });
   });
 
-  it('returns only the `sentry-trace` tag if no DSC is available', () => {
+  it('returns only the `sentry-trace` tag if no DSC is available without a client', () => {
     vi.spyOn(SentryCore, 'getDynamicSamplingContextFromClient').mockReturnValueOnce({
       trace_id: '',
       public_key: undefined,
@@ -94,8 +106,13 @@ describe('getTracingMetaTags', () => {
       // @ts-expect-error - only passing a partial span object
       {
         isRecording: () => true,
-        traceId: '12345678901234567890123456789012',
-        spanId: '1234567890123456',
+        spanContext: () => {
+          return {
+            traceId: '12345678901234567890123456789012',
+            spanId: '1234567890123456',
+            traceFlags: TRACE_FLAG_SAMPLED,
+          };
+        },
         transaction: undefined,
       },
       mockedScope,

packages/browser/test/unit/profiling/hubextensions.test.ts

@@ -10,6 +10,9 @@ import { JSDOM } from 'jsdom';
 
 import { onProfilingStartRouteTransaction } from '../../../src';
 
+// eslint-disable-next-line no-bitwise
+const TraceFlagSampled = 0x1 << 0;
+
 // @ts-expect-error store a reference so we can reset it later
 const globalDocument = global.document;
 // @ts-expect-error store a reference so we can reset it later
@@ -67,9 +70,17 @@ describe('BrowserProfilingIntegration', () => {
     // @ts-expect-error force api to be undefined
     global.window.Profiler = undefined;
     // set sampled to true so that profiling does not early return
-    const mockTransaction = { isRecording: () => true } as Transaction;
+    const mockTransaction = {
+      isRecording: () => true,
+      spanContext: () => ({
+        traceId: '12345678901234567890123456789012',
+        spanId: '1234567890123456',
+        traceFlags: TraceFlagSampled,
+      }),
+    } as Transaction;
     expect(() => onProfilingStartRouteTransaction(mockTransaction)).not.toThrow();
   });
+
   it('does not throw if constructor throws', () => {
     const spy = jest.fn();
 
@@ -80,8 +91,15 @@ describe('BrowserProfilingIntegration', () => {
       }
     }
 
-    // set isRecording to true so that profiling does not early return
-    const mockTransaction = { isRecording: () => true } as Transaction;
+    // set sampled to true so that profiling does not early return
+    const mockTransaction = {
+      isRecording: () => true,
+      spanContext: () => ({
+        traceId: '12345678901234567890123456789012',
+        spanId: '1234567890123456',
+        traceFlags: TraceFlagSampled,
+      }),
+    } as Transaction;
 
     // @ts-expect-error override with our own constructor
     global.window.Profiler = Profiler;

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

@@ -78,7 +78,7 @@ describe('Bun Serve Integration', () => {
     const SENTRY_BAGGAGE_HEADER = 'sentry-version=1.0,sentry-environment=production';
 
     client.on('finishTransaction', transaction => {
-      expect(transaction.traceId).toBe(TRACE_ID);
+      expect(transaction.spanContext().traceId).toBe(TRACE_ID);
       expect(transaction.parentSpanId).toBe(PARENT_SPAN_ID);
       expect(transaction.isRecording()).toBe(true);
 

packages/core/src/index.ts

@@ -78,6 +78,7 @@ export { handleCallbackErrors } from './utils/handleCallbackErrors';
 export {
   spanToTraceHeader,
   spanToJSON,
+  spanIsSampled,
 } from './utils/spanUtils';
 export { DEFAULT_ENVIRONMENT } from './constants';
 export { ModuleMetadata } from './integrations/metadata';

packages/core/src/tracing/idletransaction.ts

@@ -45,18 +45,18 @@ export class IdleTransactionSpanRecorder extends SpanRecorder {
   public add(span: Span): void {
     // We should make sure we do not push and pop activities for
     // the transaction that this span recorder belongs to.
-    if (span.spanId !== this.transactionSpanId) {
+    if (span.spanContext().spanId !== this.transactionSpanId) {
       // We patch span.end() to pop an activity after setting an endTimestamp.
       // eslint-disable-next-line @typescript-eslint/unbound-method
       const originalEnd = span.end;
       span.end = (...rest: unknown[]) => {
-        this._popActivity(span.spanId);
+        this._popActivity(span.spanContext().spanId);
         return originalEnd.apply(span, rest);
       };
 
       // We should only push new activities if the span does not have an end timestamp.
       if (span.endTimestamp === undefined) {
-        this._pushActivity(span.spanId);
+        this._pushActivity(span.spanContext().spanId);
       }
     }
 
@@ -123,7 +123,7 @@ export class IdleTransaction extends Transaction {
     if (_onScope) {
       // We set the transaction here on the scope so error events pick up the trace
       // context and attach it to the error.
-      DEBUG_BUILD && logger.log(`Setting idle transaction on scope. Span ID: ${this.spanId}`);
+      DEBUG_BUILD && logger.log(`Setting idle transaction on scope. Span ID: ${this.spanContext().spanId}`);
       _idleHub.getScope().setSpan(this);
     }
 
@@ -158,7 +158,7 @@ export class IdleTransaction extends Transaction {
 
       this.spanRecorder.spans = this.spanRecorder.spans.filter((span: Span) => {
         // If we are dealing with the transaction itself, we just return it
-        if (span.spanId === this.spanId) {
+        if (span.spanContext().spanId === this.spanContext().spanId) {
           return true;
         }
 
@@ -233,7 +233,7 @@ export class IdleTransaction extends Transaction {
         this._popActivity(id);
       };
 
-      this.spanRecorder = new IdleTransactionSpanRecorder(pushActivity, popActivity, this.spanId, maxlen);
+      this.spanRecorder = new IdleTransactionSpanRecorder(pushActivity, popActivity, this.spanContext().spanId, maxlen);
 
       // Start heartbeat so that transactions do not run forever.
       DEBUG_BUILD && logger.log('Starting heartbeat');