feat(core)!: Pass root spans to beforeSendSpan and disallow returning null (#14831)

- [x] Disallows returning null from `beforeSendSpan`
- [x] Passes root spans to `beforeSendSpan`
- [x] Adds entry to migration guide and changelog


closes #14336

Author: chargome

docs/migration/v8-to-v9.md

@@ -68,6 +68,8 @@ Sentry.init({
 });
 ```
 
+- Dropping spans in the `beforeSendSpan` hook is no longer possible.
+- The `beforeSendSpan` hook now receives the root span as well as the child spans.
 - In previous versions, we determined if tracing is enabled (for Tracing Without Performance) by checking if either `tracesSampleRate` or `traceSampler` are _defined_ at all, in `Sentry.init()`. This means that e.g. the following config would lead to tracing without performance (=tracing being enabled, even if no spans would be started):
 
 ```js
@@ -243,6 +245,10 @@ The following outlines deprecations that were introduced in version 8 of the SDK
 ## General
 
 - **Returning `null` from `beforeSendSpan` span is deprecated.**
+
+  Returning `null` from `beforeSendSpan` will now result in a warning being logged.
+  In v9, dropping spans is not possible anymore within this hook.
+
 - **Passing `undefined` to `tracesSampleRate` / `tracesSampler` / `enableTracing` will be handled differently in v9**
 
   In v8, a setup like the following:

packages/core/src/client.ts

@@ -52,9 +52,11 @@ import { logger } from './utils-hoist/logger';
 import { checkOrSetAlreadyCaught, uuid4 } from './utils-hoist/misc';
 import { SyncPromise, rejectedSyncPromise, resolvedSyncPromise } from './utils-hoist/syncpromise';
 import { getPossibleEventMessages } from './utils/eventUtils';
+import { merge } from './utils/merge';
 import { parseSampleRate } from './utils/parseSampleRate';
 import { prepareEvent } from './utils/prepareEvent';
 import { showSpanDropWarning } from './utils/spanUtils';
+import { convertSpanJsonToTransactionEvent, convertTransactionEventToSpanJson } from './utils/transactionEvent';
 
 const ALREADY_SEEN_ERROR = "Not capturing exception because it's already been captured.";
 const MISSING_RELEASE_FOR_SESSION_ERROR = 'Discarded session because of missing or non-string release';
@@ -1004,41 +1006,54 @@ function processBeforeSend(
   hint: EventHint,
 ): PromiseLike<Event | null> | Event | null {
   const { beforeSend, beforeSendTransaction, beforeSendSpan } = options;
+  let processedEvent = event;
 
-  if (isErrorEvent(event) && beforeSend) {
-    return beforeSend(event, hint);
+  if (isErrorEvent(processedEvent) && beforeSend) {
+    return beforeSend(processedEvent, hint);
   }
 
-  if (isTransactionEvent(event)) {
-    if (event.spans && beforeSendSpan) {
-      const processedSpans: SpanJSON[] = [];
-      for (const span of event.spans) {
-        const processedSpan = beforeSendSpan(span);
-        if (processedSpan) {
-          processedSpans.push(processedSpan);
-        } else {
-          showSpanDropWarning();
-          client.recordDroppedEvent('before_send', 'span');
+  if (isTransactionEvent(processedEvent)) {
+    if (beforeSendSpan) {
+      // process root span
+      const processedRootSpanJson = beforeSendSpan(convertTransactionEventToSpanJson(processedEvent));
+      if (!processedRootSpanJson) {
+        showSpanDropWarning();
+      } else {
+        // update event with processed root span values
+        processedEvent = merge(event, convertSpanJsonToTransactionEvent(processedRootSpanJson));
+      }
+
+      // process child spans
+      if (processedEvent.spans) {
+        const processedSpans: SpanJSON[] = [];
+        for (const span of processedEvent.spans) {
+          const processedSpan = beforeSendSpan(span);
+          if (!processedSpan) {
+            showSpanDropWarning();
+            processedSpans.push(span);
+          } else {
+            processedSpans.push(processedSpan);
+          }
         }
+        processedEvent.spans = processedSpans;
       }
-      event.spans = processedSpans;
     }
 
     if (beforeSendTransaction) {
-      if (event.spans) {
+      if (processedEvent.spans) {
         // We store the # of spans before processing in SDK metadata,
         // so we can compare it afterwards to determine how many spans were dropped
-        const spanCountBefore = event.spans.length;
-        event.sdkProcessingMetadata = {
+        const spanCountBefore = processedEvent.spans.length;
+        processedEvent.sdkProcessingMetadata = {
           ...event.sdkProcessingMetadata,
           spanCountBeforeProcessing: spanCountBefore,
         };
       }
-      return beforeSendTransaction(event, hint);
+      return beforeSendTransaction(processedEvent as TransactionEvent, hint);
     }
   }
 
-  return event;
+  return processedEvent;
 }
 
 function isErrorEvent(event: Event): event is ErrorEvent {

packages/core/src/envelope.ts

@@ -18,7 +18,6 @@ import type {
   SessionItem,
   SpanEnvelope,
   SpanItem,
-  SpanJSON,
 } from './types-hoist';
 import { dsnToString } from './utils-hoist/dsn';
 import {
@@ -127,13 +126,17 @@ export function createSpanEnvelope(spans: [SentrySpan, ...SentrySpan[]], client?
   const beforeSendSpan = client && client.getOptions().beforeSendSpan;
   const convertToSpanJSON = beforeSendSpan
     ? (span: SentrySpan) => {
-        const spanJson = beforeSendSpan(spanToJSON(span) as SpanJSON);
-        if (!spanJson) {
+        const spanJson = spanToJSON(span);
+        const processedSpan = beforeSendSpan(spanJson);
+
+        if (!processedSpan) {
           showSpanDropWarning();
+          return spanJson;
         }
-        return spanJson;
+
+        return processedSpan;
       }
-    : (span: SentrySpan) => spanToJSON(span);
+    : spanToJSON;
 
   const items: SpanItem[] = [];
   for (const span of spans) {

packages/core/src/types-hoist/options.ts

@@ -290,7 +290,7 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
    *
    * @returns A new span that will be sent or null if the span should not be sent.
    */
-  beforeSendSpan?: (span: SpanJSON) => SpanJSON | null;
+  beforeSendSpan?: (span: SpanJSON) => SpanJSON;
 
   /**
    * An event-processing callback for transaction events, guaranteed to be invoked after all other event

packages/core/src/utils/spanUtils.ts

@@ -286,7 +286,7 @@ export function showSpanDropWarning(): void {
     consoleSandbox(() => {
       // eslint-disable-next-line no-console
       console.warn(
-        '[Sentry] Deprecation warning: Returning null from `beforeSendSpan` will be disallowed from SDK version 9.0.0 onwards. The callback will only support mutating spans. To drop certain spans, configure the respective integrations directly.',
+        '[Sentry] Returning null from `beforeSendSpan` is disallowed. To drop certain spans, configure the respective integrations directly.',
       );
     });
     hasShownSpanDropWarning = true;

packages/core/src/utils/transactionEvent.ts

@@ -0,0 +1,57 @@
+import { SEMANTIC_ATTRIBUTE_EXCLUSIVE_TIME, SEMANTIC_ATTRIBUTE_PROFILE_ID } from '../semanticAttributes';
+import type { SpanJSON, TransactionEvent } from '../types-hoist';
+import { dropUndefinedKeys } from '../utils-hoist';
+
+/**
+ * Converts a transaction event to a span JSON object.
+ */
+export function convertTransactionEventToSpanJson(event: TransactionEvent): SpanJSON {
+  const { trace_id, parent_span_id, span_id, status, origin, data, op } = event.contexts?.trace ?? {};
+
+  return dropUndefinedKeys({
+    data: data ?? {},
+    description: event.transaction,
+    op,
+    parent_span_id,
+    span_id: span_id ?? '',
+    start_timestamp: event.start_timestamp ?? 0,
+    status,
+    timestamp: event.timestamp,
+    trace_id: trace_id ?? '',
+    origin,
+    profile_id: data?.[SEMANTIC_ATTRIBUTE_PROFILE_ID] as string | undefined,
+    exclusive_time: data?.[SEMANTIC_ATTRIBUTE_EXCLUSIVE_TIME] as number | undefined,
+    measurements: event.measurements,
+    is_segment: true,
+  });
+}
+
+/**
+ * Converts a span JSON object to a transaction event.
+ */
+export function convertSpanJsonToTransactionEvent(span: SpanJSON): TransactionEvent {
+  const event: TransactionEvent = {
+    type: 'transaction',
+    timestamp: span.timestamp,
+    start_timestamp: span.start_timestamp,
+    transaction: span.description,
+    contexts: {
+      trace: {
+        trace_id: span.trace_id,
+        span_id: span.span_id,
+        parent_span_id: span.parent_span_id,
+        op: span.op,
+        status: span.status,
+        origin: span.origin,
+        data: {
+          ...span.data,
+          ...(span.profile_id && { [SEMANTIC_ATTRIBUTE_PROFILE_ID]: span.profile_id }),
+          ...(span.exclusive_time && { [SEMANTIC_ATTRIBUTE_EXCLUSIVE_TIME]: span.exclusive_time }),
+        },
+      },
+    },
+    measurements: span.measurements,
+  };
+
+  return dropUndefinedKeys(event);
+}