feat(core): Deprecate Transaction.getDynamicSamplingContext in favour of getDynamicSamplingContextFromSpan

Author: Lms24

MIGRATION.md

@@ -93,6 +93,7 @@ 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.
+* `span.getDynamicSamplingContext`: Use `getDynamicSamplingContextFromSpan` utility function instead.
 * `transaction.setMetadata()`: Use attributes instead, or set data on the scope.
 * `transaction.metadata`: Use attributes instead, or set data on the scope.
 

dev-packages/rollup-utils/plugins/bundlePlugins.mjs

@@ -135,6 +135,9 @@ export function makeTerserPlugin() {
           // These are used by instrument.ts in utils for identifying HTML elements & events
           '_sentryCaptured',
           '_sentryId',
+          // For v7 backwards-compatibility we need to access txn._frozenDynamicSamplingContext
+          // TODO (v8): Remove this reserved word
+          '_frozenDynamicSamplingContext',
         ],
       },
     },

packages/astro/src/server/meta.ts

@@ -1,4 +1,5 @@
 import { getDynamicSamplingContextFromClient, spanToTraceHeader } from '@sentry/core';
+import { getDynamicSamplingContextFromSpan } from '@sentry/core/src/tracing/dynamicSamplingContext';
 import type { Client, Scope, Span } from '@sentry/types';
 import {
   TRACEPARENT_REGEXP,
@@ -33,7 +34,7 @@ export function getTracingMetaTags(
   const sentryTrace = span ? spanToTraceHeader(span) : generateSentryTraceHeader(traceId, undefined, sampled);
 
   const dynamicSamplingContext = transaction
-    ? transaction.getDynamicSamplingContext()
+    ? getDynamicSamplingContextFromSpan(transaction)
     : dsc
       ? dsc
       : client

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

@@ -21,7 +21,11 @@ import { getClient } from './exports';
 import { MetricsAggregator } from './metrics/aggregator';
 import type { Scope } from './scope';
 import { SessionFlusher } from './sessionflusher';
-import { addTracingExtensions, getDynamicSamplingContextFromClient } from './tracing';
+import {
+  addTracingExtensions,
+  getDynamicSamplingContextFromClient,
+  getDynamicSamplingContextFromSpan,
+} from './tracing';
 import { spanToTraceContext } from './utils/spanUtils';
 
 export interface ServerRuntimeClientOptions extends ClientOptions<BaseTransportOptions> {
@@ -257,7 +261,7 @@ export class ServerRuntimeClient<
 
     const span = scope.getSpan();
     if (span) {
-      const samplingContext = span.transaction ? span.transaction.getDynamicSamplingContext() : undefined;
+      const samplingContext = span.transaction ? getDynamicSamplingContextFromSpan(span) : undefined;
       return [samplingContext, spanToTraceContext(span)];
     }
 

packages/core/src/tracing/dynamicSamplingContext.ts

@@ -1,17 +1,19 @@
-import type { Client, DynamicSamplingContext, Scope } from '@sentry/types';
+import type { Client, DynamicSamplingContext, Scope, Span } from '@sentry/types';
 import { dropUndefinedKeys } from '@sentry/utils';
 
 import { DEFAULT_ENVIRONMENT } from '../constants';
+import { getClient, getCurrentScope } from '../exports';
 
 /**
  * Creates a dynamic sampling context from a client.
  *
- * Dispatchs the `createDsc` lifecycle hook as a side effect.
+ * Dispatches the `createDsc` lifecycle hook as a side effect.
  */
 export function getDynamicSamplingContextFromClient(
   trace_id: string,
   client: Client,
   scope?: Scope,
+  emitHook: boolean = true,
 ): DynamicSamplingContext {
   const options = client.getOptions();
 
@@ -26,6 +28,64 @@ export function getDynamicSamplingContextFromClient(
     trace_id,
   }) as DynamicSamplingContext;
 
+  if (emitHook) {
+    client.emit && client.emit('createDsc', dsc);
+  }
+
+  return dsc;
+}
+
+/**
+ * A Span with a frozen dynamic sampling context.
+ */
+type TransactionWithV7FrozenDsc = Span & { _frozenDynamicSamplingContext?: DynamicSamplingContext };
+
+/**
+ * Creates a dynamic sampling context from a span (and client and scope)
+ *
+ * @param span the span from which a few values like the root span name and sample rate are extracted.
+ *
+ * @returns a dynamic sampling context
+ */
+export function getDynamicSamplingContextFromSpan(span: Span): Readonly<Partial<DynamicSamplingContext>> {
+  // TODO (v8): Remove v7FrozenDsc as a Transaction will no longer have _frozenDynamicSamplingContext
+  // For now we need to avoid breaking users who directly created a txn with a DSC, where this field is still set.
+  // @see Transaction class constructor
+  const v7FrozenDsc = (span as TransactionWithV7FrozenDsc)._frozenDynamicSamplingContext;
+  if (v7FrozenDsc) {
+    return v7FrozenDsc;
+  }
+
+  const client = getClient();
+  if (!client) {
+    return {};
+  }
+
+  // passing emit=false here to only emit later once the DSC is actually populated
+  const dsc = getDynamicSamplingContextFromClient(span.traceId, client, getCurrentScope(), false);
+  const txn = span.transaction;
+  if (!txn) {
+    return dsc;
+  }
+
+  const maybeSampleRate = txn.metadata.sampleRate;
+  if (maybeSampleRate !== undefined) {
+    dsc.sample_rate = `${maybeSampleRate}`;
+  }
+
+  // We don't want to have a transaction name in the DSC if the source is "url" because URLs might contain PII
+  const source = txn.metadata.source;
+  if (source && source !== 'url') {
+    dsc.transaction = txn.name;
+  }
+
+  // TODO: Switch to `spanIsSampled` once we have it
+  // eslint-disable-next-line deprecation/deprecation
+  if (txn.sampled !== undefined) {
+    // eslint-disable-next-line deprecation/deprecation
+    dsc.sampled = String(txn.sampled);
+  }
+
   client.emit && client.emit('createDsc', dsc);
 
   return dsc;

packages/core/src/tracing/index.ts

@@ -19,5 +19,5 @@ export {
   startSpanManual,
   continueTrace,
 } from './trace';
-export { getDynamicSamplingContextFromClient } from './dynamicSamplingContext';
+export { getDynamicSamplingContextFromClient, getDynamicSamplingContextFromSpan } from './dynamicSamplingContext';
 export { setMeasurement } from './measurement';

packages/core/src/tracing/transaction.ts

@@ -17,7 +17,7 @@ import type { Hub } from '../hub';
 import { getCurrentHub } from '../hub';
 import { SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE, SEMANTIC_ATTRIBUTE_SENTRY_SOURCE } from '../semanticAttributes';
 import { spanTimeInputToSeconds, spanToTraceContext } from '../utils/spanUtils';
-import { getDynamicSamplingContextFromClient } from './dynamicSamplingContext';
+import { getDynamicSamplingContextFromSpan } from './dynamicSamplingContext';
 import { Span as SpanClass, SpanRecorder } from './span';
 
 /** JSDoc */
@@ -227,43 +227,11 @@ export class Transaction extends SpanClass implements TransactionInterface {
    * @inheritdoc
    *
    * @experimental
+   *
+   * @deprecated Use top-level `getDynamicSamplingContextFromSpan` instead.
    */
   public getDynamicSamplingContext(): Readonly<Partial<DynamicSamplingContext>> {
-    if (this._frozenDynamicSamplingContext) {
-      return this._frozenDynamicSamplingContext;
-    }
-
-    const hub = this._hub || getCurrentHub();
-    const client = hub.getClient();
-
-    if (!client) return {};
-
-    const { _traceId: traceId, _sampled: sampled } = this;
-
-    const scope = hub.getScope();
-    const dsc = getDynamicSamplingContextFromClient(traceId, client, scope);
-
-    // eslint-disable-next-line deprecation/deprecation
-    const maybeSampleRate = this.metadata.sampleRate;
-    if (maybeSampleRate !== undefined) {
-      dsc.sample_rate = `${maybeSampleRate}`;
-    }
-
-    // We don't want to have a transaction name in the DSC if the source is "url" because URLs might contain PII
-    // eslint-disable-next-line deprecation/deprecation
-    const source = this.metadata.source;
-    if (source && source !== 'url') {
-      dsc.transaction = this._name;
-    }
-
-    if (sampled !== undefined) {
-      dsc.sampled = String(sampled);
-    }
-
-    // Uncomment if we want to make DSC immutable
-    // this._frozenDynamicSamplingContext = dsc;
-
-    return dsc;
+    return getDynamicSamplingContextFromSpan(this);
   }
 
   /**
@@ -340,7 +308,7 @@ export class Transaction extends SpanClass implements TransactionInterface {
       type: 'transaction',
       sdkProcessingMetadata: {
         ...metadata,
-        dynamicSamplingContext: this.getDynamicSamplingContext(),
+        dynamicSamplingContext: getDynamicSamplingContextFromSpan(this),
       },
       ...(source && {
         transaction_info: {

packages/core/src/utils/applyScopeDataToEvent.ts

@@ -1,5 +1,6 @@
 import type { Breadcrumb, Event, PropagationContext, ScopeData, Span } from '@sentry/types';
 import { arrayify } from '@sentry/utils';
+import { getDynamicSamplingContextFromSpan } from '../tracing/dynamicSamplingContext';
 import { spanToJSON, spanToTraceContext } from './spanUtils';
 
 /**
@@ -176,7 +177,7 @@ function applySpanToEvent(event: Event, span: Span): void {
   const transaction = span.transaction;
   if (transaction) {
     event.sdkProcessingMetadata = {
-      dynamicSamplingContext: transaction.getDynamicSamplingContext(),
+      dynamicSamplingContext: getDynamicSamplingContextFromSpan(span),
       ...event.sdkProcessingMetadata,
     };
     const transactionName = spanToJSON(transaction).description;

packages/nextjs/src/common/wrapAppGetInitialPropsWithSentry.ts

@@ -1,4 +1,10 @@
-import { addTracingExtensions, getClient, getCurrentScope, spanToTraceHeader } from '@sentry/core';
+import {
+  addTracingExtensions,
+  getClient,
+  getCurrentScope,
+  getDynamicSamplingContextFromSpan,
+  spanToTraceHeader,
+} from '@sentry/core';
 import { dynamicSamplingContextToSentryBaggageHeader } from '@sentry/utils';
 import type App from 'next/app';
 
@@ -66,7 +72,7 @@ export function wrapAppGetInitialPropsWithSentry(origAppGetInitialProps: AppGetI
         if (requestTransaction) {
           appGetInitialProps.pageProps._sentryTraceData = spanToTraceHeader(requestTransaction);
 
-          const dynamicSamplingContext = requestTransaction.getDynamicSamplingContext();
+          const dynamicSamplingContext = getDynamicSamplingContextFromSpan(requestTransaction);
           appGetInitialProps.pageProps._sentryBaggage =
             dynamicSamplingContextToSentryBaggageHeader(dynamicSamplingContext);
         }

packages/nextjs/src/common/wrapErrorGetInitialPropsWithSentry.ts

@@ -1,4 +1,10 @@
-import { addTracingExtensions, getClient, getCurrentScope, spanToTraceHeader } from '@sentry/core';
+import {
+  addTracingExtensions,
+  getClient,
+  getCurrentScope,
+  getDynamicSamplingContextFromSpan,
+  spanToTraceHeader,
+} from '@sentry/core';
 import { dynamicSamplingContextToSentryBaggageHeader } from '@sentry/utils';
 import type { NextPageContext } from 'next';
 import type { ErrorProps } from 'next/error';
@@ -58,7 +64,7 @@ export function wrapErrorGetInitialPropsWithSentry(
         if (requestTransaction) {
           errorGetInitialProps._sentryTraceData = spanToTraceHeader(requestTransaction);
 
-          const dynamicSamplingContext = requestTransaction.getDynamicSamplingContext();
+          const dynamicSamplingContext = getDynamicSamplingContextFromSpan(requestTransaction);
           errorGetInitialProps._sentryBaggage = dynamicSamplingContextToSentryBaggageHeader(dynamicSamplingContext);
         }