feat(core): Deprecate forceTransaction option in StartSpanOptions

packages/bundler-plugins/src/core/build-plugin-manager.ts

@@ -524,6 +524,7 @@ export function createSentryBuildPluginManager(
       Only use this if you need to manually inject debug IDs into the build artifacts.
     */
     async injectDebugIds(buildArtifactPaths: string[]) {
+      // oxlint-disable-next-line typescript/no-deprecated
       await startSpan({ name: 'inject-debug-ids', scope: sentryScope, forceTransaction: true }, async () => {
         try {
           const cliInstance = new SentryCliAdapter(options);
@@ -561,6 +562,7 @@ export function createSentryBuildPluginManager(
 
       await startSpan(
         // This is `forceTransaction`ed because this span is used in dashboards in the form of indexed transactions.
+        // oxlint-disable-next-line typescript/no-deprecated
         { name: 'debug-id-sourcemap-upload', scope: sentryScope, forceTransaction: true },
         async () => {
           // If we're not using a temp folder, we must not prepare artifacts in-place (to avoid mutating user files)

packages/core/src/integrations/mcp-server/spans.ts

@@ -115,6 +115,7 @@ function createMcpSpan(config: McpSpanConfig): unknown {
   return startSpan(
     {
       name: spanName,
+      // oxlint-disable-next-line typescript/no-deprecated
       forceTransaction: true,
       attributes,
     },

packages/core/src/tracing/trace.ts

@@ -52,6 +52,7 @@ import { SUPPRESS_TRACING_KEY } from './constants';
  */
 export function startSpan<T>(options: StartSpanOptions, callback: (span: Span) => T): T {
   const spanArguments = parseSentrySpanArguments(options);
+  // oxlint-disable-next-line typescript/no-deprecated
   const { forceTransaction, parentSpan: customParentSpan, scope: customScope } = options;
 
   // We still need to fork a potentially passed scope, as we set the active span on it
@@ -104,6 +105,7 @@ export function startSpan<T>(options: StartSpanOptions, callback: (span: Span) =
  */
 export function startSpanManual<T>(options: StartSpanOptions, callback: (span: Span, finish: () => void) => T): T {
   const spanArguments = parseSentrySpanArguments(options);
+  // oxlint-disable-next-line typescript/no-deprecated
   const { forceTransaction, parentSpan: customParentSpan, scope: customScope } = options;
 
   const customForkedScope = customScope?.clone();
@@ -150,6 +152,7 @@ export function startSpanManual<T>(options: StartSpanOptions, callback: (span: S
  */
 export function startInactiveSpan(options: StartSpanOptions): Span {
   const spanArguments = parseSentrySpanArguments(options);
+  // oxlint-disable-next-line typescript/no-deprecated
   const { forceTransaction, parentSpan: customParentSpan, scope: customScope } = options;
 
   // If `options.scope` is defined, we use this as as a wrapper,

packages/core/src/trpc.ts

@@ -103,6 +103,7 @@ export function trpcMiddleware(options: SentryTrpcMiddlewareOptions = {}) {
             [TRPC_PROCEDURE_PATH]: String(path),
             [TRPC_PROCEDURE_TYPE]: String(type),
           },
+          // oxlint-disable-next-line typescript/no-deprecated
           forceTransaction: !!options.forceTransaction,
         },
         async span => {

packages/core/src/types/startSpanOptions.ts

@@ -39,6 +39,32 @@ export interface StartSpanOptions {
    * If set to true, this span will be forced to be treated as a transaction in the Sentry UI, if possible and applicable.
    * Note that it is up to the SDK to decide how exactly the span will be sent, which may change in future SDK versions.
    * It is not guaranteed that a span started with this flag set to `true` will be sent as a transaction.
+   *
+   * @deprecated This option will be removed in the next major version of the SDK. There is no longer a concrete use
+   * case for it: all spans are indexed and searchable in Sentry, so a span no longer needs to be a transaction to be
+   * queried, filtered or aggregated on. In most cases, simply drop the option. The span is still sent, just as a child
+   * of its parent span, if a parent span is active.
+   * If you do need the span to be a segment (root) span, follow the examples below:.
+   *
+   * @example Making a span a root span:
+   * ```js
+   * Sentry.withActiveSpan(null, () => {
+   *   Sentry.startSpan({ name: 'span-that-should-be-a-root' }, () => {
+   *     // ...
+   *   });
+   * });
+   * ```
+   *
+   * @example Keeping the root span attached to a specific trace:
+   * ```js
+   * Sentry.continueTrace({ sentryTrace, baggage }, () =>
+   *   Sentry.withActiveSpan(null, () =>
+   *     Sentry.startSpan({ name: 'span-that-should-be-a-root' }, () => {
+   *       // ...
+   *     }),
+   *   ),
+   * );
+   * ```
    */
   forceTransaction?: boolean;
 

packages/nestjs/src/integrations/helpers.ts

@@ -117,6 +117,7 @@ export function getEventSpanOptions(event: string): {
       [SENTRY_OP]: FUNCTION,
       [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.event.nestjs',
     },
+    // oxlint-disable-next-line typescript/no-deprecated
     forceTransaction: true,
   };
 }

packages/nextjs/src/common/withServerActionInstrumentation.ts

@@ -118,6 +118,7 @@ async function withServerActionInstrumentationImplementation<A extends (...args:
           return await startSpan(
             {
               name: `serverAction/${serverActionName}`,
+              // oxlint-disable-next-line typescript/no-deprecated
               forceTransaction: true,
               attributes: {
                 [SENTRY_KIND]: 'server',