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

packages/core/src/index.ts

@@ -102,7 +102,13 @@ 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 {
+  applyTunnelDefaults as _INTERNAL_applyTunnelDefaults,
+  getTunnelPath,
+  handleTunnelRequest,
+  normalizeTunnelBasePath as _INTERNAL_normalizeTunnelBasePath,
+  TUNNEL_RESPONSE_HEADER,
+} from './utils/tunnel';
 export { addAutoIpAddressToSession } from './utils/ipAddress';
 export {
   convertSpanLinksForEnvelope,
@@ -415,7 +421,14 @@ export type {
   HttpHeadersCollection,
   ResolvedDataCollection,
 } from './types/datacollection';
-export type { ClientOptions, CoreOptions as Options } from './types/options';
+export type {
+  BrowserTunnelOptions,
+  ClientOptions,
+  CoreOptions as Options,
+  ServerTunnelOptions,
+  TunnelInit,
+  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)) {
+          // Like Node's http and undici instrumentation: SDK-internal requests leave no breadcrumb.
+          if (isTracingSuppressed() || isSentryRequestUrl(handlerData.fetchData.url, client)) {
             return;
           }
 

packages/core/src/server-runtime-client.ts

@@ -21,6 +21,7 @@ import { uuid4 } from './utils/misc';
 import { makePromiseBuffer } from './utils/promisebuffer';
 import { resolvedSyncPromise } from './utils/syncpromise';
 import { _getTraceInfoFromScope } from './utils/trace-info';
+import { applyManagedTunnelDefaults } from './utils/managedTunnelDefaults';
 
 export interface ServerRuntimeClientOptions extends ClientOptions<BaseTransportOptions> {
   platform?: string;
@@ -58,6 +59,7 @@ export class ServerRuntimeClient<
 
     super(options);
 
+    applyManagedTunnelDefaults(this);
     this._setUpMetricsProcessing();
   }
 

packages/core/src/server.ts

@@ -6,6 +6,17 @@
 
 export type { ServerRuntimeClientOptions } from './server-runtime-client';
 export { ServerRuntimeClient } from './server-runtime-client';
+export type { TunnelRequestLike } from './utils/tunnel';
+export {
+  getTunnelPaths as _INTERNAL_getTunnelPaths,
+  handleTunnelRequestIfMatched,
+  isTunnelRequest,
+  resolveServerTunnelOption as _INTERNAL_resolveServerTunnelOption,
+} from './utils/tunnel';
+export {
+  _INTERNAL_resetManagedTunnelDefaults,
+  setManagedTunnelDefaults as _INTERNAL_setManagedTunnelDefaults,
+} from './utils/managedTunnelDefaults';
 export type { ServerRuntimeOptions } from './types/options';
 export { trpcMiddleware } from './trpc';
 export { wrapMcpServerWithSentry } from './integrations/mcp-server';

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,13 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
    */
   tunnel?: string;
 
+  /**
+   * Set by server SDKs when the managed tunnel is enabled.
+   *
+   * @internal This option is not part of the public API and is subject to change at any time.
+   */
+  _managedTunnel?: ServerTunnelOptions;
+
   /**
    * Controls what data the SDK collects and sends to Sentry.
    * All fields are optional — omitted fields use the documented defaults.
@@ -645,6 +652,40 @@ export type BeforeSendStreamedSpanCallback = (span: StreamedSpanJSON) => Streame
  */
 export type BeforeSendStaticSpanCallback = (span: SpanJSON) => SpanJSON;
 
+/** Managed tunnel options shared by the browser and the server `init`, see `tunnel`. */
+export interface TunnelOptions {
+  /** 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;
+}
+
+/** Managed tunnel options for the browser `init`. */
+export interface BrowserTunnelOptions extends TunnelOptions {
+  /** Append a trailing slash to the tunnel path, for servers that redirect paths without one. */
+  trailingSlash?: boolean;
+}
+
+/** Managed tunnel options for a server `init`. */
+export interface ServerTunnelOptions extends TunnelOptions {
+  /** DSNs to forward besides the server's own, e.g. a different browser DSN. */
+  allowedDsns?: string[];
+}
+
+/**
+ * The `tunnel` option, where to send envelopes instead of the Sentry ingest URL:
+ *
+ * - A URL, e.g. `https://example.com/tunnel`, sends envelopes to your own tunnel endpoint.
+ * - A relative path, e.g. `/monitor`, enables the managed tunnel at that fixed path. The browser sends envelopes to
+ *   it and the server SDK serves it, so set the same path in both `init`s.
+ * - `true` enables the managed tunnel at a same-origin path derived from the DSN. Set it in both the browser and the
+ *   server `init`: the browser sends envelopes to that path and the server SDK forwards them to Sentry. This keeps
+ *   ad-blockers from dropping events.
+ * - Options, like `true`, with the browser or server options of the managed tunnel.
+ */
+export type TunnelInit<T extends TunnelOptions = TunnelOptions> = string | true | T;
+
 /** Base configuration options for every SDK. */
 export interface CoreOptions<TO extends BaseTransportOptions = BaseTransportOptions> extends Omit<
   Partial<ClientOptions<TO>>,

packages/core/src/utils/managedTunnelDefaults.ts

@@ -0,0 +1,80 @@
+import type { Client } from '../client';
+import { getClient } from '../currentScopes';
+import type { IgnoreSpanFilter, ServerTunnelOptions } from '../types/options';
+import {
+  getTunnelIgnoreSpanFilters,
+  normalizeTunnelBasePath,
+  resolveAllowedDsns,
+  resolveTunnelPaths,
+  setServedTunnel,
+  stripBasePathFromTunnelPath,
+} from './tunnel';
+
+/**
+ * Managed tunnel settings a framework SDK knows outside `init`.
+ */
+interface ManagedTunnelDefaults {
+  /**
+   * Enables the managed tunnel when `init` didn't, e.g. from TanStack Start's `tunnelRoute` build option. Its base
+   * path is `basePath`, so it has none of its own.
+   */
+  tunnel?: Omit<ServerTunnelOptions, 'basePath'>;
+  /** The path prefix the app is served under. Applies however the tunnel was enabled, unless `init` set its own. */
+  basePath?: string;
+}
+
+let managedTunnelDefaults: ManagedTunnelDefaults | undefined;
+
+// So re-applying defaults replaces a client's filters instead of adding more.
+const installedSpanFilters = new WeakMap<Client, IgnoreSpanFilter[]>();
+
+/**
+ * Sets framework-known tunnel settings for the current and every later server client, so per-request clients
+ * (Cloudflare) start with them. Settings from `init` win. Framework SDKs call this once at load.
+ */
+export function setManagedTunnelDefaults(defaults: ManagedTunnelDefaults): void {
+  managedTunnelDefaults = {
+    ...managedTunnelDefaults,
+    ...(defaults.tunnel && { tunnel: defaults.tunnel }),
+    ...(defaults.basePath !== undefined && { basePath: defaults.basePath }),
+  };
+  applyManagedTunnelDefaults(getClient());
+}
+
+/**
+ * Resolves a server client's managed tunnel (from `init` or the defaults), computes its paths and allowed DSNs, and
+ * installs its span filters. Runs when a server client is created and from {@link setManagedTunnelDefaults}.
+ */
+export function applyManagedTunnelDefaults(client: Client | undefined): void {
+  const options = client?.getOptions();
+  const tunnelOptions: ServerTunnelOptions | undefined = options?._managedTunnel ?? managedTunnelDefaults?.tunnel;
+  if (!client || !options || !tunnelOptions) {
+    return;
+  }
+
+  const basePath = normalizeTunnelBasePath(managedTunnelDefaults?.basePath);
+  const resolved = stripBasePathFromTunnelPath(
+    tunnelOptions.basePath === undefined && basePath ? { ...tunnelOptions, basePath } : tunnelOptions,
+  );
+  options._managedTunnel = resolved;
+  const allowedDsns = resolveAllowedDsns(resolved.allowedDsns, client.getDsn());
+  const paths = resolveTunnelPaths(resolved, allowedDsns);
+  setServedTunnel(client, { paths, allowedDsns });
+
+  const previousFilters = installedSpanFilters.get(client) ?? [];
+  const spanFilters = getTunnelIgnoreSpanFilters(resolved, paths);
+  options.ignoreSpans = [
+    ...(options.ignoreSpans ?? []).filter(filter => !(previousFilters as unknown[]).includes(filter)),
+    ...spanFilters,
+  ];
+  installedSpanFilters.set(client, spanFilters);
+}
+
+/**
+ * Resets {@link setManagedTunnelDefaults}, for tests.
+ *
+ * @internal
+ */
+export function _INTERNAL_resetManagedTunnelDefaults(): void {
+  managedTunnelDefaults = undefined;
+}