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

[onurtemizkan]

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, 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

// entry.server.tsximport*asSentryfrom'@sentry/react-router';exportdefaultSentry.createSentryHandleRequest({/* ... */});exportconsthandleError=Sentry.createSentryHandleError();exportconstunstable_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

// entry.client.tsxconsttracing=Sentry.reactRouterTracingIntegration({useInstrumentationAPI: true});Sentry.init({integrations: [tracing],});<HydratedRouterunstable_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 Observability: Server-side instrumentation 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

[Copilot]

Pull request overview

This PR adds comprehensive support for React Router's instrumentation API, enabling automatic performance monitoring and error tracking for React Router v7.x applications. The implementation provides both server-side and client-side instrumentation that integrates with React Router's unstable_instrumentations API (planned to become stable in v8).

Key Changes:

• Server and client instrumentation API implementations with automatic span creation for loaders, actions, middleware, and lazy routes
• Backward compatibility mechanisms to prevent duplicate instrumentation when using both legacy wrappers and the new API
• Comprehensive E2E test application demonstrating real-world usage

Reviewed changes

Copilot reviewed 55 out of 55 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/react-router/src/server/createServerInstrumentation.ts	New server instrumentation implementation with handler and route hooks
packages/react-router/src/client/createClientInstrumentation.ts	New client instrumentation implementation for router navigation and route handlers
packages/react-router/src/common/utils.ts	Shared utility functions for URL parsing, pattern extraction, and error capture
packages/react-router/src/common/types.ts	TypeScript type definitions for React Router's instrumentation API
packages/react-router/src/server/serverGlobals.ts	Global flag management to detect instrumentation API usage
packages/react-router/src/server/wrapServerLoader.ts	Updated to skip instrumentation when API is active, with deprecation warning
packages/react-router/src/server/wrapServerAction.ts	Updated to skip instrumentation when API is active, with deprecation warning
packages/react-router/src/server/wrapSentryHandleRequest.ts	Enhanced to work alongside instrumentation API, preserving origin attributes
packages/react-router/src/client/tracingIntegration.ts	Extended with lazy-loaded clientInstrumentation getter and options support
packages/react-router/src/client/hydratedRouter.ts	Updated to avoid double-counting navigation when API handles it
packages/react-router/src/server/integration/reactRouterServer.ts	Updated to skip OTEL patching when instrumentation API is used
packages/react-router/src/server/instrumentation/reactRouter.ts	Updated to skip OTEL instrumentation for loaders/actions when API is active
packages/react-router/test/server/createServerInstrumentation.test.ts	Comprehensive unit tests for server instrumentation API
packages/react-router/test/client/createClientInstrumentation.test.ts	Comprehensive unit tests for client instrumentation API
packages/react-router/test/common/utils.test.ts	Unit tests for shared utility functions
dev-packages/e2e-tests/test-applications/react-router-7-framework-instrumentation/*	Complete E2E test application with performance and error tests

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 55 out of 55 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

size-limit report 📦

Path	Size	% Change	Change
@sentry/browser	24.82 kB	-	-
@sentry/browser - with treeshaking flags	23.32 kB	-	-
@sentry/browser (incl. Tracing)	41.6 kB	-	-
@sentry/browser (incl. Tracing, Profiling)	46.19 kB	-	-
@sentry/browser (incl. Tracing, Replay)	80.17 kB	-	-
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags	69.91 kB	-	-
@sentry/browser (incl. Tracing, Replay with Canvas)	84.85 kB	-	-
@sentry/browser (incl. Tracing, Replay, Feedback)	97.1 kB	-	-
@sentry/browser (incl. Feedback)	41.54 kB	-	-
@sentry/browser (incl. sendFeedback)	29.51 kB	-	-
@sentry/browser (incl. FeedbackAsync)	34.5 kB	-	-
@sentry/browser (incl. Metrics)	25.85 kB	-	-
@sentry/browser (incl. Logs)	26.07 kB	-	-
@sentry/browser (incl. Metrics & Logs)	26.73 kB	-	-
@sentry/react	26.54 kB	-	-
@sentry/react (incl. Tracing)	43.79 kB	-	-
@sentry/vue	29.29 kB	-	-
@sentry/vue (incl. Tracing)	43.41 kB	-	-
@sentry/svelte	24.84 kB	-	-
CDN Bundle	27.25 kB	-	-
CDN Bundle (incl. Tracing)	42.24 kB	-	-
CDN Bundle (incl. Tracing, Replay)	78.96 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback)	84.41 kB	-	-
CDN Bundle - uncompressed	80.06 kB	-	-
CDN Bundle (incl. Tracing) - uncompressed	125.49 kB	-	-
CDN Bundle (incl. Tracing, Replay) - uncompressed	242.03 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed	254.79 kB	-	-
@sentry/nextjs (client)	46.02 kB	-	-
@sentry/sveltekit (client)	41.97 kB	-	-
@sentry/node-core	51.62 kB	+0.01%	+1 B 🔺
@sentry/node	161.52 kB	-	-
@sentry/node - without tracing	93.05 kB	-	-
@sentry/aws-serverless	108.57 kB	+0.01%	+1 B 🔺

View base workflow run

[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,365	-	11,145	-16%
GET With Sentry	1,803	19%	1,889	-5%
GET With Sentry (error only)	6,067	65%	7,659	-21%
POST Baseline	1,198	-	1,171	+2%
POST With Sentry	603	50%	582	+4%
POST With Sentry (error only)	1,053	88%	1,039	+1%
MYSQL Baseline	3,320	-	4,024	-17%
MYSQL With Sentry	507	15%	600	-16%
MYSQL With Sentry (error only)	2,712	82%	3,153	-14%

View base workflow run