feat(react-router): Add support for React Router instrumentation API (#18580)

Adds support for React Router's `unstable_instrumentations` API for
automatic performance monitoring.

Resolves: #18127
Resolves: #18121
Ref: remix-run/react-router#13749
Ref: remix-run/react-router#14412

React Router 7.9.5 introduced the [`unstable_instrumentations`
API](https://reactrouter.com/how-to/instrumentation), which provides
hooks for instrumenting request handlers, loaders, actions, middleware,
and lazy routes. This enables automatic span creation without requiring
manual wrapper functions.

### Server-side

Added `createSentryServerInstrumentation()`:

- `handler.request` - Creates root HTTP server span with parameterized
route names
- `route.loader` - Automatic loader span creation
- `route.action` - Automatic action span creation
- `route.middleware` - Automatic middleware span creation
- `route.lazy` - Lazy route loading spans

```typescript
// entry.server.tsx
import * as Sentry from '@sentry/react-router';

export default Sentry.createSentryHandleRequest({ /* ... */ });
export const handleError = Sentry.createSentryHandleError();
export const unstable_instrumentations = [Sentry.createSentryServerInstrumentation()];
```

### Client-side

Added client instrumentation via `reactRouterTracingIntegration({
useInstrumentationAPI: true })`:

- `router.navigate` - Navigation transaction creation
- `router.fetch` - Fetcher span creation
- `route.loader/action/middleware/lazy` - Client-side route handler
spans

```typescript
// entry.client.tsx
const tracing = Sentry.reactRouterTracingIntegration({ useInstrumentationAPI: true });

Sentry.init({
  integrations: [tracing],
});

<HydratedRouter unstable_instrumentations={[tracing.clientInstrumentation]} />
```

### Backward compatibility

When the instrumentation API is used:
- `wrapServerLoader` and `wrapServerAction` skip creating spans and emit
a warning in debug mode
- Legacy navigation patching in `instrumentHydratedRouter` checks if
instrumentation API handled it
- Server-side OTEL instrumentation for loaders/actions is skipped

### Also:
- Created `serverGlobals.ts` to isolate flag handling (avoids pulling
OpenTelemetry deps in Cloudflare builds)
- Updated `wrapSentryHandleRequest` to explicitly set parameterized
transaction names (improves Hydrogen parameterization)
- Added E2E test application `react-router-7-framework-instrumentation`


### Notes
- Client-side limitation: As of React Router 7.x, HydratedRouter does
not invoke client instrumentation hooks in Framework Mode. Client-side
navigation is handled by existing instrumentHydratedRouter(). The client
instrumentation is prepared for when React Router adds support. See
remix-run/react-router#13749.
- Lazy routes limitation: In Framework Mode, `route.lazy` hooks are not
triggered because the bundler handles code-splitting.

_Needs docs PR_

---------

Co-authored-by: Charly Gomez <charly.gomez@sentry.io>

Author: onurtemizkan

dev-packages/e2e-tests/test-applications/hydrogen-react-router-7/tests/server-transactions.test.ts

@@ -13,7 +13,8 @@ test('Sends parameterized transaction name to Sentry', async ({ page }) => {
   const transaction = await transactionPromise;
 
   expect(transaction).toBeDefined();
-  expect(transaction.transaction).toBe('GET /user/123');
+  // Transaction name should be parameterized (route pattern, not actual URL)
+  expect(transaction.transaction).toBe('GET /user/:id');
 });
 
 test('Sends two linked transactions (server & client) to Sentry', async ({ page }) => {

dev-packages/e2e-tests/test-applications/react-router-7-framework-instrumentation/.gitignore

@@ -0,0 +1,32 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+/test-results/
+/playwright-report/
+/playwright/.cache/
+
+!*.d.ts
+
+# react router
+.react-router

dev-packages/e2e-tests/test-applications/react-router-7-framework-instrumentation/.npmrc

@@ -0,0 +1,2 @@
+@sentry:registry=http://127.0.0.1:4873
+@sentry-internal:registry=http://127.0.0.1:4873

dev-packages/e2e-tests/test-applications/react-router-7-framework-instrumentation/app/app.css

@@ -0,0 +1,5 @@
+body {
+  font-family: system-ui, sans-serif;
+  margin: 0;
+  padding: 20px;
+}

dev-packages/e2e-tests/test-applications/react-router-7-framework-instrumentation/app/entry.client.tsx

@@ -0,0 +1,33 @@
+import * as Sentry from '@sentry/react-router';
+import { StrictMode, startTransition } from 'react';
+import { hydrateRoot } from 'react-dom/client';
+import { HydratedRouter } from 'react-router/dom';
+
+// Create the tracing integration with useInstrumentationAPI enabled
+// This must be set BEFORE Sentry.init() to prepare the instrumentation
+const tracing = Sentry.reactRouterTracingIntegration({ useInstrumentationAPI: true });
+
+Sentry.init({
+  environment: 'qa', // dynamic sampling bias to keep transactions
+  dsn: 'https://username@domain/123',
+  tunnel: `http://localhost:3031/`, // proxy server
+  integrations: [tracing],
+  tracesSampleRate: 1.0,
+  tracePropagationTargets: [/^\//],
+});
+
+// Get the client instrumentation from the Sentry integration
+// NOTE: As of React Router 7.x, HydratedRouter does NOT invoke these hooks in Framework Mode.
+// The client-side instrumentation is prepared for when React Router adds support.
+// Client-side navigation is currently handled by the legacy instrumentHydratedRouter() approach.
+const sentryClientInstrumentation = [tracing.clientInstrumentation];
+
+startTransition(() => {
+  hydrateRoot(
+    document,
+    <StrictMode>
+      {/* unstable_instrumentations is React Router 7.x's prop name (will become `instrumentations` in v8) */}
+      <HydratedRouter unstable_instrumentations={sentryClientInstrumentation} />
+    </StrictMode>,
+  );
+});

dev-packages/e2e-tests/test-applications/react-router-7-framework-instrumentation/app/entry.server.tsx

@@ -0,0 +1,22 @@
+import { createReadableStreamFromReadable } from '@react-router/node';
+import * as Sentry from '@sentry/react-router';
+import { renderToPipeableStream } from 'react-dom/server';
+import { ServerRouter } from 'react-router';
+import { type HandleErrorFunction } from 'react-router';
+
+const ABORT_DELAY = 5_000;
+
+const handleRequest = Sentry.createSentryHandleRequest({
+  streamTimeout: ABORT_DELAY,
+  ServerRouter,
+  renderToPipeableStream,
+  createReadableStreamFromReadable,
+});
+
+export default handleRequest;
+
+export const handleError: HandleErrorFunction = Sentry.createSentryHandleError({ logErrors: true });
+
+// Use Sentry's instrumentation API for server-side tracing
+// `unstable_instrumentations` is React Router 7.x's export name (will become `instrumentations` in v8)
+export const unstable_instrumentations = [Sentry.createSentryServerInstrumentation()];

dev-packages/e2e-tests/test-applications/react-router-7-framework-instrumentation/app/root.tsx

@@ -0,0 +1,69 @@
+import * as Sentry from '@sentry/react-router';
+import { Links, Meta, Outlet, Scripts, ScrollRestoration, isRouteErrorResponse } from 'react-router';
+import type { Route } from './+types/root';
+import stylesheet from './app.css?url';
+
+export const links: Route.LinksFunction = () => [
+  { rel: 'preconnect', href: 'https://fonts.googleapis.com' },
+  {
+    rel: 'preconnect',
+    href: 'https://fonts.gstatic.com',
+    crossOrigin: 'anonymous',
+  },
+  {
+    rel: 'stylesheet',
+    href: 'https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap',
+  },
+  { rel: 'stylesheet', href: stylesheet },
+];
+
+export function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        {children}
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+
+export default function App() {
+  return <Outlet />;
+}
+
+export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
+  let message = 'Oops!';
+  let details = 'An unexpected error occurred.';
+  let stack: string | undefined;
+
+  if (isRouteErrorResponse(error)) {
+    message = error.status === 404 ? '404' : 'Error';
+    details = error.status === 404 ? 'The requested page could not be found.' : error.statusText || details;
+  } else if (error && error instanceof Error) {
+    Sentry.captureException(error);
+    if (import.meta.env.DEV) {
+      details = error.message;
+      stack = error.stack;
+    }
+  }
+
+  return (
+    <main className="pt-16 p-4 container mx-auto">
+      <h1>{message}</h1>
+      <p>{details}</p>
+      {stack && (
+        <pre className="w-full p-4 overflow-x-auto">
+          <code>{stack}</code>
+        </pre>
+      )}
+    </main>
+  );
+}

dev-packages/e2e-tests/test-applications/react-router-7-framework-instrumentation/app/routes.ts

@@ -0,0 +1,19 @@
+import { type RouteConfig, index, prefix, route } from '@react-router/dev/routes';
+
+export default [
+  index('routes/home.tsx'),
+  ...prefix('performance', [
+    index('routes/performance/index.tsx'),
+    route('ssr', 'routes/performance/ssr.tsx'),
+    route('with/:param', 'routes/performance/dynamic-param.tsx'),
+    route('static', 'routes/performance/static.tsx'),
+    route('server-loader', 'routes/performance/server-loader.tsx'),
+    route('server-action', 'routes/performance/server-action.tsx'),
+    route('with-middleware', 'routes/performance/with-middleware.tsx'),
+    route('error-loader', 'routes/performance/error-loader.tsx'),
+    route('error-action', 'routes/performance/error-action.tsx'),
+    route('error-middleware', 'routes/performance/error-middleware.tsx'),
+    route('lazy-route', 'routes/performance/lazy-route.tsx'),
+    route('fetcher-test', 'routes/performance/fetcher-test.tsx'),
+  ]),
+] satisfies RouteConfig;

dev-packages/e2e-tests/test-applications/react-router-7-framework-instrumentation/app/routes/home.tsx

@@ -0,0 +1,10 @@
+export function meta() {
+  return [
+    { title: 'React Router Instrumentation API Test' },
+    { name: 'description', content: 'Testing React Router instrumentation API' },
+  ];
+}
+
+export default function Home() {
+  return <div>home</div>;
+}

dev-packages/e2e-tests/test-applications/react-router-7-framework-instrumentation/app/routes/performance/dynamic-param.tsx

@@ -0,0 +1,15 @@
+import type { Route } from './+types/dynamic-param';
+
+// Minimal loader to trigger Sentry's route instrumentation
+export function loader() {
+  return null;
+}
+
+export default function DynamicParamPage({ params }: Route.ComponentProps) {
+  return (
+    <div>
+      <h1>Dynamic Param Page</h1>
+      <div>Param: {params.param}</div>
+    </div>
+  );
+}