feat(core): Add managed tunnel helpers that derive the tunnel path from the DSN

packages/core/src/client.ts

@@ -41,6 +41,7 @@ import type { ResolvedDataCollection } from './types/datacollection';
 import { createClientReportEnvelope } from './utils/clientreport';
 import { consoleSandbox, debug } from './utils/debug-logger';
 import { dsnToString, makeDsn } from './utils/dsn';
+import { getTunnelIgnoreSpanFilter } from './utils/tunnel';
 import { addItemToEnvelope, createAttachmentEnvelopeItem, getDataCategoryByType } from './utils/envelope';
 import { getPossibleEventMessages, isInternalException } from './utils/eventUtils';
 import { isObjectLike, isParameterizedString, isPlainObject, isPrimitive } from './utils/is';
@@ -271,6 +272,11 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
       DEBUG_BUILD && debug.warn('No DSN provided, client will not send events.');
     }
 
+    const tunnelSpanFilter = options._managedTunnel && getTunnelIgnoreSpanFilter(options._managedTunnel, this._dsn);
+    if (tunnelSpanFilter) {
+      this._options.ignoreSpans = [...(this._options.ignoreSpans ?? []), tunnelSpanFilter];
+    }
+
     const { beforeSendSpan, traceLifecycle } = this._options;
     // A `beforeSendSpan` callback is only invoked for the span format matching the trace lifecycle,
     // so a mismatch means it is silently never called.

packages/core/src/index.ts

@@ -101,8 +101,19 @@ export { isSentryRequestUrl } from './utils/isSentryRequestUrl';
 export { handleCallbackErrors } from './utils/handleCallbackErrors';
 export { safeCallback } from './utils/safeCallback';
 export { parameterize, fmt } from './utils/parameterize';
-export type { HandleTunnelRequestOptions } from './utils/tunnel';
-export { handleTunnelRequest } from './utils/tunnel';
+export type { HandleTunnelRequestOptions, TunnelRequestLike } from './utils/tunnel';
+export {
+  applyTunnelDefaults,
+  getTunnelPath,
+  getTunnelPaths,
+  handleTunnelRequest,
+  handleTunnelRequestIfMatched,
+  isTunnelRequest,
+  normalizeTunnelBasePath,
+  resolveServerTunnelOption,
+  setManagedTunnelBasePath,
+  TUNNEL_RESPONSE_HEADER,
+} from './utils/tunnel';
 export { addAutoIpAddressToSession } from './utils/ipAddress';
 export {
   convertSpanLinksForEnvelope,
@@ -415,7 +426,7 @@ export type {
   HttpHeadersCollection,
   ResolvedDataCollection,
 } from './types/datacollection';
-export type { ClientOptions, CoreOptions as Options } from './types/options';
+export type { ClientOptions, CoreOptions as Options, TunnelOptions } from './types/options';
 export type { Package } from './types/package';
 export type { PolymorphicEvent, PolymorphicRequest } from './types/polymorphics';
 export type {

packages/core/src/integrations/fetch.ts

@@ -5,6 +5,7 @@ import { getClient } from '../currentScopes';
 import { instrumentFetchRequest } from '../fetch';
 import { defineIntegration } from '../integration';
 import { addFetchInstrumentationHandler } from '../instrument/fetch';
+import { isTracingSuppressed } from '../tracing/trace';
 import type { FetchBreadcrumbData, FetchBreadcrumbHint } from '../types/breadcrumb';
 import type { HandlerDataFetch } from '../types/instrument';
 import type { Integration, IntegrationFn } from '../types/integration';
@@ -92,7 +93,8 @@ export function createFetchIntegration({
             return;
           }
 
-          if (isSentryRequestUrl(handlerData.fetchData.url, client)) {
+          // Matches Node's http and undici instrumentation, so SDK-internal requests (e.g. a tunnel forward) leave no breadcrumb.
+          if (isTracingSuppressed() || isSentryRequestUrl(handlerData.fetchData.url, client)) {
             return;
           }
 

packages/core/src/types/options.ts

@@ -96,7 +96,7 @@ export type IgnoreSpanAttributeValue = string | boolean | number | string[] | bo
  * At least one of the properties (`name`, `op`, or `attributes`) must be set.
  * If multiple are set, all must match for the span to be ignored.
  */
-type IgnoreSpanFilter =
+export type IgnoreSpanFilter =
   | {
       /**
        * Spans with a name matching this pattern will be ignored.
@@ -373,6 +373,14 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
    */
   tunnel?: string;
 
+  /**
+   * Set by server SDKs when the managed tunnel is enabled. Server request handlers check it to decide whether to
+   * serve the managed tunnel.
+   *
+   * @internal This option is not part of the public API and is subject to change at any time.
+   */
+  _managedTunnel?: TunnelOptions;
+
   /**
    * Controls what data the SDK collects and sends to Sentry.
    * All fields are optional — omitted fields use the documented defaults.
@@ -645,6 +653,24 @@ export type BeforeSendStreamedSpanCallback = (span: StreamedSpanJSON) => Streame
  */
 export type BeforeSendStaticSpanCallback = (span: SpanJSON) => SpanJSON;
 
+/** Options for the managed tunnel, see `tunnel`. */
+export interface TunnelOptions {
+  /**
+   * Server only. DSNs whose envelopes the tunnel forwards, in addition to the server's own DSN. List the browser DSN
+   * here when the browser uses a different one.
+   */
+  allowedDsns?: string[];
+
+  /** A fixed tunnel path instead of the one derived from the DSN. A relative `tunnel` string sets this. */
+  path?: string;
+
+  /** Path prefix the app is served under, e.g. `/docs`. Set the same value in the browser and the server `init`. */
+  basePath?: string;
+
+  /** Browser only. Append a trailing slash to the tunnel path, for servers that redirect paths without one. */
+  trailingSlash?: boolean;
+}
+
 /** Base configuration options for every SDK. */
 export interface CoreOptions<TO extends BaseTransportOptions = BaseTransportOptions> extends Omit<
   Partial<ClientOptions<TO>>,