feat(tanstackstart-react): Add wrappers for manual instrumentation of servers-side middlewares

[nicohrubec]

This PR adds a middleware wrapper to the tanstackstart SDK that allows users to add tracing to their application middleware. Eventually we will want to patch this automatically, but that is a bit tricky since it requires build-time magic. This API provides a manual alternative for now and can later still act as a fallback for cases where auto-instrumentation doesn't work.

How it works
The wrapper patches the middleware options.server function that gets executed whenever a middleware is run. Each middleware invocation creates a span with:

• op: middleware.tanstackstart
• origin: manual.middleware.tanstackstart
• name: The instrumentation automatically assigns the middleware name based on the variable name assigned to the middleware.

At first I had the issue that if multiple middlewares were used they would be nested (i.e. first middleware is parent of second etc.). This is because the middlewares call next() to move down the middleware chain, so trivially starting a span for the middleware execution would actually create a span that would last for the current middleware and any middlewares that come after in the middleware chain. I fixed that by also proxying next(), where I end the middleware span and then also reattach the middleware spans to the parent request span instead of the previous middleware span.

Usage

import { wrapMiddlewaresWithSentry } from '@sentry/tanstackstart-react';

  const [wrappedAuth, wrappedLogging] = wrapMiddlewaresWithSentry({
    authMiddleware,
    loggingMiddleware,
  });

Tests

Added E2E tests for:

• if multiple middlewares are executed we get spans for both and they are sibling spans (i.e. children of the same parent)
• global request middleware
• global function middleware
• request middleware

Screenshots from sample app

Using two global request middlewares:

Closes #18666

[cursor]

Span never ends when middleware throws or skips next()

The span created by startSpanManual is only ended inside getNextProxy when next() is called. If the middleware throws an error (e.g., authentication failure) or returns early without calling next(), the span will never be ended. This causes orphaned spans and potential memory leaks. The trpcMiddleware implementation demonstrates the correct pattern: wrapping the middleware execution in a try-catch and calling span.end() in both success and error paths. Additionally, per the review rules, captureException with a proper mechanism should be called when an error occurs.

 

[s1gr1d]

This could be a legit problem. Maybe you can test throwing an error in the middleware to make sure nothing unexpected happens here.

[github-actions]

node-overhead report 🧳

Note: This is a synthetic benchmark with a minimal express app and does not necessarily reflect the real-world performance impact in an application.

Scenario	Requests/s	% of Baseline	Prev. Requests/s	Change %
GET Baseline	9,033	-	8,987	+1%
GET With Sentry	1,769	20%	1,675	+6%
GET With Sentry (error only)	6,111	68%	6,171	-1%
POST Baseline	1,191	-	1,207	-1%
POST With Sentry	595	50%	576	+3%
POST With Sentry (error only)	1,064	89%	1,036	+3%
MYSQL Baseline	3,264	-	3,299	-1%
MYSQL With Sentry	485	15%	423	+15%
MYSQL With Sentry (error only)	2,663	82%	2,700	-1%

View base workflow run

[s1gr1d]

This could be a legit problem. Maybe you can test throwing an error in the middleware to make sure nothing unexpected happens here.

[sentry]

Bug: Middleware spans are not closed if next() is not called or an error occurs, leading to a memory leak.
_{Severity: CRITICAL}

🔍 Detailed Analysis

The middleware instrumentation uses startSpanManual to create a span, but this span is only ended when the middleware's next() function is invoked. If a middleware short-circuits the request (a valid pattern for authentication or validation) or throws an error before calling next(), the span is never closed. This leads to an accumulation of unclosed spans in memory, causing a memory leak and performance degradation over time, as well as incomplete tracing data.

💡 Suggested Fix

Wrap the middleware execution logic within a try...finally block. The call to span.end() should be placed in the finally block to ensure that the span is always closed, regardless of whether the middleware completes successfully, throws an error, or short-circuits by not calling next().

🤖 Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: packages/tanstackstart-react/src/server/middleware.ts#L47-L56

Potential issue: The middleware instrumentation uses `startSpanManual` to create a span,
but this span is only ended when the middleware's `next()` function is invoked. If a
middleware short-circuits the request (a valid pattern for authentication or validation)
or throws an error before calling `next()`, the span is never closed. This leads to an
accumulation of unclosed spans in memory, causing a memory leak and performance
degradation over time, as well as incomplete tracing data.

_{Did we get this right? 👍 / 👎 to inform future reviews.
Reference ID: 8404895}