feat(core): Deprecate Span.transaction in favor of getRootSpan (#10134)

Deprecate the `transaction` field on the `Span` interface and
class. Instead, we'll store the span hierarchy in a different format
external to the span class. In node-experimental, we use a WeakMap
referencing the parent span as a data structure which we might need to
generally do in v8. This, however, is a breaking change, so for now we
deprecate the field but use it in the replacement utility function for
v7.

Author: Lms24

MIGRATION.md

@@ -152,6 +152,7 @@ In v8, the Span class is heavily reworked. The following properties & methods ar
 - `span.setTag()`: Use `span.setAttribute()` instead or set tags on the surrounding scope.
 - `span.setData()`: Use `span.setAttribute()` instead.
 - `span.instrumenter` This field was removed and will be replaced internally.
+- `span.transaction`: Use `getRootSpan` utility function instead.
 - `transaction.setContext()`: Set context on the surrounding scope instead.
 
 ## Deprecate `pushScope` & `popScope` in favor of `withScope`

packages/astro/src/server/meta.ts

@@ -1,6 +1,7 @@
 import {
   getDynamicSamplingContextFromClient,
   getDynamicSamplingContextFromSpan,
+  getRootSpan,
   spanToTraceHeader,
 } from '@sentry/core';
 import type { Client, Scope, Span } from '@sentry/types';
@@ -32,12 +33,12 @@ export function getTracingMetaTags(
   client: Client | undefined,
 ): { sentryTrace: string; baggage?: string } {
   const { dsc, sampled, traceId } = scope.getPropagationContext();
-  const transaction = span?.transaction;
+  const rootSpan = span && getRootSpan(span);
 
   const sentryTrace = span ? spanToTraceHeader(span) : generateSentryTraceHeader(traceId, undefined, sampled);
 
-  const dynamicSamplingContext = transaction
-    ? getDynamicSamplingContextFromSpan(transaction)
+  const dynamicSamplingContext = rootSpan
+    ? getDynamicSamplingContextFromSpan(rootSpan)
     : dsc
       ? dsc
       : client

packages/core/src/index.ts

@@ -81,6 +81,7 @@ export {
   spanToJSON,
   spanIsSampled,
 } from './utils/spanUtils';
+export { getRootSpan } from './utils/getRootSpan';
 export { DEFAULT_ENVIRONMENT } from './constants';
 export { ModuleMetadata } from './integrations/metadata';
 export { RequestData } from './integrations/requestdata';

packages/core/src/scope.ts

@@ -334,6 +334,9 @@ export class Scope implements ScopeInterface {
     // Often, this span (if it exists at all) will be a transaction, but it's not guaranteed to be. Regardless, it will
     // have a pointer to the currently-active transaction.
     const span = this._span;
+    // Cannot replace with getRootSpan because getRootSpan returns a span, not a transaction
+    // Also, this method will be removed anyway.
+    // eslint-disable-next-line deprecation/deprecation
     return span && span.transaction;
   }
 

packages/core/src/server-runtime-client.ts

@@ -26,6 +26,7 @@ import {
   getDynamicSamplingContextFromClient,
   getDynamicSamplingContextFromSpan,
 } from './tracing';
+import { getRootSpan } from './utils/getRootSpan';
 import { spanToTraceContext } from './utils/spanUtils';
 
 export interface ServerRuntimeClientOptions extends ClientOptions<BaseTransportOptions> {
@@ -262,7 +263,7 @@ export class ServerRuntimeClient<
     // eslint-disable-next-line deprecation/deprecation
     const span = scope.getSpan();
     if (span) {
-      const samplingContext = span.transaction ? getDynamicSamplingContextFromSpan(span) : undefined;
+      const samplingContext = getRootSpan(span) ? getDynamicSamplingContextFromSpan(span) : undefined;
       return [samplingContext, spanToTraceContext(span)];
     }
 

packages/core/src/tracing/dynamicSamplingContext.ts

@@ -3,6 +3,7 @@ import { dropUndefinedKeys } from '@sentry/utils';
 
 import { DEFAULT_ENVIRONMENT } from '../constants';
 import { getClient, getCurrentScope } from '../exports';
+import { getRootSpan } from '../utils/getRootSpan';
 import { spanIsSampled, spanToJSON } from '../utils/spanUtils';
 
 /**
@@ -54,9 +55,8 @@ export function getDynamicSamplingContextFromSpan(span: Span): Readonly<Partial<
   // passing emit=false here to only emit later once the DSC is actually populated
   const dsc = getDynamicSamplingContextFromClient(spanToJSON(span).trace_id || '', client, getCurrentScope());
 
-  // As long as we use `Transaction`s internally, this should be fine.
-  // TODO: We need to replace this with a `getRootSpan(span)` function though
-  const txn = span.transaction as TransactionWithV7FrozenDsc | undefined;
+  // TODO (v8): Remove v7FrozenDsc as a Transaction will no longer have _frozenDynamicSamplingContext
+  const txn = getRootSpan(span) as TransactionWithV7FrozenDsc | undefined;
   if (!txn) {
     return dsc;
   }

packages/core/src/tracing/span.ts

@@ -16,6 +16,7 @@ import type {
 import { dropUndefinedKeys, logger, timestampInSeconds, uuid4 } from '@sentry/utils';
 
 import { DEBUG_BUILD } from '../debug-build';
+import { getRootSpan } from '../utils/getRootSpan';
 import {
   TRACE_FLAG_NONE,
   TRACE_FLAG_SAMPLED,
@@ -105,6 +106,7 @@ export class Span implements SpanInterface {
 
   /**
    * @inheritDoc
+   * @deprecated Use top level `Sentry.getRootSpan()` instead
    */
   public transaction?: Transaction;
 
@@ -304,12 +306,16 @@ export class Span implements SpanInterface {
       childSpan.spanRecorder.add(childSpan);
     }
 
-    childSpan.transaction = this.transaction;
+    const rootSpan = getRootSpan(this);
+    // TODO: still set span.transaction here until we have a more permanent solution
+    // Probably similarly to the weakmap we hold in node-experimental
+    // eslint-disable-next-line deprecation/deprecation
+    childSpan.transaction = rootSpan as Transaction;
 
-    if (DEBUG_BUILD && childSpan.transaction) {
+    if (DEBUG_BUILD && rootSpan) {
       const opStr = (spanContext && spanContext.op) || '< unknown op >';
       const nameStr = spanToJSON(childSpan).description || '< unknown name >';
-      const idStr = childSpan.transaction.spanContext().spanId;
+      const idStr = rootSpan.spanContext().spanId;
 
       const logMessage = `[Tracing] Starting '${opStr}' span on transaction '${nameStr}' (${idStr}).`;
       logger.log(logMessage);
@@ -416,11 +422,12 @@ export class Span implements SpanInterface {
 
   /** @inheritdoc */
   public end(endTimestamp?: SpanTimeInput): void {
+    const rootSpan = getRootSpan(this);
     if (
       DEBUG_BUILD &&
       // Don't call this for transactions
-      this.transaction &&
-      this.transaction.spanContext().spanId !== this._spanId
+      rootSpan &&
+      rootSpan.spanContext().spanId !== this._spanId
     ) {
       const logMessage = this._logMessage;
       if (logMessage) {

packages/core/src/tracing/transaction.ts

@@ -66,6 +66,8 @@ export class Transaction extends SpanClass implements TransactionInterface {
     this._trimEnd = transactionContext.trimEnd;
 
     // this is because transactions are also spans, and spans have a transaction pointer
+    // TODO (v8): Replace this with another way to set the root span
+    // eslint-disable-next-line deprecation/deprecation
     this.transaction = this;
 
     // If Dynamic Sampling Context is provided during the creation of the transaction, we freeze it as it usually means

packages/core/src/utils/applyScopeDataToEvent.ts

@@ -1,6 +1,7 @@
 import type { Breadcrumb, Event, PropagationContext, ScopeData, Span } from '@sentry/types';
 import { arrayify } from '@sentry/utils';
 import { getDynamicSamplingContextFromSpan } from '../tracing/dynamicSamplingContext';
+import { getRootSpan } from './getRootSpan';
 import { spanToJSON, spanToTraceContext } from './spanUtils';
 
 /**
@@ -174,13 +175,13 @@ function applySdkMetadataToEvent(
 
 function applySpanToEvent(event: Event, span: Span): void {
   event.contexts = { trace: spanToTraceContext(span), ...event.contexts };
-  const transaction = span.transaction;
-  if (transaction) {
+  const rootSpan = getRootSpan(span);
+  if (rootSpan) {
     event.sdkProcessingMetadata = {
       dynamicSamplingContext: getDynamicSamplingContextFromSpan(span),
       ...event.sdkProcessingMetadata,
     };
-    const transactionName = spanToJSON(transaction).description;
+    const transactionName = spanToJSON(rootSpan).description;
     if (transactionName) {
       event.tags = { transaction: transactionName, ...event.tags };
     }

packages/core/src/utils/getRootSpan.ts

@@ -0,0 +1,15 @@
+import type { Span } from '@sentry/types';
+
+/**
+ * Returns the root span of a given span.
+ *
+ * As long as we use `Transaction`s internally, the returned root span
+ * will be a `Transaction` but be aware that this might change in the future.
+ *
+ * If the given span has no root span or transaction, `undefined` is returned.
+ */
+export function getRootSpan(span: Span): Span | undefined {
+  // TODO (v8): Remove this check and just return span
+  // eslint-disable-next-line deprecation/deprecation
+  return span.transaction;
+}