fix(tanstackstart-react): Drop server transactions for tunnel route requests (#21769)

The server SDK was turning every incoming tunnel route request into an
`http.server` transaction. This drops tunnel traffic for both the static
and streamed (`traceLifecycle: 'stream'`) span lifecycles.

closes #21555

Author: logaretm

dev-packages/e2e-tests/test-applications/tanstackstart-react/instrument.server.mjs

@@ -5,6 +5,7 @@ Sentry.init({
   dsn: process.env.E2E_TEST_DSN,
   tunnel: `http://localhost:3031/`, // proxy server
   tracesSampleRate: 1,
+  traceLifecycle: process.env.E2E_TEST_STREAMED_SPANS === '1' ? 'stream' : 'static',
   transportOptions: {
     // We expect the app to send a lot of events in a short time
     bufferSize: 1000,

dev-packages/e2e-tests/test-applications/tanstackstart-react/package.json

@@ -17,6 +17,7 @@
     "test:assert:proxy": "pnpm test",
     "test:assert": "pnpm test:assert:proxy",
     "test:assert:tunnel-generated": "E2E_TEST_TUNNEL_ROUTE_MODE=dynamic E2E_TEST_DSN=http://public@localhost:3031/1337 pnpm test",
+    "test:assert:tunnel-streamed": "E2E_TEST_TUNNEL_ROUTE_MODE=dynamic E2E_TEST_DSN=http://public@localhost:3031/1337 E2E_TEST_STREAMED_SPANS=1 pnpm test",
     "test:assert:tunnel-static": "E2E_TEST_TUNNEL_ROUTE_MODE=static E2E_TEST_DSN=http://public@localhost:3031/1337 pnpm test",
     "test:assert:tunnel-custom": "E2E_TEST_CUSTOM_TUNNEL_ROUTE=1 pnpm test",
     "test:assert:tunnel-object": "E2E_TEST_TUNNEL_ROUTE_MODE=object E2E_TEST_DSN=http://public@localhost:3031/1337 pnpm test"
@@ -52,6 +53,11 @@
         "build-command": "pnpm test:build:tunnel-generated",
         "assert-command": "pnpm test:assert:tunnel-generated"
       },
+      {
+        "label": "tanstackstart-react (tunnel-streamed)",
+        "build-command": "pnpm test:build:tunnel-generated",
+        "assert-command": "pnpm test:assert:tunnel-streamed"
+      },
       {
         "label": "tanstackstart-react (tunnel-static)",
         "build-command": "pnpm test:build:tunnel-static",

dev-packages/e2e-tests/test-applications/tanstackstart-react/tests/tunnel.test.ts

@@ -1,8 +1,9 @@
 import { expect, test } from '@playwright/test';
-import { waitForError } from '@sentry-internal/test-utils';
+import { getSpanOp, waitForError, waitForStreamedSpan, waitForTransaction } from '@sentry-internal/test-utils';
 
 const tunnelRouteMode =
   process.env.E2E_TEST_TUNNEL_ROUTE_MODE ?? (process.env.E2E_TEST_CUSTOM_TUNNEL_ROUTE === '1' ? 'custom' : 'off');
+const useStreamedSpans = process.env.E2E_TEST_STREAMED_SPANS === '1';
 const expectedTunnelPathMatcher =
   tunnelRouteMode === 'static'
     ? '/monitor'
@@ -60,3 +61,68 @@ test('Sends client-side errors through the configured tunnel route', async ({ pa
   expect(errorEvent.exception?.values?.[0]?.value).toBe('Sentry Client Test Error');
   expect(errorEvent.transaction).toBe('/');
 });
+
+function pathnameMatchesTunnelRoute(pathname: string): boolean {
+  return typeof expectedTunnelPathMatcher === 'string'
+    ? pathname === expectedTunnelPathMatcher
+    : expectedTunnelPathMatcher.test(pathname);
+}
+
+// A server `http.server` transaction can arrive either as a classic transaction event (static trace
+// lifecycle) or as a Span v2 segment span (`traceLifecycle: 'stream'`). These helpers wait on whichever
+// format the current run produces, so the assertion below covers both lifecycles with one test body.
+function waitForServerHttpEvent(matchesPathname: (pathname: string) => boolean): Promise<unknown> {
+  if (useStreamedSpans) {
+    return waitForStreamedSpan('tanstackstart-react', span => {
+      return getSpanOp(span) === 'http.server' && matchesPathname((span.name ?? '').split(' ')[1] ?? '');
+    });
+  }
+
+  return waitForTransaction('tanstackstart-react', transactionEvent => {
+    return (
+      transactionEvent?.contexts?.trace?.op === 'http.server' &&
+      matchesPathname((transactionEvent.transaction ?? '').split(' ')[1] ?? '')
+    );
+  });
+}
+
+test('Does not create a server transaction for the tunnel route', async ({ page }) => {
+  // The incoming POST to the tunnel route must not be turned into an `http.server`
+  // transaction by the server SDK — tunnel traffic is plumbing, not application requests.
+  const tunnelServerEventPromise = waitForServerHttpEvent(pathnameMatchesTunnelRoute);
+
+  await page.goto('/');
+  const pageOrigin = new URL(page.url()).origin;
+
+  await page.locator('html[data-hydrated="true"]').waitFor();
+  await expect(page.locator('button').filter({ hasText: 'Break the client' })).toBeVisible();
+
+  const managedTunnelResponsePromise = page.waitForResponse(response => {
+    const responseUrl = new URL(response.url());
+
+    return (
+      responseUrl.origin === pageOrigin &&
+      response.request().method() === 'POST' &&
+      pathnameMatchesTunnelRoute(responseUrl.pathname)
+    );
+  });
+
+  await page.locator('button').filter({ hasText: 'Break the client' }).click();
+
+  // Ensure the tunnel POST was fully handled server-side before we issue the anchor request below.
+  await managedTunnelResponsePromise;
+
+  // Anchor on a regular server transaction issued *after* the tunnel POST. The Node transport flushes
+  // transactions/spans in FIFO order, so a (buggy) tunnel-route transaction would always arrive before
+  // this anchor. Racing the two lets us assert the absence of a tunnel transaction without idling on a timeout.
+  const anchorServerEventPromise = waitForServerHttpEvent(pathname => pathname.includes('/api/user/'));
+
+  await page.request.get('/api/user/456');
+
+  const winner = await Promise.race([
+    tunnelServerEventPromise.then(() => 'tunnel' as const),
+    anchorServerEventPromise.then(() => 'anchor' as const),
+  ]);
+
+  expect(winner).toBe('anchor');
+});

packages/tanstackstart-react/src/client/index.ts

@@ -55,3 +55,10 @@ export function createSentryTunnelRoute(_options: CreateSentryTunnelRouteOptions
     },
   };
 }
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed so the managed tunnel route module
+ * can statically import it (the call is server-guarded and tree-shaken from the client bundle).
+ */
+export function registerSentryServerTunnelRoute(_path: string): void {}

packages/tanstackstart-react/src/index.types.ts

@@ -44,3 +44,4 @@ export declare const tanstackRouterBrowserTracingIntegration: typeof clientSdk.t
 export declare const sentryGlobalRequestMiddleware: typeof serverSdk.sentryGlobalRequestMiddleware;
 export declare const sentryGlobalFunctionMiddleware: typeof serverSdk.sentryGlobalFunctionMiddleware;
 export declare const createSentryTunnelRoute: typeof serverSdk.createSentryTunnelRoute;
+export declare const registerSentryServerTunnelRoute: typeof serverSdk.registerSentryServerTunnelRoute;

packages/tanstackstart-react/src/server/index.ts

@@ -9,7 +9,7 @@ export { init } from './sdk';
 export { wrapFetchWithSentry } from './wrapFetchWithSentry';
 export { wrapMiddlewaresWithSentry } from './middleware';
 export { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from './globalMiddleware';
-export { createSentryTunnelRoute } from './tunnelRoute';
+export { createSentryTunnelRoute, registerSentryServerTunnelRoute } from './tunnelRoute';
 
 /**
  * A no-op stub of the replay integration for the server. Router setup code is shared between client and server,

packages/tanstackstart-react/src/server/tunnelRoute.ts

@@ -1,4 +1,31 @@
-import { dsnToString, getClient, handleTunnelRequest } from '@sentry/core';
+import { dsnToString, escapeStringForRegex, getClient, handleTunnelRequest } from '@sentry/core';
+
+const registeredTunnelRoutePaths = new Set<string>();
+
+/**
+ * Drops the incoming `http.server` transaction for a tunnel route by matching its request path (the
+ * `http.target` attribute, set at span creation, so it works for static and streamed lifecycles).
+ * Called at server startup for the managed route and from the handler (self-registration) otherwise.
+ */
+export function registerSentryServerTunnelRoute(path: string): void {
+  // Dedupe: the route module can be re-evaluated (HMR, multiple import paths).
+  if (registeredTunnelRoutePaths.has(path)) {
+    return;
+  }
+
+  const client = getClient();
+  if (!client) {
+    return;
+  }
+
+  registeredTunnelRoutePaths.add(path);
+
+  const options = client.getOptions();
+  options.ignoreSpans = [
+    ...(options.ignoreSpans ?? []),
+    { attributes: { 'http.target': new RegExp(`^${escapeStringForRegex(path)}(?:[/?#]|$)`) } },
+  ];
+}
 
 export interface CreateSentryTunnelRouteOptions {
   allowedDsns?: string[];
@@ -33,6 +60,12 @@ export function createSentryTunnelRoute(options: CreateSentryTunnelRouteOptions)
   return {
     handlers: {
       POST: async ({ request }) => {
+        // Self-register the path so the tunnel route's own transaction is dropped: at span-end for the
+        // static path, and at span-start for subsequent streamed requests. The first streamed request
+        // still leaks here (this runs after its span was sampled); managed routes avoid even that via
+        // the startup registration.
+        registerSentryServerTunnelRoute(new URL(request.url).pathname);
+
         const allowedDsnsFromOptions = options.allowedDsns?.length ? options.allowedDsns : undefined;
 
         const allowedDsns =

packages/tanstackstart-react/src/vite/tunnelRoute.ts

@@ -178,6 +178,14 @@ export function makeTunnelRoutePlugin(options: TunnelRouteOptions, debug?: boole
       }
 
       return `import { createFileRoute } from '@tanstack/react-router';
+import { registerSentryServerTunnelRoute } from '@sentry/tanstackstart-react';
+
+// Server-only: drop the tunnel route's own transaction. Registered synchronously at module evaluation
+// (before any request) so streamed spans are filtered from the first request. The SSR guard tree-shakes
+// it (and the import) out of the client bundle.
+if (import.meta.env.SSR) {
+  registerSentryServerTunnelRoute(${serializedTunnelRoute});
+}
 
 export const Route = createFileRoute(${serializedTunnelRoute})({
   server: {

packages/tanstackstart-react/test/server/tunnelRoute.test.ts

@@ -12,11 +12,11 @@ vi.mock('@sentry/core', async importOriginal => {
   };
 });
 
-const { createSentryTunnelRoute } = await import('../../src/server/tunnelRoute');
+const { createSentryTunnelRoute, registerSentryServerTunnelRoute } = await import('../../src/server/tunnelRoute');
 
 describe('createSentryTunnelRoute', () => {
   afterEach(() => {
-    vi.clearAllMocks();
+    vi.resetAllMocks();
   });
 
   it('returns a server route config with only a POST handler', () => {
@@ -49,10 +49,12 @@ describe('createSentryTunnelRoute', () => {
   });
 
   it('derives the allowed DSN from the active server Sentry client when allowedDsns is omitted', async () => {
-    const request = new Request('http://localhost:3000/monitoring', { method: 'POST', body: 'envelope' });
+    const request = new Request('http://localhost:3000/derive-dsn', { method: 'POST', body: 'envelope' });
     const response = new Response('ok', { status: 200 });
 
-    getClientSpy.mockReturnValueOnce({
+    // `getClient` is called both by the path self-registration and the DSN derivation.
+    getClientSpy.mockReturnValue({
+      getOptions: () => ({}),
       getDsn: () => ({
         protocol: 'http',
         publicKey: 'public',
@@ -77,6 +79,21 @@ describe('createSentryTunnelRoute', () => {
     expect(result).toBe(response);
   });
 
+  it('self-registers the request path so the streamed-span sampler can drop it', async () => {
+    const request = new Request('http://localhost:3000/handler-selfreg', { method: 'POST', body: 'envelope' });
+    const options: { ignoreSpans?: unknown[] } = {};
+    getClientSpy.mockReturnValue({ getOptions: () => options, getDsn: () => undefined });
+    handleTunnelRequestSpy.mockResolvedValueOnce(new Response('ok', { status: 200 }));
+
+    await createSentryTunnelRoute({ allowedDsns: ['https://public@o0.ingest.sentry.io/0'] }).handlers.POST({ request });
+
+    const matcher = options.ignoreSpans?.find(
+      (entry): entry is { attributes: { 'http.target': RegExp } } =>
+        !!(entry as { attributes?: { 'http.target'?: unknown } })?.attributes?.['http.target'],
+    );
+    expect(matcher?.attributes['http.target'].test('/handler-selfreg')).toBe(true);
+  });
+
   it('returns 500 when allowedDsns is omitted and no active server Sentry client DSN exists', async () => {
     const request = new Request('http://localhost:3000/monitoring', { method: 'POST', body: 'envelope' });
 
@@ -90,3 +107,43 @@ describe('createSentryTunnelRoute', () => {
     await expect(result.text()).resolves.toContain('Tunnel route requires Sentry server SDK initialized with a DSN');
   });
 });
+
+describe('registerSentryServerTunnelRoute', () => {
+  afterEach(() => {
+    vi.resetAllMocks();
+  });
+
+  it('adds an http.target ignoreSpans matcher for the tunnel route path so the transaction is dropped at span start', () => {
+    const options: { ignoreSpans?: unknown[] } = { ignoreSpans: [/existing/] };
+    getClientSpy.mockReturnValue({ getOptions: () => options });
+
+    // Unique path per test to avoid the module-level dedupe Set across tests.
+    registerSentryServerTunnelRoute('/abcd1234');
+
+    expect(options.ignoreSpans).toHaveLength(2);
+    const matcher = options.ignoreSpans?.[1] as { attributes: { 'http.target': RegExp } };
+    const pattern = matcher.attributes['http.target'];
+
+    expect(pattern.test('/abcd1234')).toBe(true);
+    expect(pattern.test('/abcd1234?o=1&p=2')).toBe(true);
+    expect(pattern.test('/abcd1234/')).toBe(true);
+    // Must not match an unrelated route that merely shares the prefix.
+    expect(pattern.test('/abcd1234extra')).toBe(false);
+  });
+
+  it('does not register the same tunnel route path twice', () => {
+    const options: { ignoreSpans?: unknown[] } = {};
+    getClientSpy.mockReturnValue({ getOptions: () => options });
+
+    registerSentryServerTunnelRoute('/dedupe-me');
+    registerSentryServerTunnelRoute('/dedupe-me');
+
+    expect(options.ignoreSpans).toHaveLength(1);
+  });
+
+  it('is a no-op when there is no active client', () => {
+    getClientSpy.mockReturnValue(undefined);
+
+    expect(() => registerSentryServerTunnelRoute('/no-client')).not.toThrow();
+  });
+});