remove marker type and "cheat" in withStaticSpan callback

Author: Lms24

MIGRATION.md

@@ -191,7 +191,7 @@ beforeSendSpan: Sentry.withStreamedSpan(span => span);
 beforeSendSpan: span => span;
 ```
 
-The internal `isStreamedBeforeSendSpanCallback()` function from `@sentry/core` is no longer exported.
+The internal `isStreamedBeforeSendSpanCallback()` function from `@sentry/core` was removed.
 
 #### Replacing `beforeSendTransaction`
 

packages/core/src/client.ts

@@ -39,7 +39,7 @@ import type { StartSpanOptions } from './types/startSpanOptions';
 import type { Transport, TransportMakeRequestResponse } from './types/transport';
 import type { ResolvedDataCollection } from './types/datacollection';
 import { createClientReportEnvelope } from './utils/clientreport';
-import { debug } from './utils/debug-logger';
+import { consoleSandbox, debug } from './utils/debug-logger';
 import { dsnToString, makeDsn } from './utils/dsn';
 import { addItemToEnvelope, createAttachmentEnvelopeItem } from './utils/envelope';
 import { getPossibleEventMessages } from './utils/eventUtils';
@@ -263,11 +263,14 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
       beforeSendSpan &&
       isStaticBeforeSendSpanCallback(beforeSendSpan) !== (traceLifecycle === 'static')
     ) {
-      debug.warn(
-        `Ignoring \`beforeSendSpan\`: ${
-          traceLifecycle === 'static' ? 'wrap it with' : 'remove'
-        } \`Sentry.withStaticSpan\` to use it with \`traceLifecycle: "${traceLifecycle}"\`.`,
-      );
+      consoleSandbox(() => {
+        // oxlint-disable-next-line no-console
+        console.warn(
+          `Ignoring \`beforeSendSpan\`: ${
+            traceLifecycle === 'static' ? 'wrap it with' : 'remove'
+          } \`Sentry.withStaticSpan\` to use it with \`traceLifecycle: "${traceLifecycle}"\`.`,
+        );
+      });
     }
 
     if (this._dsn) {

packages/core/src/tracing/spans/beforeSendSpan.ts

@@ -1,12 +1,12 @@
 import type { BeforeSendStaticSpanCallback, BeforeSendStreamedSpanCallback } from '../../types/options';
-import type { SpanJSON, StreamedSpanJSON } from '../../types/span';
+import type { StreamedSpanJSON } from '../../types/span';
 import { addNonEnumerableProperty } from '../../utils/object';
 
 /**
  * A wrapper to use the static, transaction-based span format in your `beforeSendSpan` callback.
  *
  * When using `traceLifecycle: 'static'`, wrap your callback with this function
- * to receive and return {@link SpanJSON} instead of {@link StreamedSpanJSON}.
+ * to receive and return a static span instead of a {@link StreamedSpanJSON}.
  *
  * @example
  *
@@ -18,12 +18,15 @@ import { addNonEnumerableProperty } from '../../utils/object';
  *   }),
  * });
  *
- * @param callback - The callback function that receives and returns a {@link SpanJSON}.
+ * @param callback - A {@link BeforeSendStaticSpanCallback} that receives and returns a static span.
  * @returns A callback that is compatible with the `beforeSendSpan` option when using `traceLifecycle: 'static'`.
  */
-export function withStaticSpan(callback: (span: SpanJSON) => SpanJSON): BeforeSendStaticSpanCallback {
+export function withStaticSpan(callback: BeforeSendStaticSpanCallback): BeforeSendStreamedSpanCallback {
   addNonEnumerableProperty(callback, '_static', true);
-  return callback as BeforeSendStaticSpanCallback;
+  // `beforeSendSpan` is typed as a single streamed callback so that an unwrapped callback's parameter
+  // is contextually typed as `StreamedSpanJSON`. The `_static` marker tells the SDK to hand this
+  // callback a `SpanJSON` instead, so the declared parameter type is deliberately not what it receives.
+  return callback as unknown as BeforeSendStreamedSpanCallback;
 }
 
 /**
@@ -50,13 +53,3 @@ export function withStreamedSpan(
 export function isStaticBeforeSendSpanCallback(callback: unknown): callback is BeforeSendStaticSpanCallback {
   return !!callback && typeof callback === 'function' && '_static' in callback && !!callback._static;
 }
-
-/**
- * Typesafe check to identify if a `beforeSendSpan` callback expects the streamed span JSON format.
- *
- * @param callback - The `beforeSendSpan` callback to check.
- * @returns `true` unless the callback was marked as a static span callback.
- */
-export function isStreamedBeforeSendSpanCallback(callback: unknown): callback is BeforeSendStreamedSpanCallback {
-  return !!callback && typeof callback === 'function' && !isStaticBeforeSendSpanCallback(callback);
-}

packages/core/src/tracing/spans/captureSpan.ts

@@ -20,8 +20,7 @@ import {
   streamedSpanJsonToSerializedSpan,
 } from '../../utils/spanUtils';
 import { getCapturedScopesOnSpan } from '../utils';
-import { isStaticBeforeSendSpanCallback, isStreamedBeforeSendSpanCallback } from './beforeSendSpan';
-import { hasSpanStreamingEnabled } from './hasSpanStreamingEnabled';
+import { isStaticBeforeSendSpanCallback } from './beforeSendSpan';
 import { scopeContextsToSpanAttributes } from './scopeContextAttributes';
 import { spanJsonToStreamedSpanJson, streamedSpanJsonToSpanJson } from './spanJsonToStreamedSpan';
 import { DEFAULT_ENVIRONMENT } from '../../constants';
@@ -161,14 +160,14 @@ function applyCommonSpanAttributes(
  * TODO(v12): Remove the v1 and static callback conversion shenanigans once we drop transactions.
  */
 function applyBeforeSendSpan(span: StreamedSpanJSON, client: Client): StreamedSpanJSON {
-  const { beforeSendSpan } = client.getOptions();
+  const { beforeSendSpan, traceLifecycle } = client.getOptions();
 
   if (!beforeSendSpan) {
     return span;
   }
 
-  if (hasSpanStreamingEnabled(client)) {
-    return isStreamedBeforeSendSpanCallback(beforeSendSpan) ? applyBeforeSendSpanCallback(span, beforeSendSpan) : span;
+  if (traceLifecycle === 'stream') {
+    return !isStaticBeforeSendSpanCallback(beforeSendSpan) ? applyBeforeSendSpanCallback(span, beforeSendSpan) : span;
   }
 
   return isStaticBeforeSendSpanCallback(beforeSendSpan)

packages/core/src/types/options.ts

@@ -640,7 +640,7 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
    *
    * @returns The modified span payload that will be sent.
    */
-  beforeSendSpan?: BeforeSendStreamedSpanCallback | BeforeSendStaticSpanCallbackMarker;
+  beforeSendSpan?: BeforeSendStreamedSpanCallback;
 
   /**
    * An event-processing callback for transaction events, guaranteed to be invoked after all other event
@@ -680,16 +680,13 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
 export type BeforeSendStreamedSpanCallback = (span: StreamedSpanJSON) => StreamedSpanJSON;
 
 /**
- * The marker that {@link withStaticSpan} adds to a `beforeSendSpan` callback.
+ * A callback for processing spans sent as part of transaction events.
  *
- * Deliberately not callable: `beforeSendSpan` must have exactly one call signature for TypeScript to
- * contextually type an unwrapped callback's parameter as {@link StreamedSpanJSON}. A union of two
- * callable types would infer `any` instead.
+ * Pass this to {@link withStaticSpan} rather than to `beforeSendSpan` directly.
+ *
+ * @see {@link SpanJSON} for the static span format used with `traceLifecycle: 'static'`
  */
-type BeforeSendStaticSpanCallbackMarker = { _static: true };
-
-/** A callback for processing spans sent as part of transaction events. */
-export type BeforeSendStaticSpanCallback = ((span: SpanJSON) => SpanJSON) & BeforeSendStaticSpanCallbackMarker;
+export type BeforeSendStaticSpanCallback = (span: SpanJSON) => SpanJSON;
 
 /** Base configuration options for every SDK. */
 export interface CoreOptions<TO extends BaseTransportOptions = BaseTransportOptions> extends Omit<