feat(core): Log warnings when returning null in beforeSendSpan

packages/core/src/baseclient.ts

@@ -52,6 +52,7 @@ import { dropUndefinedKeys } from './utils-hoist/object';
 import { SyncPromise, rejectedSyncPromise, resolvedSyncPromise } from './utils-hoist/syncpromise';
 import { parseSampleRate } from './utils/parseSampleRate';
 import { prepareEvent } from './utils/prepareEvent';
+import { showSpanDropWarning } from './utils/spanUtils';
 
 const ALREADY_SEEN_ERROR = "Not capturing exception because it's already been captured.";
 
@@ -977,6 +978,7 @@ function processBeforeSend(
         if (processedSpan) {
           processedSpans.push(processedSpan);
         } else {
+          showSpanDropWarning();
           client.recordDroppedEvent('before_send', 'span');
         }
       }

packages/core/src/envelope.ts

@@ -24,7 +24,7 @@ import {
   createSpanEnvelopeItem,
   getSdkMetadataForEnvelopeHeader,
 } from './utils-hoist/envelope';
-import { spanToJSON } from './utils/spanUtils';
+import { showSpanDropWarning, spanToJSON } from './utils/spanUtils';
 
 /**
  * Apply SdkInfo (name, version, packages, integrations) to the corresponding event key.
@@ -122,7 +122,13 @@ export function createSpanEnvelope(spans: [SentrySpan, ...SentrySpan[]], client?
 
   const beforeSendSpan = client && client.getOptions().beforeSendSpan;
   const convertToSpanJSON = beforeSendSpan
-    ? (span: SentrySpan) => beforeSendSpan(spanToJSON(span) as SpanJSON)
+    ? (span: SentrySpan) => {
+        const spanJson = beforeSendSpan(spanToJSON(span) as SpanJSON);
+        if (!spanJson) {
+          showSpanDropWarning();
+        }
+        return spanJson;
+      }
     : (span: SentrySpan) => spanToJSON(span);
 
   const items: SpanItem[] = [];

packages/core/src/utils/spanUtils.ts

@@ -12,11 +12,13 @@ import type {
 import { getAsyncContextStrategy } from '../asyncContext';
 import { getMainCarrier } from '../carrier';
 import { getCurrentScope } from '../currentScopes';
+import { DEBUG_BUILD } from '../debug-build';
 import { getMetricSummaryJsonForSpan, updateMetricSummaryOnSpan } from '../metrics/metric-summary';
 import type { MetricType } from '../metrics/types';
 import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '../semanticAttributes';
 import type { SentrySpan } from '../tracing/sentrySpan';
 import { SPAN_STATUS_OK, SPAN_STATUS_UNSET } from '../tracing/spanstatus';
+import { logger } from '../utils-hoist/logger';
 import { addNonEnumerableProperty, dropUndefinedKeys } from '../utils-hoist/object';
 import { timestampInSeconds } from '../utils-hoist/time';
 import { generateSentryTraceHeader } from '../utils-hoist/tracing';
@@ -26,6 +28,11 @@ import { _getSpanForScope } from './spanOnScope';
 export const TRACE_FLAG_NONE = 0x0;
 export const TRACE_FLAG_SAMPLED = 0x1;
 
+// todo(v9): Remove this once we've stopped dropping spans via `beforeSendSpan`
+const SPAN_DROP_WARNING =
+  'Dropping spans via `beforeSendSpan` will be removed in SDK v9.0.0. The callback will only support modifying span attributes.';
+let hasShownSpanDropWarning = false;
+
 /**
  * Convert a span to a trace context, which can be sent as the `trace` context in an event.
  * By default, this will only include trace_id, span_id & parent_span_id.
@@ -280,3 +287,15 @@ export function updateMetricSummaryOnActiveSpan(
     updateMetricSummaryOnSpan(span, metricType, sanitizedName, value, unit, tags, bucketKey);
   }
 }
+
+/**
+ * Logs a warning once if `beforeSendSpan` is used to drop spans.
+ *
+ * todo(v9): Remove this once we've stopped dropping spans via `beforeSendSpan`.
+ */
+export function showSpanDropWarning(): void {
+  if (DEBUG_BUILD && !hasShownSpanDropWarning) {
+    logger.warn(SPAN_DROP_WARNING);
+    hasShownSpanDropWarning = true;
+  }
+}