feat(core): Deprecate spanId on propagationContext

Author: mydea

docs/migration/draft-v9-migration-guide.md

@@ -43,6 +43,8 @@
 - Deprecated `debugIntegration`. To log outgoing events, use [Hook Options](https://docs.sentry.io/platforms/javascript/configuration/options/#hooks) (`beforeSend`, `beforeSendTransaction`, ...).
 - Deprecated `sessionTimingIntegration`. To capture session durations alongside events, use [Context](https://docs.sentry.io/platforms/javascript/enriching-events/context/) (`Sentry.setContext()`).
 - Deprecated `addTracingHeadersToFetchRequest` method - this was only meant for internal use and is not needed anymore.
+- Deprecated `generatePropagationContext()` in favor of using `generateTraceId()` directly.
+- Deprecated `spanId` field on `propagationContext` - this field will be removed in v9, and should neither be read or set anymore.
 
 ## `@sentry/nestjs`
 

packages/browser/src/tracing/browserTracingIntegration.ts

@@ -14,6 +14,7 @@ import {
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
   SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
   TRACING_DEFAULTS,
+  generateTraceId,
   getActiveSpan,
   getClient,
   getCurrentScope,
@@ -28,7 +29,6 @@ import {
 import {
   GLOBAL_OBJ,
   browserPerformanceTimeOrigin,
-  generatePropagationContext,
   getDomElement,
   logger,
   propagationContextFromHeaders,
@@ -452,8 +452,8 @@ export function startBrowserTracingPageLoadSpan(
  * This will only do something if a browser tracing integration has been setup.
  */
 export function startBrowserTracingNavigationSpan(client: Client, spanOptions: StartSpanOptions): Span | undefined {
-  getIsolationScope().setPropagationContext(generatePropagationContext());
-  getCurrentScope().setPropagationContext(generatePropagationContext());
+  getIsolationScope().setPropagationContext({ traceId: generateTraceId() });
+  getCurrentScope().setPropagationContext({ traceId: generateTraceId() });
 
   client.emit('startNavigationSpan', spanOptions);
 

packages/browser/test/tracing/browserTracingIntegration.test.ts

@@ -688,6 +688,7 @@ describe('browserTracingIntegration', () => {
 
       const propCtxAfterEnd = getCurrentScope().getPropagationContext();
       expect(propCtxAfterEnd).toStrictEqual({
+        // eslint-disable-next-line deprecation/deprecation
         spanId: propCtxBeforeEnd.spanId,
         traceId: propCtxBeforeEnd.traceId,
         sampled: true,
@@ -727,6 +728,7 @@ describe('browserTracingIntegration', () => {
 
       const propCtxAfterEnd = getCurrentScope().getPropagationContext();
       expect(propCtxAfterEnd).toStrictEqual({
+        // eslint-disable-next-line deprecation/deprecation
         spanId: propCtxBeforeEnd.spanId,
         traceId: propCtxBeforeEnd.traceId,
         sampled: false,

packages/core/src/currentScopes.ts

@@ -128,6 +128,8 @@ export function getClient<C extends Client>(): C | undefined {
 export function getTraceContextFromScope(scope: Scope): TraceContext {
   const propagationContext = scope.getPropagationContext();
 
+  // TODO(v9): Use generateSpanId() instead of spanId
+  // eslint-disable-next-line deprecation/deprecation
   const { traceId, spanId, parentSpanId } = propagationContext;
 
   const traceContext: TraceContext = dropUndefinedKeys({

packages/core/src/scope.ts

@@ -26,7 +26,7 @@ import { updateSession } from './session';
 import { isPlainObject } from './utils-hoist/is';
 import { logger } from './utils-hoist/logger';
 import { uuid4 } from './utils-hoist/misc';
-import { generatePropagationContext } from './utils-hoist/propagationContext';
+import { generateSpanId, generateTraceId } from './utils-hoist/propagationContext';
 import { dateTimestampInSeconds } from './utils-hoist/time';
 import { merge } from './utils/merge';
 import { _getSpanForScope, _setSpanForScope } from './utils/spanOnScope';
@@ -115,7 +115,10 @@ class ScopeClass implements ScopeInterface {
     this._extra = {};
     this._contexts = {};
     this._sdkProcessingMetadata = {};
-    this._propagationContext = generatePropagationContext();
+    this._propagationContext = {
+      traceId: generateTraceId(),
+      spanId: generateSpanId(),
+    };
   }
 
   /**
@@ -398,7 +401,7 @@ class ScopeClass implements ScopeInterface {
     this._session = undefined;
     _setSpanForScope(this, undefined);
     this._attachments = [];
-    this._propagationContext = generatePropagationContext();
+    this.setPropagationContext({ traceId: generateTraceId() });
 
     this._notifyScopeListeners();
     return this;
@@ -491,8 +494,14 @@ class ScopeClass implements ScopeInterface {
   /**
    * @inheritDoc
    */
-  public setPropagationContext(context: PropagationContext): this {
-    this._propagationContext = context;
+  public setPropagationContext(
+    context: Omit<PropagationContext, 'spanId'> & Partial<Pick<PropagationContext, 'spanId'>>,
+  ): this {
+    this._propagationContext = {
+      // eslint-disable-next-line deprecation/deprecation
+      spanId: generateSpanId(),
+      ...context,
+    };
     return this;
   }
 

packages/core/src/tracing/trace.ts

@@ -10,7 +10,7 @@ import { getAsyncContextStrategy } from '../asyncContext';
 import { DEBUG_BUILD } from '../debug-build';
 import { SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE, SEMANTIC_ATTRIBUTE_SENTRY_SOURCE } from '../semanticAttributes';
 import { logger } from '../utils-hoist/logger';
-import { generatePropagationContext } from '../utils-hoist/propagationContext';
+import { generateTraceId } from '../utils-hoist/propagationContext';
 import { propagationContextFromHeaders } from '../utils-hoist/tracing';
 import { handleCallbackErrors } from '../utils/handleCallbackErrors';
 import { hasTracingEnabled } from '../utils/hasTracingEnabled';
@@ -260,7 +260,7 @@ export function suppressTracing<T>(callback: () => T): T {
  */
 export function startNewTrace<T>(callback: () => T): T {
   return withScope(scope => {
-    scope.setPropagationContext(generatePropagationContext());
+    scope.setPropagationContext({ traceId: generateTraceId() });
     DEBUG_BUILD && logger.info(`Starting a new trace with id ${scope.getPropagationContext().traceId}`);
     return withActiveSpan(null, callback);
   });

packages/core/src/utils-hoist/index.ts

@@ -166,7 +166,12 @@ export { makeFifoCache } from './cache';
 export { eventFromMessage, eventFromUnknownInput, exceptionFromError, parseStackFrames } from './eventbuilder';
 export { callFrameToStackFrame, watchdogTimer } from './anr';
 export { LRUMap } from './lru';
-export { generatePropagationContext } from './propagationContext';
+export {
+  // eslint-disable-next-line deprecation/deprecation
+  generatePropagationContext,
+  generateTraceId,
+  generateSpanId,
+} from './propagationContext';
 export { vercelWaitUntil } from './vercelWaitUntil';
 export { SDK_VERSION } from './version';
 export { getDebugImagesForResources, getFilenameToDebugIdMap } from './debug-ids';

packages/core/src/utils-hoist/propagationContext.ts

@@ -2,11 +2,27 @@ import type { PropagationContext } from '@sentry/types';
 import { uuid4 } from './misc';
 
 /**
- * Returns a new minimal propagation context
+ * Returns a new minimal propagation context.
+ *
+ * @deprecated Use `generateTraceId` and `generateSpanId` instead.
  */
 export function generatePropagationContext(): PropagationContext {
   return {
-    traceId: uuid4(),
-    spanId: uuid4().substring(16),
+    traceId: generateTraceId(),
+    spanId: generateSpanId(),
   };
 }
+
+/**
+ * Generate a random, valid trace ID.
+ */
+export function generateTraceId(): string {
+  return uuid4();
+}
+
+/**
+ * Generate a random, valid span ID.
+ */
+export function generateSpanId(): string {
+  return uuid4().substring(16);
+}

packages/core/src/utils-hoist/tracing.ts

@@ -2,7 +2,7 @@ import type { PropagationContext, TraceparentData } from '@sentry/types';
 
 import { baggageHeaderToDynamicSamplingContext } from './baggage';
 import { uuid4 } from './misc';
-import { generatePropagationContext } from './propagationContext';
+import { generateSpanId, generateTraceId } from './propagationContext';
 
 // eslint-disable-next-line @sentry-internal/sdk/no-regexp-constructor -- RegExp is used for readability here
 export const TRACEPARENT_REGEXP = new RegExp(
@@ -56,12 +56,12 @@ export function propagationContextFromHeaders(
   const dynamicSamplingContext = baggageHeaderToDynamicSamplingContext(baggage);
 
   if (!traceparentData || !traceparentData.traceId) {
-    return generatePropagationContext();
+    return { traceId: generateTraceId(), spanId: generateSpanId() };
   }
 
   const { traceId, parentSpanId, parentSampled } = traceparentData;
 
-  const virtualSpanId = uuid4().substring(16);
+  const virtualSpanId = generateSpanId();
 
   return {
     traceId,

packages/core/src/utils/traceData.ts

@@ -81,6 +81,8 @@ export function isValidBaggageString(baggage?: string): boolean {
  * Get a sentry-trace header value for the given scope.
  */
 function scopeToTraceHeader(scope: Scope): string {
+  // TODO(v9): Use generateSpanId() instead of spanId
+  // eslint-disable-next-line deprecation/deprecation
   const { traceId, sampled, spanId } = scope.getPropagationContext();
   return generateSentryTraceHeader(traceId, spanId, sampled);
 }

packages/core/test/utils-hoist/proagationContext.test.ts

@@ -2,6 +2,7 @@ import { generatePropagationContext } from '../../src/utils-hoist/propagationCon
 
 describe('generatePropagationContext', () => {
   it('generates a new minimal propagation context', () => {
+    // eslint-disable-next-line deprecation/deprecation
     expect(generatePropagationContext()).toEqual({
       traceId: expect.stringMatching(/^[0-9a-f]{32}$/),
       spanId: expect.stringMatching(/^[0-9a-f]{16}$/),

packages/node/src/integrations/anr/worker.ts

@@ -121,6 +121,8 @@ function applyScopeToEvent(event: Event, scope: ScopeData): void {
   applyScopeDataToEvent(event, scope);
 
   if (!event.contexts?.trace) {
+    // TODO(v9): Use generateSpanId() instead of spanId
+    // eslint-disable-next-line deprecation/deprecation
     const { traceId, spanId, parentSpanId } = scope.propagationContext;
     event.contexts = {
       trace: {

packages/opentelemetry/src/propagator.ts

@@ -220,6 +220,8 @@ export function getInjectionData(context: Context): {
   return {
     dynamicSamplingContext,
     traceId: propagationContext.traceId,
+    // TODO(v9): Use generateSpanId() instead
+    // eslint-disable-next-line deprecation/deprecation
     spanId: propagationContext.spanId,
     sampled: propagationContext.sampled,
   };

packages/types/src/scope.ts

@@ -226,7 +226,9 @@ export interface Scope {
   /**
    * Add propagation context to the scope, used for distributed tracing
    */
-  setPropagationContext(context: PropagationContext): this;
+  setPropagationContext(
+    context: Omit<PropagationContext, 'spanId'> & Partial<Pick<PropagationContext, 'spanId'>>,
+  ): this;
 
   /**
    * Get propagation context from the scope, used for distributed tracing

packages/types/src/tracing.ts

@@ -20,6 +20,8 @@ export interface PropagationContext {
    * particular execution context when performance monitoring is disabled.
    *
    * The ID of a current span (if one exists) should have precedence over this value when propagating trace data.
+   *
+   * @deprecated This value will not be used anymore in the future, and should not be set or read anymore.
    */
   spanId: string;
   /**

packages/utils/src/index.ts

@@ -517,6 +517,7 @@ export const watchdogTimer = watchdogTimer_imported;
 export const LRUMap = LRUMap_imported;
 
 /** @deprecated Import from `@sentry/core` instead. */
+// eslint-disable-next-line deprecation/deprecation
 export const generatePropagationContext = generatePropagationContext_imported;
 
 /** @deprecated Import from `@sentry/core` instead. */