feat(react-router): Add client-side router instrumentation

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

@@ -8,7 +8,7 @@ Sentry.init({
  // todo: get this from env
  dsn: 'https://username@domain/123',
  tunnel: `http://localhost:3031/`, // proxy server
- integrations: [Sentry.browserTracingIntegration()],
+ integrations: [Sentry.reactRouterTracingIntegration()],
  tracesSampleRate: 1.0,
  tracePropagationTargets: [/^\//],
 });

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

@@ -12,6 +12,7 @@ export default [
  ]),
  ...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'),
  ]),

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

@@ -1,3 +1,13 @@
+import { Link } from 'react-router';
+
 export default function PerformancePage() {
- return <h1>Performance Page</h1>;
+ return (
+ <div>
+ <h1>Performance Page</h1>
+ <nav>
+ <Link to="/performance/ssr">SSR Page</Link>
+ <Link to="/performance/with/sentry">With Param Page</Link>
+ </nav>
+ </div>
+ );
 }

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

@@ -0,0 +1,7 @@
+export default function SsrPage() {
+ return (
+ <div>
+ <h1>SSR Page</h1>
+ </div>
+ );
+}

dev-packages/e2e-tests/test-applications/react-router-7-framework/tests/performance/navigation.client.test.ts

@@ -0,0 +1,107 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+import { APP_NAME } from '../constants';
+
+test.describe('client - navigation performance', () => {
+ test('should create navigation transaction', async ({ page }) => {
+ const navigationPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/ssr';
+ });
+
+ await page.goto(`/performance`); // pageload
+ await page.waitForTimeout(1000); // give it a sec before navigation
+ await page.getByRole('link', { name: 'SSR Page' }).click(); // navigation
+
+ const transaction = await navigationPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.navigation.react-router',
+ 'sentry.op': 'navigation',
+ 'sentry.source': 'url',
+ },
+ op: 'navigation',
+ origin: 'auto.navigation.react-router',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/ssr',
+ type: 'transaction',
+ transaction_info: { source: 'url' },
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/ssr'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+
+ test('should update navigation transaction for dynamic routes', async ({ page }) => {
+ const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/with/:param';
+ });
+
+ await page.goto(`/performance`); // pageload
+ await page.waitForTimeout(1000); // give it a sec before navigation
+ await page.getByRole('link', { name: 'With Param Page' }).click(); // navigation
+
+ const transaction = await txPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.navigation.react-router',
+ 'sentry.op': 'navigation',
+ 'sentry.source': 'route',
+ },
+ op: 'navigation',
+ origin: 'auto.navigation.react-router',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/with/:param',
+ type: 'transaction',
+ transaction_info: { source: 'route' },
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/with/sentry'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+});

dev-packages/e2e-tests/test-applications/react-router-7-framework/tests/performance/pageload.client.test.ts

@@ -53,6 +53,56 @@ test.describe('client - pageload performance', () => {
  });
  });
 
+ test('should update pageload transaction for dynamic routes', async ({ page }) => {
+ const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/with/:param';
+ });
+
+ await page.goto(`/performance/with/sentry`);
+
+ const transaction = await txPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.pageload.browser',
+ 'sentry.op': 'pageload',
+ 'sentry.source': 'route',
+ },
+ op: 'pageload',
+ origin: 'auto.pageload.browser',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/with/:param',
+ type: 'transaction',
+ transaction_info: { source: 'route' },
+ measurements: expect.any(Object),
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/with/sentry'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+
  // todo: this page is currently not prerendered (see react-router.config.ts)
  test('should send pageload transaction for prerendered pages', async ({ page }) => {
  const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {

packages/react-router/src/client/hydratedRouter.ts

@@ -0,0 +1,147 @@
+import { startBrowserTracingNavigationSpan } from '@sentry/browser';
+import type { Span } from '@sentry/core';
+import {
+ consoleSandbox,
+ getActiveSpan,
+ getClient,
+ getRootSpan,
+ GLOBAL_OBJ,
+ SEMANTIC_ATTRIBUTE_SENTRY_OP,
+ SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+ SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
+ spanToJSON,
+} from '@sentry/core';
+import type { DataRouter, RouterState } from 'react-router';
+import { DEBUG_BUILD } from '../common/debug-build';
+
+const GLOBAL_OBJ_WITH_DATA_ROUTER = GLOBAL_OBJ as typeof GLOBAL_OBJ & {
+ __reactRouterDataRouter?: DataRouter;
+};
+
+const MAX_RETRIES = 40; // 2 seconds at 50ms interval
+
+/**
+ * Instruments the React Router Data Router for pageloads and navigation.
+ *
+ * This function waits for the router to be available after hydration, then:
+ * 1. Updates the pageload transaction with parameterized route info
+ * 2. Patches router.navigate() to create navigation transactions
+ * 3. Subscribes to router state changes to update navigation transactions with parameterized routes
+ */
+export function instrumentHydratedRouter(): void {
+ function trySubscribe(): boolean {
+ const router = GLOBAL_OBJ_WITH_DATA_ROUTER.__reactRouterDataRouter;
+
+ if (router) {
+ // The first time we hit the router, we try to update the pageload transaction
+ // todo: update pageload tx here
+ const pageloadSpan = getActiveRootSpan();
+ const pageloadName = pageloadSpan ? spanToJSON(pageloadSpan).description : undefined;
+ const parameterizePageloadRoute = getParameterizedRoute(router.state);
+ if (
+ pageloadName &&
+ normalizePathname(router.state.location.pathname) === normalizePathname(pageloadName) && // this event is for the currently active pageload
+ normalizePathname(parameterizePageloadRoute) !== normalizePathname(pageloadName) // route is not parameterized yet
+ ) {
+ pageloadSpan?.updateName(parameterizePageloadRoute);
+ pageloadSpan?.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+ }
+
+ // Patching navigate for creating accurate navigation transactions
+ if (typeof router.navigate === 'function') {
+ const originalNav = router.navigate.bind(router);
+ router.navigate = function sentryPatchedNavigate(...args) {
+ maybeCreateNavigationTransaction(
+ String(args[0]) || '<unknown route>', // will be updated anyway
+ 'url', // this also will be updated once we have the parameterized route
+ );
+ return originalNav(...args);
+ };
+ }
+
+ // Subscribe to router state changes to update navigation transactions with parameterized routes
+ router.subscribe(newState => {
+ const navigationSpan = getActiveRootSpan();
+ const navigationSpanName = navigationSpan ? spanToJSON(navigationSpan).description : undefined;
+ const parameterizedNavRoute = getParameterizedRoute(newState);
+
+ if (
+ navigationSpanName && // we have an active pageload tx
+ newState.navigation.state === 'idle' && // navigation has completed
+ normalizePathname(newState.location.pathname) === normalizePathname(navigationSpanName) && // this event is for the currently active navigation
+ normalizePathname(parameterizedNavRoute) !== normalizePathname(navigationSpanName) // route is not parameterized yet
+ ) {
+ navigationSpan?.updateName(parameterizedNavRoute);
+ navigationSpan?.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+ }
+ });
+ return true;
+ }
+ return false;
+ }
+
+ // Wait until the router is available (since the SDK loads before hydration)
+ if (!trySubscribe()) {
+ let retryCount = 0;
+ // Retry until the router is available or max retries reached
+ const interval = setInterval(() => {
+ if (trySubscribe() || retryCount >= MAX_RETRIES) {
+ if (retryCount >= MAX_RETRIES) {
+ DEBUG_BUILD &&
+ consoleSandbox(() => {
+ // eslint-disable-next-line no-console
+ console.warn('Unable to instrument React Router: router not found after hydration.');
+ });
+ }
+ clearInterval(interval);
+ }
+ retryCount++;
+ }, 50);
+ }
+}
+
+function maybeCreateNavigationTransaction(name: string, source: 'url' | 'route'): Span | undefined {
+ const client = getClient();
+
+ if (!client) {
+ return undefined;
+ }
+
+ return startBrowserTracingNavigationSpan(client, {
+ name,
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: source,
+ [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'navigation',
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.navigation.react-router',
+ },
+ });
+}
+
+function getActiveRootSpan(): Span | undefined {
+ const activeSpan = getActiveSpan();
+ if (!activeSpan) {
+ return undefined;
+ }
+
+ const rootSpan = getRootSpan(activeSpan);
+
+ const op = spanToJSON(rootSpan).op;
+
+ // Only use this root span if it is a pageload or navigation span
+ return op === 'navigation' || op === 'pageload' ? rootSpan : undefined;
+}
+
+function getParameterizedRoute(routerState: RouterState): string {
+ const lastMatch = routerState.matches[routerState.matches.length - 1];
+ return normalizePathname(lastMatch?.route.path ?? routerState.location.pathname);
+}
+
+function normalizePathname(pathname: string): string {
+ // Ensure it starts with a single slash
+ let normalized = pathname.startsWith('/') ? pathname : `/${pathname}`;
+ // Remove trailing slash unless it's the root
+ if (normalized.length > 1 && normalized.endsWith('/')) {
+ normalized = normalized.slice(0, -1);
+ }
+ return normalized;
+}

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

@@ -1,3 +1,4 @@
 export * from '@sentry/browser';
 
 export { init } from './sdk';
+export { reactRouterTracingIntegration } from './tracingIntegration';

packages/react-router/src/client/sdk.ts

@@ -1,19 +1,33 @@
 import type { BrowserOptions } from '@sentry/browser';
 import { init as browserInit } from '@sentry/browser';
 import type { Client } from '@sentry/core';
-import { applySdkMetadata, setTag } from '@sentry/core';
+import { applySdkMetadata, consoleSandbox, setTag } from '@sentry/core';
+
+const BROWSER_TRACING_INTEGRATION_ID = 'BrowserTracing';
 
 /**
  * Initializes the client side of the React Router SDK.
  */
 export function init(options: BrowserOptions): Client | undefined {
- const opts = {
- ...options,
- };
+ // If BrowserTracing integration was passed to options, emit a warning
+ if (options.integrations && Array.isArray(options.integrations)) {
+ const hasBrowserTracing = options.integrations.some(
+ integration => integration.name === BROWSER_TRACING_INTEGRATION_ID,
+ );
+
+ if (hasBrowserTracing) {
+ consoleSandbox(() => {
+ // eslint-disable-next-line no-console
+ console.warn(
+ 'browserTracingIntegration is not fully compatible with @sentry/react-router. Please use reactRouterTracingIntegration instead.',
+ );
+ });
+ }
+ }
 
- applySdkMetadata(opts, 'react-router', ['react-router', 'browser']);
+ applySdkMetadata(options, 'react-router', ['react-router', 'browser']);
 
- const client = browserInit(opts);
+ const client = browserInit(options);
 
  setTag('runtime', 'browser');
 

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

@@ -8,7 +8,7 @@ Sentry.init({
  // todo: get this from env
  dsn: 'https://username@domain/123',
  tunnel: `http://localhost:3031/`, // proxy server
- integrations: [Sentry.browserTracingIntegration()],
+ integrations: [Sentry.reactRouterTracingIntegration()],
  tracesSampleRate: 1.0,
  tracePropagationTargets: [/^\//],
 });

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

@@ -12,6 +12,7 @@ export default [
  ]),
  ...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'),
  ]),

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

@@ -1,3 +1,13 @@
+import { Link } from 'react-router';
+
 export default function PerformancePage() {
- return <h1>Performance Page</h1>;
+ return (
+ <div>
+ <h1>Performance Page</h1>
+ <nav>
+ <Link to="/performance/ssr">SSR Page</Link>
+ <Link to="/performance/with/sentry">With Param Page</Link>
+ </nav>
+ </div>
+ );
 }

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

@@ -0,0 +1,7 @@
+export default function SsrPage() {
+ return (
+ <div>
+ <h1>SSR Page</h1>
+ </div>
+ );
+}

dev-packages/e2e-tests/test-applications/react-router-7-framework/tests/performance/navigation.client.test.ts

@@ -0,0 +1,107 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+import { APP_NAME } from '../constants';
+
+test.describe('client - navigation performance', () => {
+ test('should create navigation transaction', async ({ page }) => {
+ const navigationPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/ssr';
+ });
+
+ await page.goto(`/performance`); // pageload
+ await page.waitForTimeout(1000); // give it a sec before navigation
+ await page.getByRole('link', { name: 'SSR Page' }).click(); // navigation
+
+ const transaction = await navigationPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.navigation.react-router',
+ 'sentry.op': 'navigation',
+ 'sentry.source': 'url',
+ },
+ op: 'navigation',
+ origin: 'auto.navigation.react-router',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/ssr',
+ type: 'transaction',
+ transaction_info: { source: 'url' },
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/ssr'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+
+ test('should update navigation transaction for dynamic routes', async ({ page }) => {
+ const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/with/:param';
+ });
+
+ await page.goto(`/performance`); // pageload
+ await page.waitForTimeout(1000); // give it a sec before navigation
+ await page.getByRole('link', { name: 'With Param Page' }).click(); // navigation
+
+ const transaction = await txPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.navigation.react-router',
+ 'sentry.op': 'navigation',
+ 'sentry.source': 'route',
+ },
+ op: 'navigation',
+ origin: 'auto.navigation.react-router',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/with/:param',
+ type: 'transaction',
+ transaction_info: { source: 'route' },
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/with/sentry'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+});

dev-packages/e2e-tests/test-applications/react-router-7-framework/tests/performance/pageload.client.test.ts

@@ -53,6 +53,56 @@ test.describe('client - pageload performance', () => {
  });
  });
 
+ test('should update pageload transaction for dynamic routes', async ({ page }) => {
+ const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/with/:param';
+ });
+
+ await page.goto(`/performance/with/sentry`);
+
+ const transaction = await txPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.pageload.browser',
+ 'sentry.op': 'pageload',
+ 'sentry.source': 'route',
+ },
+ op: 'pageload',
+ origin: 'auto.pageload.browser',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/with/:param',
+ type: 'transaction',
+ transaction_info: { source: 'route' },
+ measurements: expect.any(Object),
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/with/sentry'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+
  // todo: this page is currently not prerendered (see react-router.config.ts)
  test('should send pageload transaction for prerendered pages', async ({ page }) => {
  const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {

packages/react-router/src/client/hydratedRouter.ts

@@ -0,0 +1,147 @@
+import { startBrowserTracingNavigationSpan } from '@sentry/browser';
+import type { Span } from '@sentry/core';
+import {
+ consoleSandbox,
+ getActiveSpan,
+ getClient,
+ getRootSpan,
+ GLOBAL_OBJ,
+ SEMANTIC_ATTRIBUTE_SENTRY_OP,
+ SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+ SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
+ spanToJSON,
+} from '@sentry/core';
+import type { DataRouter, RouterState } from 'react-router';
+import { DEBUG_BUILD } from '../common/debug-build';
+
+const GLOBAL_OBJ_WITH_DATA_ROUTER = GLOBAL_OBJ as typeof GLOBAL_OBJ & {
+ __reactRouterDataRouter?: DataRouter;
+};
+
+const MAX_RETRIES = 40; // 2 seconds at 50ms interval
+
+/**
+ * Instruments the React Router Data Router for pageloads and navigation.
+ *
+ * This function waits for the router to be available after hydration, then:
+ * 1. Updates the pageload transaction with parameterized route info
+ * 2. Patches router.navigate() to create navigation transactions
+ * 3. Subscribes to router state changes to update navigation transactions with parameterized routes
+ */
+export function instrumentHydratedRouter(): void {
+ function trySubscribe(): boolean {
+ const router = GLOBAL_OBJ_WITH_DATA_ROUTER.__reactRouterDataRouter;
+
+ if (router) {
+ // The first time we hit the router, we try to update the pageload transaction
+ // todo: update pageload tx here
+ const pageloadSpan = getActiveRootSpan();
+ const pageloadName = pageloadSpan ? spanToJSON(pageloadSpan).description : undefined;
+ const parameterizePageloadRoute = getParameterizedRoute(router.state);
+ if (
+ pageloadName &&
+ normalizePathname(router.state.location.pathname) === normalizePathname(pageloadName) && // this event is for the currently active pageload
+ normalizePathname(parameterizePageloadRoute) !== normalizePathname(pageloadName) // route is not parameterized yet
+ ) {
+ pageloadSpan?.updateName(parameterizePageloadRoute);
+ pageloadSpan?.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+ }
+
+ // Patching navigate for creating accurate navigation transactions
+ if (typeof router.navigate === 'function') {
+ const originalNav = router.navigate.bind(router);
+ router.navigate = function sentryPatchedNavigate(...args) {
+ maybeCreateNavigationTransaction(
+ String(args[0]) || '<unknown route>', // will be updated anyway
+ 'url', // this also will be updated once we have the parameterized route
+ );
+ return originalNav(...args);
+ };
+ }
+
+ // Subscribe to router state changes to update navigation transactions with parameterized routes
+ router.subscribe(newState => {
+ const navigationSpan = getActiveRootSpan();
+ const navigationSpanName = navigationSpan ? spanToJSON(navigationSpan).description : undefined;
+ const parameterizedNavRoute = getParameterizedRoute(newState);
+
+ if (
+ navigationSpanName && // we have an active pageload tx
+ newState.navigation.state === 'idle' && // navigation has completed
+ normalizePathname(newState.location.pathname) === normalizePathname(navigationSpanName) && // this event is for the currently active navigation
+ normalizePathname(parameterizedNavRoute) !== normalizePathname(navigationSpanName) // route is not parameterized yet
+ ) {
+ navigationSpan?.updateName(parameterizedNavRoute);
+ navigationSpan?.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+ }
+ });
+ return true;
+ }
+ return false;
+ }
+
+ // Wait until the router is available (since the SDK loads before hydration)
+ if (!trySubscribe()) {
+ let retryCount = 0;
+ // Retry until the router is available or max retries reached
+ const interval = setInterval(() => {
+ if (trySubscribe() || retryCount >= MAX_RETRIES) {
+ if (retryCount >= MAX_RETRIES) {
+ DEBUG_BUILD &&
+ consoleSandbox(() => {
+ // eslint-disable-next-line no-console
+ console.warn('Unable to instrument React Router: router not found after hydration.');
+ });
+ }
+ clearInterval(interval);
+ }
+ retryCount++;
+ }, 50);
+ }
+}
+
+function maybeCreateNavigationTransaction(name: string, source: 'url' | 'route'): Span | undefined {
+ const client = getClient();
+
+ if (!client) {
+ return undefined;
+ }
+
+ return startBrowserTracingNavigationSpan(client, {
+ name,
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: source,
+ [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'navigation',
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.navigation.react-router',
+ },
+ });
+}
+
+function getActiveRootSpan(): Span | undefined {
+ const activeSpan = getActiveSpan();
+ if (!activeSpan) {
+ return undefined;
+ }
+
+ const rootSpan = getRootSpan(activeSpan);
+
+ const op = spanToJSON(rootSpan).op;
+
+ // Only use this root span if it is a pageload or navigation span
+ return op === 'navigation' || op === 'pageload' ? rootSpan : undefined;
+}
+
+function getParameterizedRoute(routerState: RouterState): string {
+ const lastMatch = routerState.matches[routerState.matches.length - 1];
+ return normalizePathname(lastMatch?.route.path ?? routerState.location.pathname);
+}
+
+function normalizePathname(pathname: string): string {
+ // Ensure it starts with a single slash
+ let normalized = pathname.startsWith('/') ? pathname : `/${pathname}`;
+ // Remove trailing slash unless it's the root
+ if (normalized.length > 1 && normalized.endsWith('/')) {
+ normalized = normalized.slice(0, -1);
+ }
+ return normalized;
+}

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

@@ -1,3 +1,4 @@
 export * from '@sentry/browser';
 
 export { init } from './sdk';
+export { reactRouterTracingIntegration } from './tracingIntegration';

packages/react-router/src/client/sdk.ts

@@ -1,19 +1,33 @@
 import type { BrowserOptions } from '@sentry/browser';
 import { init as browserInit } from '@sentry/browser';
 import type { Client } from '@sentry/core';
-import { applySdkMetadata, setTag } from '@sentry/core';
+import { applySdkMetadata, consoleSandbox, setTag } from '@sentry/core';
+
+const BROWSER_TRACING_INTEGRATION_ID = 'BrowserTracing';
 
 /**
  * Initializes the client side of the React Router SDK.
  */
 export function init(options: BrowserOptions): Client | undefined {
- const opts = {
- ...options,
- };
+ // If BrowserTracing integration was passed to options, emit a warning
+ if (options.integrations && Array.isArray(options.integrations)) {
+ const hasBrowserTracing = options.integrations.some(
+ integration => integration.name === BROWSER_TRACING_INTEGRATION_ID,
+ );
+
+ if (hasBrowserTracing) {
+ consoleSandbox(() => {
+ // eslint-disable-next-line no-console
+ console.warn(
+ 'browserTracingIntegration is not fully compatible with @sentry/react-router. Please use reactRouterTracingIntegration instead.',
+ );
+ });
+ }
+ }
 
- applySdkMetadata(opts, 'react-router', ['react-router', 'browser']);
+ applySdkMetadata(options, 'react-router', ['react-router', 'browser']);
 
- const client = browserInit(opts);
+ const client = browserInit(options);
 
  setTag('runtime', 'browser');
 

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

@@ -8,7 +8,7 @@ Sentry.init({
  // todo: get this from env
  dsn: 'https://username@domain/123',
  tunnel: `http://localhost:3031/`, // proxy server
- integrations: [Sentry.browserTracingIntegration()],
+ integrations: [Sentry.reactRouterTracingIntegration()],
  tracesSampleRate: 1.0,
  tracePropagationTargets: [/^\//],
 });

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

@@ -12,6 +12,7 @@ export default [
  ]),
  ...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'),
  ]),

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

@@ -1,3 +1,13 @@
+import { Link } from 'react-router';
+
 export default function PerformancePage() {
- return <h1>Performance Page</h1>;
+ return (
+ <div>
+ <h1>Performance Page</h1>
+ <nav>
+ <Link to="/performance/ssr">SSR Page</Link>
+ <Link to="/performance/with/sentry">With Param Page</Link>
+ </nav>
+ </div>
+ );
 }

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

@@ -0,0 +1,7 @@
+export default function SsrPage() {
+ return (
+ <div>
+ <h1>SSR Page</h1>
+ </div>
+ );
+}

dev-packages/e2e-tests/test-applications/react-router-7-framework/tests/performance/navigation.client.test.ts

@@ -0,0 +1,107 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+import { APP_NAME } from '../constants';
+
+test.describe('client - navigation performance', () => {
+ test('should create navigation transaction', async ({ page }) => {
+ const navigationPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/ssr';
+ });
+
+ await page.goto(`/performance`); // pageload
+ await page.waitForTimeout(1000); // give it a sec before navigation
+ await page.getByRole('link', { name: 'SSR Page' }).click(); // navigation
+
+ const transaction = await navigationPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.navigation.react-router',
+ 'sentry.op': 'navigation',
+ 'sentry.source': 'url',
+ },
+ op: 'navigation',
+ origin: 'auto.navigation.react-router',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/ssr',
+ type: 'transaction',
+ transaction_info: { source: 'url' },
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/ssr'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+
+ test('should update navigation transaction for dynamic routes', async ({ page }) => {
+ const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/with/:param';
+ });
+
+ await page.goto(`/performance`); // pageload
+ await page.waitForTimeout(1000); // give it a sec before navigation
+ await page.getByRole('link', { name: 'With Param Page' }).click(); // navigation
+
+ const transaction = await txPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.navigation.react-router',
+ 'sentry.op': 'navigation',
+ 'sentry.source': 'route',
+ },
+ op: 'navigation',
+ origin: 'auto.navigation.react-router',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/with/:param',
+ type: 'transaction',
+ transaction_info: { source: 'route' },
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/with/sentry'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+});

dev-packages/e2e-tests/test-applications/react-router-7-framework/tests/performance/pageload.client.test.ts

@@ -53,6 +53,56 @@ test.describe('client - pageload performance', () => {
  });
  });
 
+ test('should update pageload transaction for dynamic routes', async ({ page }) => {
+ const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/with/:param';
+ });
+
+ await page.goto(`/performance/with/sentry`);
+
+ const transaction = await txPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.pageload.browser',
+ 'sentry.op': 'pageload',
+ 'sentry.source': 'route',
+ },
+ op: 'pageload',
+ origin: 'auto.pageload.browser',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/with/:param',
+ type: 'transaction',
+ transaction_info: { source: 'route' },
+ measurements: expect.any(Object),
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/with/sentry'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+
  // todo: this page is currently not prerendered (see react-router.config.ts)
  test('should send pageload transaction for prerendered pages', async ({ page }) => {
  const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {

packages/react-router/src/client/hydratedRouter.ts

@@ -0,0 +1,147 @@
+import { startBrowserTracingNavigationSpan } from '@sentry/browser';
+import type { Span } from '@sentry/core';
+import {
+ consoleSandbox,
+ getActiveSpan,
+ getClient,
+ getRootSpan,
+ GLOBAL_OBJ,
+ SEMANTIC_ATTRIBUTE_SENTRY_OP,
+ SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+ SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
+ spanToJSON,
+} from '@sentry/core';
+import type { DataRouter, RouterState } from 'react-router';
+import { DEBUG_BUILD } from '../common/debug-build';
+
+const GLOBAL_OBJ_WITH_DATA_ROUTER = GLOBAL_OBJ as typeof GLOBAL_OBJ & {
+ __reactRouterDataRouter?: DataRouter;
+};
+
+const MAX_RETRIES = 40; // 2 seconds at 50ms interval
+
+/**
+ * Instruments the React Router Data Router for pageloads and navigation.
+ *
+ * This function waits for the router to be available after hydration, then:
+ * 1. Updates the pageload transaction with parameterized route info
+ * 2. Patches router.navigate() to create navigation transactions
+ * 3. Subscribes to router state changes to update navigation transactions with parameterized routes
+ */
+export function instrumentHydratedRouter(): void {
+ function trySubscribe(): boolean {
+ const router = GLOBAL_OBJ_WITH_DATA_ROUTER.__reactRouterDataRouter;
+
+ if (router) {
+ // The first time we hit the router, we try to update the pageload transaction
+ // todo: update pageload tx here
+ const pageloadSpan = getActiveRootSpan();
+ const pageloadName = pageloadSpan ? spanToJSON(pageloadSpan).description : undefined;
+ const parameterizePageloadRoute = getParameterizedRoute(router.state);
+ if (
+ pageloadName &&
+ normalizePathname(router.state.location.pathname) === normalizePathname(pageloadName) && // this event is for the currently active pageload
+ normalizePathname(parameterizePageloadRoute) !== normalizePathname(pageloadName) // route is not parameterized yet
+ ) {
+ pageloadSpan?.updateName(parameterizePageloadRoute);
+ pageloadSpan?.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+ }
+
+ // Patching navigate for creating accurate navigation transactions
+ if (typeof router.navigate === 'function') {
+ const originalNav = router.navigate.bind(router);
+ router.navigate = function sentryPatchedNavigate(...args) {
+ maybeCreateNavigationTransaction(
+ String(args[0]) || '<unknown route>', // will be updated anyway
+ 'url', // this also will be updated once we have the parameterized route
+ );
+ return originalNav(...args);
+ };
+ }
+
+ // Subscribe to router state changes to update navigation transactions with parameterized routes
+ router.subscribe(newState => {
+ const navigationSpan = getActiveRootSpan();
+ const navigationSpanName = navigationSpan ? spanToJSON(navigationSpan).description : undefined;
+ const parameterizedNavRoute = getParameterizedRoute(newState);
+
+ if (
+ navigationSpanName && // we have an active pageload tx
+ newState.navigation.state === 'idle' && // navigation has completed
+ normalizePathname(newState.location.pathname) === normalizePathname(navigationSpanName) && // this event is for the currently active navigation
+ normalizePathname(parameterizedNavRoute) !== normalizePathname(navigationSpanName) // route is not parameterized yet
+ ) {
+ navigationSpan?.updateName(parameterizedNavRoute);
+ navigationSpan?.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+ }
+ });
+ return true;
+ }
+ return false;
+ }
+
+ // Wait until the router is available (since the SDK loads before hydration)
+ if (!trySubscribe()) {
+ let retryCount = 0;
+ // Retry until the router is available or max retries reached
+ const interval = setInterval(() => {
+ if (trySubscribe() || retryCount >= MAX_RETRIES) {
+ if (retryCount >= MAX_RETRIES) {
+ DEBUG_BUILD &&
+ consoleSandbox(() => {
+ // eslint-disable-next-line no-console
+ console.warn('Unable to instrument React Router: router not found after hydration.');
+ });
+ }
+ clearInterval(interval);
+ }
+ retryCount++;
+ }, 50);
+ }
+}
+
+function maybeCreateNavigationTransaction(name: string, source: 'url' | 'route'): Span | undefined {
+ const client = getClient();
+
+ if (!client) {
+ return undefined;
+ }
+
+ return startBrowserTracingNavigationSpan(client, {
+ name,
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: source,
+ [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'navigation',
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.navigation.react-router',
+ },
+ });
+}
+
+function getActiveRootSpan(): Span | undefined {
+ const activeSpan = getActiveSpan();
+ if (!activeSpan) {
+ return undefined;
+ }
+
+ const rootSpan = getRootSpan(activeSpan);
+
+ const op = spanToJSON(rootSpan).op;
+
+ // Only use this root span if it is a pageload or navigation span
+ return op === 'navigation' || op === 'pageload' ? rootSpan : undefined;
+}
+
+function getParameterizedRoute(routerState: RouterState): string {
+ const lastMatch = routerState.matches[routerState.matches.length - 1];
+ return normalizePathname(lastMatch?.route.path ?? routerState.location.pathname);
+}
+
+function normalizePathname(pathname: string): string {
+ // Ensure it starts with a single slash
+ let normalized = pathname.startsWith('/') ? pathname : `/${pathname}`;
+ // Remove trailing slash unless it's the root
+ if (normalized.length > 1 && normalized.endsWith('/')) {
+ normalized = normalized.slice(0, -1);
+ }
+ return normalized;
+}

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

@@ -1,3 +1,4 @@
 export * from '@sentry/browser';
 
 export { init } from './sdk';
+export { reactRouterTracingIntegration } from './tracingIntegration';

packages/react-router/src/client/sdk.ts

@@ -1,19 +1,33 @@
 import type { BrowserOptions } from '@sentry/browser';
 import { init as browserInit } from '@sentry/browser';
 import type { Client } from '@sentry/core';
-import { applySdkMetadata, setTag } from '@sentry/core';
+import { applySdkMetadata, consoleSandbox, setTag } from '@sentry/core';
+
+const BROWSER_TRACING_INTEGRATION_ID = 'BrowserTracing';
 
 /**
  * Initializes the client side of the React Router SDK.
  */
 export function init(options: BrowserOptions): Client | undefined {
- const opts = {
- ...options,
- };
+ // If BrowserTracing integration was passed to options, emit a warning
+ if (options.integrations && Array.isArray(options.integrations)) {
+ const hasBrowserTracing = options.integrations.some(
+ integration => integration.name === BROWSER_TRACING_INTEGRATION_ID,
+ );
+
+ if (hasBrowserTracing) {
+ consoleSandbox(() => {
+ // eslint-disable-next-line no-console
+ console.warn(
+ 'browserTracingIntegration is not fully compatible with @sentry/react-router. Please use reactRouterTracingIntegration instead.',
+ );
+ });
+ }
+ }
 
- applySdkMetadata(opts, 'react-router', ['react-router', 'browser']);
+ applySdkMetadata(options, 'react-router', ['react-router', 'browser']);
 
- const client = browserInit(opts);
+ const client = browserInit(options);
 
  setTag('runtime', 'browser');
 

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

@@ -8,7 +8,7 @@ Sentry.init({
  // todo: get this from env
  dsn: 'https://username@domain/123',
  tunnel: `http://localhost:3031/`, // proxy server
- integrations: [Sentry.browserTracingIntegration()],
+ integrations: [Sentry.reactRouterTracingIntegration()],
  tracesSampleRate: 1.0,
  tracePropagationTargets: [/^\//],
 });

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

@@ -12,6 +12,7 @@ export default [
  ]),
  ...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'),
  ]),

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

@@ -1,3 +1,13 @@
+import { Link } from 'react-router';
+
 export default function PerformancePage() {
- return <h1>Performance Page</h1>;
+ return (
+ <div>
+ <h1>Performance Page</h1>
+ <nav>
+ <Link to="/performance/ssr">SSR Page</Link>
+ <Link to="/performance/with/sentry">With Param Page</Link>
+ </nav>
+ </div>
+ );
 }

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

@@ -0,0 +1,7 @@
+export default function SsrPage() {
+ return (
+ <div>
+ <h1>SSR Page</h1>
+ </div>
+ );
+}

dev-packages/e2e-tests/test-applications/react-router-7-framework/tests/performance/navigation.client.test.ts

@@ -0,0 +1,107 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+import { APP_NAME } from '../constants';
+
+test.describe('client - navigation performance', () => {
+ test('should create navigation transaction', async ({ page }) => {
+ const navigationPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/ssr';
+ });
+
+ await page.goto(`/performance`); // pageload
+ await page.waitForTimeout(1000); // give it a sec before navigation
+ await page.getByRole('link', { name: 'SSR Page' }).click(); // navigation
+
+ const transaction = await navigationPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.navigation.react-router',
+ 'sentry.op': 'navigation',
+ 'sentry.source': 'url',
+ },
+ op: 'navigation',
+ origin: 'auto.navigation.react-router',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/ssr',
+ type: 'transaction',
+ transaction_info: { source: 'url' },
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/ssr'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+
+ test('should update navigation transaction for dynamic routes', async ({ page }) => {
+ const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/with/:param';
+ });
+
+ await page.goto(`/performance`); // pageload
+ await page.waitForTimeout(1000); // give it a sec before navigation
+ await page.getByRole('link', { name: 'With Param Page' }).click(); // navigation
+
+ const transaction = await txPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.navigation.react-router',
+ 'sentry.op': 'navigation',
+ 'sentry.source': 'route',
+ },
+ op: 'navigation',
+ origin: 'auto.navigation.react-router',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/with/:param',
+ type: 'transaction',
+ transaction_info: { source: 'route' },
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/with/sentry'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+});

dev-packages/e2e-tests/test-applications/react-router-7-framework/tests/performance/pageload.client.test.ts

@@ -53,6 +53,56 @@ test.describe('client - pageload performance', () => {
  });
  });
 
+ test('should update pageload transaction for dynamic routes', async ({ page }) => {
+ const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/with/:param';
+ });
+
+ await page.goto(`/performance/with/sentry`);
+
+ const transaction = await txPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.pageload.browser',
+ 'sentry.op': 'pageload',
+ 'sentry.source': 'route',
+ },
+ op: 'pageload',
+ origin: 'auto.pageload.browser',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/with/:param',
+ type: 'transaction',
+ transaction_info: { source: 'route' },
+ measurements: expect.any(Object),
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/with/sentry'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+
  // todo: this page is currently not prerendered (see react-router.config.ts)
  test('should send pageload transaction for prerendered pages', async ({ page }) => {
  const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {

packages/react-router/src/client/hydratedRouter.ts

@@ -0,0 +1,147 @@
+import { startBrowserTracingNavigationSpan } from '@sentry/browser';
+import type { Span } from '@sentry/core';
+import {
+ consoleSandbox,
+ getActiveSpan,
+ getClient,
+ getRootSpan,
+ GLOBAL_OBJ,
+ SEMANTIC_ATTRIBUTE_SENTRY_OP,
+ SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+ SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
+ spanToJSON,
+} from '@sentry/core';
+import type { DataRouter, RouterState } from 'react-router';
+import { DEBUG_BUILD } from '../common/debug-build';
+
+const GLOBAL_OBJ_WITH_DATA_ROUTER = GLOBAL_OBJ as typeof GLOBAL_OBJ & {
+ __reactRouterDataRouter?: DataRouter;
+};
+
+const MAX_RETRIES = 40; // 2 seconds at 50ms interval
+
+/**
+ * Instruments the React Router Data Router for pageloads and navigation.
+ *
+ * This function waits for the router to be available after hydration, then:
+ * 1. Updates the pageload transaction with parameterized route info
+ * 2. Patches router.navigate() to create navigation transactions
+ * 3. Subscribes to router state changes to update navigation transactions with parameterized routes
+ */
+export function instrumentHydratedRouter(): void {
+ function trySubscribe(): boolean {
+ const router = GLOBAL_OBJ_WITH_DATA_ROUTER.__reactRouterDataRouter;
+
+ if (router) {
+ // The first time we hit the router, we try to update the pageload transaction
+ // todo: update pageload tx here
+ const pageloadSpan = getActiveRootSpan();
+ const pageloadName = pageloadSpan ? spanToJSON(pageloadSpan).description : undefined;
+ const parameterizePageloadRoute = getParameterizedRoute(router.state);
+ if (
+ pageloadName &&
+ normalizePathname(router.state.location.pathname) === normalizePathname(pageloadName) && // this event is for the currently active pageload
+ normalizePathname(parameterizePageloadRoute) !== normalizePathname(pageloadName) // route is not parameterized yet
+ ) {
+ pageloadSpan?.updateName(parameterizePageloadRoute);
+ pageloadSpan?.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+ }
+
+ // Patching navigate for creating accurate navigation transactions
+ if (typeof router.navigate === 'function') {
+ const originalNav = router.navigate.bind(router);
+ router.navigate = function sentryPatchedNavigate(...args) {
+ maybeCreateNavigationTransaction(
+ String(args[0]) || '<unknown route>', // will be updated anyway
+ 'url', // this also will be updated once we have the parameterized route
+ );
+ return originalNav(...args);
+ };
+ }
+
+ // Subscribe to router state changes to update navigation transactions with parameterized routes
+ router.subscribe(newState => {
+ const navigationSpan = getActiveRootSpan();
+ const navigationSpanName = navigationSpan ? spanToJSON(navigationSpan).description : undefined;
+ const parameterizedNavRoute = getParameterizedRoute(newState);
+
+ if (
+ navigationSpanName && // we have an active pageload tx
+ newState.navigation.state === 'idle' && // navigation has completed
+ normalizePathname(newState.location.pathname) === normalizePathname(navigationSpanName) && // this event is for the currently active navigation
+ normalizePathname(parameterizedNavRoute) !== normalizePathname(navigationSpanName) // route is not parameterized yet
+ ) {
+ navigationSpan?.updateName(parameterizedNavRoute);
+ navigationSpan?.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+ }
+ });
+ return true;
+ }
+ return false;
+ }
+
+ // Wait until the router is available (since the SDK loads before hydration)
+ if (!trySubscribe()) {
+ let retryCount = 0;
+ // Retry until the router is available or max retries reached
+ const interval = setInterval(() => {
+ if (trySubscribe() || retryCount >= MAX_RETRIES) {
+ if (retryCount >= MAX_RETRIES) {
+ DEBUG_BUILD &&
+ consoleSandbox(() => {
+ // eslint-disable-next-line no-console
+ console.warn('Unable to instrument React Router: router not found after hydration.');
+ });
+ }
+ clearInterval(interval);
+ }
+ retryCount++;
+ }, 50);
+ }
+}
+
+function maybeCreateNavigationTransaction(name: string, source: 'url' | 'route'): Span | undefined {
+ const client = getClient();
+
+ if (!client) {
+ return undefined;
+ }
+
+ return startBrowserTracingNavigationSpan(client, {
+ name,
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: source,
+ [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'navigation',
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.navigation.react-router',
+ },
+ });
+}
+
+function getActiveRootSpan(): Span | undefined {
+ const activeSpan = getActiveSpan();
+ if (!activeSpan) {
+ return undefined;
+ }
+
+ const rootSpan = getRootSpan(activeSpan);
+
+ const op = spanToJSON(rootSpan).op;
+
+ // Only use this root span if it is a pageload or navigation span
+ return op === 'navigation' || op === 'pageload' ? rootSpan : undefined;
+}
+
+function getParameterizedRoute(routerState: RouterState): string {
+ const lastMatch = routerState.matches[routerState.matches.length - 1];
+ return normalizePathname(lastMatch?.route.path ?? routerState.location.pathname);
+}
+
+function normalizePathname(pathname: string): string {
+ // Ensure it starts with a single slash
+ let normalized = pathname.startsWith('/') ? pathname : `/${pathname}`;
+ // Remove trailing slash unless it's the root
+ if (normalized.length > 1 && normalized.endsWith('/')) {
+ normalized = normalized.slice(0, -1);
+ }
+ return normalized;
+}

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

@@ -1,3 +1,4 @@
 export * from '@sentry/browser';
 
 export { init } from './sdk';
+export { reactRouterTracingIntegration } from './tracingIntegration';

packages/react-router/src/client/sdk.ts

@@ -1,19 +1,33 @@
 import type { BrowserOptions } from '@sentry/browser';
 import { init as browserInit } from '@sentry/browser';
 import type { Client } from '@sentry/core';
-import { applySdkMetadata, setTag } from '@sentry/core';
+import { applySdkMetadata, consoleSandbox, setTag } from '@sentry/core';
+
+const BROWSER_TRACING_INTEGRATION_ID = 'BrowserTracing';
 
 /**
  * Initializes the client side of the React Router SDK.
  */
 export function init(options: BrowserOptions): Client | undefined {
- const opts = {
- ...options,
- };
+ // If BrowserTracing integration was passed to options, emit a warning
+ if (options.integrations && Array.isArray(options.integrations)) {
+ const hasBrowserTracing = options.integrations.some(
+ integration => integration.name === BROWSER_TRACING_INTEGRATION_ID,
+ );
+
+ if (hasBrowserTracing) {
+ consoleSandbox(() => {
+ // eslint-disable-next-line no-console
+ console.warn(
+ 'browserTracingIntegration is not fully compatible with @sentry/react-router. Please use reactRouterTracingIntegration instead.',
+ );
+ });
+ }
+ }
 
- applySdkMetadata(opts, 'react-router', ['react-router', 'browser']);
+ applySdkMetadata(options, 'react-router', ['react-router', 'browser']);
 
- const client = browserInit(opts);
+ const client = browserInit(options);
 
  setTag('runtime', 'browser');
 

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

@@ -8,7 +8,7 @@ Sentry.init({
  // todo: get this from env
  dsn: 'https://username@domain/123',
  tunnel: `http://localhost:3031/`, // proxy server
- integrations: [Sentry.browserTracingIntegration()],
+ integrations: [Sentry.reactRouterTracingIntegration()],
  tracesSampleRate: 1.0,
  tracePropagationTargets: [/^\//],
 });

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

@@ -12,6 +12,7 @@ export default [
  ]),
  ...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'),
  ]),

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

@@ -1,3 +1,13 @@
+import { Link } from 'react-router';
+
 export default function PerformancePage() {
- return <h1>Performance Page</h1>;
+ return (
+ <div>
+ <h1>Performance Page</h1>
+ <nav>
+ <Link to="/performance/ssr">SSR Page</Link>
+ <Link to="/performance/with/sentry">With Param Page</Link>
+ </nav>
+ </div>
+ );
 }

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

@@ -0,0 +1,7 @@
+export default function SsrPage() {
+ return (
+ <div>
+ <h1>SSR Page</h1>
+ </div>
+ );
+}

dev-packages/e2e-tests/test-applications/react-router-7-framework/tests/performance/navigation.client.test.ts

@@ -0,0 +1,107 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+import { APP_NAME } from '../constants';
+
+test.describe('client - navigation performance', () => {
+ test('should create navigation transaction', async ({ page }) => {
+ const navigationPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/ssr';
+ });
+
+ await page.goto(`/performance`); // pageload
+ await page.waitForTimeout(1000); // give it a sec before navigation
+ await page.getByRole('link', { name: 'SSR Page' }).click(); // navigation
+
+ const transaction = await navigationPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.navigation.react-router',
+ 'sentry.op': 'navigation',
+ 'sentry.source': 'url',
+ },
+ op: 'navigation',
+ origin: 'auto.navigation.react-router',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/ssr',
+ type: 'transaction',
+ transaction_info: { source: 'url' },
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/ssr'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+
+ test('should update navigation transaction for dynamic routes', async ({ page }) => {
+ const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/with/:param';
+ });
+
+ await page.goto(`/performance`); // pageload
+ await page.waitForTimeout(1000); // give it a sec before navigation
+ await page.getByRole('link', { name: 'With Param Page' }).click(); // navigation
+
+ const transaction = await txPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.navigation.react-router',
+ 'sentry.op': 'navigation',
+ 'sentry.source': 'route',
+ },
+ op: 'navigation',
+ origin: 'auto.navigation.react-router',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/with/:param',
+ type: 'transaction',
+ transaction_info: { source: 'route' },
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/with/sentry'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+});

dev-packages/e2e-tests/test-applications/react-router-7-framework/tests/performance/pageload.client.test.ts

@@ -53,6 +53,56 @@ test.describe('client - pageload performance', () => {
  });
  });
 
+ test('should update pageload transaction for dynamic routes', async ({ page }) => {
+ const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/with/:param';
+ });
+
+ await page.goto(`/performance/with/sentry`);
+
+ const transaction = await txPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.pageload.browser',
+ 'sentry.op': 'pageload',
+ 'sentry.source': 'route',
+ },
+ op: 'pageload',
+ origin: 'auto.pageload.browser',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/with/:param',
+ type: 'transaction',
+ transaction_info: { source: 'route' },
+ measurements: expect.any(Object),
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/with/sentry'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+
  // todo: this page is currently not prerendered (see react-router.config.ts)
  test('should send pageload transaction for prerendered pages', async ({ page }) => {
  const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {

packages/react-router/src/client/hydratedRouter.ts

@@ -0,0 +1,147 @@
+import { startBrowserTracingNavigationSpan } from '@sentry/browser';
+import type { Span } from '@sentry/core';
+import {
+ consoleSandbox,
+ getActiveSpan,
+ getClient,
+ getRootSpan,
+ GLOBAL_OBJ,
+ SEMANTIC_ATTRIBUTE_SENTRY_OP,
+ SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+ SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
+ spanToJSON,
+} from '@sentry/core';
+import type { DataRouter, RouterState } from 'react-router';
+import { DEBUG_BUILD } from '../common/debug-build';
+
+const GLOBAL_OBJ_WITH_DATA_ROUTER = GLOBAL_OBJ as typeof GLOBAL_OBJ & {
+ __reactRouterDataRouter?: DataRouter;
+};
+
+const MAX_RETRIES = 40; // 2 seconds at 50ms interval
+
+/**
+ * Instruments the React Router Data Router for pageloads and navigation.
+ *
+ * This function waits for the router to be available after hydration, then:
+ * 1. Updates the pageload transaction with parameterized route info
+ * 2. Patches router.navigate() to create navigation transactions
+ * 3. Subscribes to router state changes to update navigation transactions with parameterized routes
+ */
+export function instrumentHydratedRouter(): void {
+ function trySubscribe(): boolean {
+ const router = GLOBAL_OBJ_WITH_DATA_ROUTER.__reactRouterDataRouter;
+
+ if (router) {
+ // The first time we hit the router, we try to update the pageload transaction
+ // todo: update pageload tx here
+ const pageloadSpan = getActiveRootSpan();
+ const pageloadName = pageloadSpan ? spanToJSON(pageloadSpan).description : undefined;
+ const parameterizePageloadRoute = getParameterizedRoute(router.state);
+ if (
+ pageloadName &&
+ normalizePathname(router.state.location.pathname) === normalizePathname(pageloadName) && // this event is for the currently active pageload
+ normalizePathname(parameterizePageloadRoute) !== normalizePathname(pageloadName) // route is not parameterized yet
+ ) {
+ pageloadSpan?.updateName(parameterizePageloadRoute);
+ pageloadSpan?.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+ }
+
+ // Patching navigate for creating accurate navigation transactions
+ if (typeof router.navigate === 'function') {
+ const originalNav = router.navigate.bind(router);
+ router.navigate = function sentryPatchedNavigate(...args) {
+ maybeCreateNavigationTransaction(
+ String(args[0]) || '<unknown route>', // will be updated anyway
+ 'url', // this also will be updated once we have the parameterized route
+ );
+ return originalNav(...args);
+ };
+ }
+
+ // Subscribe to router state changes to update navigation transactions with parameterized routes
+ router.subscribe(newState => {
+ const navigationSpan = getActiveRootSpan();
+ const navigationSpanName = navigationSpan ? spanToJSON(navigationSpan).description : undefined;
+ const parameterizedNavRoute = getParameterizedRoute(newState);
+
+ if (
+ navigationSpanName && // we have an active pageload tx
+ newState.navigation.state === 'idle' && // navigation has completed
+ normalizePathname(newState.location.pathname) === normalizePathname(navigationSpanName) && // this event is for the currently active navigation
+ normalizePathname(parameterizedNavRoute) !== normalizePathname(navigationSpanName) // route is not parameterized yet
+ ) {
+ navigationSpan?.updateName(parameterizedNavRoute);
+ navigationSpan?.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+ }
+ });
+ return true;
+ }
+ return false;
+ }
+
+ // Wait until the router is available (since the SDK loads before hydration)
+ if (!trySubscribe()) {
+ let retryCount = 0;
+ // Retry until the router is available or max retries reached
+ const interval = setInterval(() => {
+ if (trySubscribe() || retryCount >= MAX_RETRIES) {
+ if (retryCount >= MAX_RETRIES) {
+ DEBUG_BUILD &&
+ consoleSandbox(() => {
+ // eslint-disable-next-line no-console
+ console.warn('Unable to instrument React Router: router not found after hydration.');
+ });
+ }
+ clearInterval(interval);
+ }
+ retryCount++;
+ }, 50);
+ }
+}
+
+function maybeCreateNavigationTransaction(name: string, source: 'url' | 'route'): Span | undefined {
+ const client = getClient();
+
+ if (!client) {
+ return undefined;
+ }
+
+ return startBrowserTracingNavigationSpan(client, {
+ name,
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: source,
+ [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'navigation',
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.navigation.react-router',
+ },
+ });
+}
+
+function getActiveRootSpan(): Span | undefined {
+ const activeSpan = getActiveSpan();
+ if (!activeSpan) {
+ return undefined;
+ }
+
+ const rootSpan = getRootSpan(activeSpan);
+
+ const op = spanToJSON(rootSpan).op;
+
+ // Only use this root span if it is a pageload or navigation span
+ return op === 'navigation' || op === 'pageload' ? rootSpan : undefined;
+}
+
+function getParameterizedRoute(routerState: RouterState): string {
+ const lastMatch = routerState.matches[routerState.matches.length - 1];
+ return normalizePathname(lastMatch?.route.path ?? routerState.location.pathname);
+}
+
+function normalizePathname(pathname: string): string {
+ // Ensure it starts with a single slash
+ let normalized = pathname.startsWith('/') ? pathname : `/${pathname}`;
+ // Remove trailing slash unless it's the root
+ if (normalized.length > 1 && normalized.endsWith('/')) {
+ normalized = normalized.slice(0, -1);
+ }
+ return normalized;
+}

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

@@ -1,3 +1,4 @@
 export * from '@sentry/browser';
 
 export { init } from './sdk';
+export { reactRouterTracingIntegration } from './tracingIntegration';

packages/react-router/src/client/sdk.ts

@@ -1,19 +1,33 @@
 import type { BrowserOptions } from '@sentry/browser';
 import { init as browserInit } from '@sentry/browser';
 import type { Client } from '@sentry/core';
-import { applySdkMetadata, setTag } from '@sentry/core';
+import { applySdkMetadata, consoleSandbox, setTag } from '@sentry/core';
+
+const BROWSER_TRACING_INTEGRATION_ID = 'BrowserTracing';
 
 /**
  * Initializes the client side of the React Router SDK.
  */
 export function init(options: BrowserOptions): Client | undefined {
- const opts = {
- ...options,
- };
+ // If BrowserTracing integration was passed to options, emit a warning
+ if (options.integrations && Array.isArray(options.integrations)) {
+ const hasBrowserTracing = options.integrations.some(
+ integration => integration.name === BROWSER_TRACING_INTEGRATION_ID,
+ );
+
+ if (hasBrowserTracing) {
+ consoleSandbox(() => {
+ // eslint-disable-next-line no-console
+ console.warn(
+ 'browserTracingIntegration is not fully compatible with @sentry/react-router. Please use reactRouterTracingIntegration instead.',
+ );
+ });
+ }
+ }
 
- applySdkMetadata(opts, 'react-router', ['react-router', 'browser']);
+ applySdkMetadata(options, 'react-router', ['react-router', 'browser']);
 
- const client = browserInit(opts);
+ const client = browserInit(options);
 
  setTag('runtime', 'browser');
 

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

@@ -8,7 +8,7 @@ Sentry.init({
  // todo: get this from env
  dsn: 'https://username@domain/123',
  tunnel: `http://localhost:3031/`, // proxy server
- integrations: [Sentry.browserTracingIntegration()],
+ integrations: [Sentry.reactRouterTracingIntegration()],
  tracesSampleRate: 1.0,
  tracePropagationTargets: [/^\//],
 });

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

@@ -12,6 +12,7 @@ export default [
  ]),
  ...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'),
  ]),

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

@@ -1,3 +1,13 @@
+import { Link } from 'react-router';
+
 export default function PerformancePage() {
- return <h1>Performance Page</h1>;
+ return (
+ <div>
+ <h1>Performance Page</h1>
+ <nav>
+ <Link to="/performance/ssr">SSR Page</Link>
+ <Link to="/performance/with/sentry">With Param Page</Link>
+ </nav>
+ </div>
+ );
 }

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

@@ -0,0 +1,7 @@
+export default function SsrPage() {
+ return (
+ <div>
+ <h1>SSR Page</h1>
+ </div>
+ );
+}

dev-packages/e2e-tests/test-applications/react-router-7-framework/tests/performance/navigation.client.test.ts

@@ -0,0 +1,107 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+import { APP_NAME } from '../constants';
+
+test.describe('client - navigation performance', () => {
+ test('should create navigation transaction', async ({ page }) => {
+ const navigationPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/ssr';
+ });
+
+ await page.goto(`/performance`); // pageload
+ await page.waitForTimeout(1000); // give it a sec before navigation
+ await page.getByRole('link', { name: 'SSR Page' }).click(); // navigation
+
+ const transaction = await navigationPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.navigation.react-router',
+ 'sentry.op': 'navigation',
+ 'sentry.source': 'url',
+ },
+ op: 'navigation',
+ origin: 'auto.navigation.react-router',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/ssr',
+ type: 'transaction',
+ transaction_info: { source: 'url' },
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/ssr'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+
+ test('should update navigation transaction for dynamic routes', async ({ page }) => {
+ const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/with/:param';
+ });
+
+ await page.goto(`/performance`); // pageload
+ await page.waitForTimeout(1000); // give it a sec before navigation
+ await page.getByRole('link', { name: 'With Param Page' }).click(); // navigation
+
+ const transaction = await txPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.navigation.react-router',
+ 'sentry.op': 'navigation',
+ 'sentry.source': 'route',
+ },
+ op: 'navigation',
+ origin: 'auto.navigation.react-router',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/with/:param',
+ type: 'transaction',
+ transaction_info: { source: 'route' },
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/with/sentry'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+});

dev-packages/e2e-tests/test-applications/react-router-7-framework/tests/performance/pageload.client.test.ts

@@ -53,6 +53,56 @@ test.describe('client - pageload performance', () => {
  });
  });
 
+ test('should update pageload transaction for dynamic routes', async ({ page }) => {
+ const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/with/:param';
+ });
+
+ await page.goto(`/performance/with/sentry`);
+
+ const transaction = await txPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.pageload.browser',
+ 'sentry.op': 'pageload',
+ 'sentry.source': 'route',
+ },
+ op: 'pageload',
+ origin: 'auto.pageload.browser',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/with/:param',
+ type: 'transaction',
+ transaction_info: { source: 'route' },
+ measurements: expect.any(Object),
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/with/sentry'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+
  // todo: this page is currently not prerendered (see react-router.config.ts)
  test('should send pageload transaction for prerendered pages', async ({ page }) => {
  const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {

packages/react-router/src/client/hydratedRouter.ts

@@ -0,0 +1,147 @@
+import { startBrowserTracingNavigationSpan } from '@sentry/browser';
+import type { Span } from '@sentry/core';
+import {
+ consoleSandbox,
+ getActiveSpan,
+ getClient,
+ getRootSpan,
+ GLOBAL_OBJ,
+ SEMANTIC_ATTRIBUTE_SENTRY_OP,
+ SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+ SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
+ spanToJSON,
+} from '@sentry/core';
+import type { DataRouter, RouterState } from 'react-router';
+import { DEBUG_BUILD } from '../common/debug-build';
+
+const GLOBAL_OBJ_WITH_DATA_ROUTER = GLOBAL_OBJ as typeof GLOBAL_OBJ & {
+ __reactRouterDataRouter?: DataRouter;
+};
+
+const MAX_RETRIES = 40; // 2 seconds at 50ms interval
+
+/**
+ * Instruments the React Router Data Router for pageloads and navigation.
+ *
+ * This function waits for the router to be available after hydration, then:
+ * 1. Updates the pageload transaction with parameterized route info
+ * 2. Patches router.navigate() to create navigation transactions
+ * 3. Subscribes to router state changes to update navigation transactions with parameterized routes
+ */
+export function instrumentHydratedRouter(): void {
+ function trySubscribe(): boolean {
+ const router = GLOBAL_OBJ_WITH_DATA_ROUTER.__reactRouterDataRouter;
+
+ if (router) {
+ // The first time we hit the router, we try to update the pageload transaction
+ // todo: update pageload tx here
+ const pageloadSpan = getActiveRootSpan();
+ const pageloadName = pageloadSpan ? spanToJSON(pageloadSpan).description : undefined;
+ const parameterizePageloadRoute = getParameterizedRoute(router.state);
+ if (
+ pageloadName &&
+ normalizePathname(router.state.location.pathname) === normalizePathname(pageloadName) && // this event is for the currently active pageload
+ normalizePathname(parameterizePageloadRoute) !== normalizePathname(pageloadName) // route is not parameterized yet
+ ) {
+ pageloadSpan?.updateName(parameterizePageloadRoute);
+ pageloadSpan?.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+ }
+
+ // Patching navigate for creating accurate navigation transactions
+ if (typeof router.navigate === 'function') {
+ const originalNav = router.navigate.bind(router);
+ router.navigate = function sentryPatchedNavigate(...args) {
+ maybeCreateNavigationTransaction(
+ String(args[0]) || '<unknown route>', // will be updated anyway
+ 'url', // this also will be updated once we have the parameterized route
+ );
+ return originalNav(...args);
+ };
+ }
+
+ // Subscribe to router state changes to update navigation transactions with parameterized routes
+ router.subscribe(newState => {
+ const navigationSpan = getActiveRootSpan();
+ const navigationSpanName = navigationSpan ? spanToJSON(navigationSpan).description : undefined;
+ const parameterizedNavRoute = getParameterizedRoute(newState);
+
+ if (
+ navigationSpanName && // we have an active pageload tx
+ newState.navigation.state === 'idle' && // navigation has completed
+ normalizePathname(newState.location.pathname) === normalizePathname(navigationSpanName) && // this event is for the currently active navigation
+ normalizePathname(parameterizedNavRoute) !== normalizePathname(navigationSpanName) // route is not parameterized yet
+ ) {
+ navigationSpan?.updateName(parameterizedNavRoute);
+ navigationSpan?.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+ }
+ });
+ return true;
+ }
+ return false;
+ }
+
+ // Wait until the router is available (since the SDK loads before hydration)
+ if (!trySubscribe()) {
+ let retryCount = 0;
+ // Retry until the router is available or max retries reached
+ const interval = setInterval(() => {
+ if (trySubscribe() || retryCount >= MAX_RETRIES) {
+ if (retryCount >= MAX_RETRIES) {
+ DEBUG_BUILD &&
+ consoleSandbox(() => {
+ // eslint-disable-next-line no-console
+ console.warn('Unable to instrument React Router: router not found after hydration.');
+ });
+ }
+ clearInterval(interval);
+ }
+ retryCount++;
+ }, 50);
+ }
+}
+
+function maybeCreateNavigationTransaction(name: string, source: 'url' | 'route'): Span | undefined {
+ const client = getClient();
+
+ if (!client) {
+ return undefined;
+ }
+
+ return startBrowserTracingNavigationSpan(client, {
+ name,
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: source,
+ [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'navigation',
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.navigation.react-router',
+ },
+ });
+}
+
+function getActiveRootSpan(): Span | undefined {
+ const activeSpan = getActiveSpan();
+ if (!activeSpan) {
+ return undefined;
+ }
+
+ const rootSpan = getRootSpan(activeSpan);
+
+ const op = spanToJSON(rootSpan).op;
+
+ // Only use this root span if it is a pageload or navigation span
+ return op === 'navigation' || op === 'pageload' ? rootSpan : undefined;
+}
+
+function getParameterizedRoute(routerState: RouterState): string {
+ const lastMatch = routerState.matches[routerState.matches.length - 1];
+ return normalizePathname(lastMatch?.route.path ?? routerState.location.pathname);
+}
+
+function normalizePathname(pathname: string): string {
+ // Ensure it starts with a single slash
+ let normalized = pathname.startsWith('/') ? pathname : `/${pathname}`;
+ // Remove trailing slash unless it's the root
+ if (normalized.length > 1 && normalized.endsWith('/')) {
+ normalized = normalized.slice(0, -1);
+ }
+ return normalized;
+}

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

@@ -1,3 +1,4 @@
 export * from '@sentry/browser';
 
 export { init } from './sdk';
+export { reactRouterTracingIntegration } from './tracingIntegration';

packages/react-router/src/client/sdk.ts

@@ -1,19 +1,33 @@
 import type { BrowserOptions } from '@sentry/browser';
 import { init as browserInit } from '@sentry/browser';
 import type { Client } from '@sentry/core';
-import { applySdkMetadata, setTag } from '@sentry/core';
+import { applySdkMetadata, consoleSandbox, setTag } from '@sentry/core';
+
+const BROWSER_TRACING_INTEGRATION_ID = 'BrowserTracing';
 
 /**
  * Initializes the client side of the React Router SDK.
  */
 export function init(options: BrowserOptions): Client | undefined {
- const opts = {
- ...options,
- };
+ // If BrowserTracing integration was passed to options, emit a warning
+ if (options.integrations && Array.isArray(options.integrations)) {
+ const hasBrowserTracing = options.integrations.some(
+ integration => integration.name === BROWSER_TRACING_INTEGRATION_ID,
+ );
+
+ if (hasBrowserTracing) {
+ consoleSandbox(() => {
+ // eslint-disable-next-line no-console
+ console.warn(
+ 'browserTracingIntegration is not fully compatible with @sentry/react-router. Please use reactRouterTracingIntegration instead.',
+ );
+ });
+ }
+ }
 
- applySdkMetadata(opts, 'react-router', ['react-router', 'browser']);
+ applySdkMetadata(options, 'react-router', ['react-router', 'browser']);
 
- const client = browserInit(opts);
+ const client = browserInit(options);
 
  setTag('runtime', 'browser');
 

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

@@ -8,7 +8,7 @@ Sentry.init({
  // todo: get this from env
  dsn: 'https://username@domain/123',
  tunnel: `http://localhost:3031/`, // proxy server
- integrations: [Sentry.browserTracingIntegration()],
+ integrations: [Sentry.reactRouterTracingIntegration()],
  tracesSampleRate: 1.0,
  tracePropagationTargets: [/^\//],
 });

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

@@ -12,6 +12,7 @@ export default [
  ]),
  ...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'),
  ]),

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

@@ -1,3 +1,13 @@
+import { Link } from 'react-router';
+
 export default function PerformancePage() {
- return <h1>Performance Page</h1>;
+ return (
+ <div>
+ <h1>Performance Page</h1>
+ <nav>
+ <Link to="/performance/ssr">SSR Page</Link>
+ <Link to="/performance/with/sentry">With Param Page</Link>
+ </nav>
+ </div>
+ );
 }

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

@@ -0,0 +1,7 @@
+export default function SsrPage() {
+ return (
+ <div>
+ <h1>SSR Page</h1>
+ </div>
+ );
+}

dev-packages/e2e-tests/test-applications/react-router-7-framework/tests/performance/navigation.client.test.ts

@@ -0,0 +1,107 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+import { APP_NAME } from '../constants';
+
+test.describe('client - navigation performance', () => {
+ test('should create navigation transaction', async ({ page }) => {
+ const navigationPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/ssr';
+ });
+
+ await page.goto(`/performance`); // pageload
+ await page.waitForTimeout(1000); // give it a sec before navigation
+ await page.getByRole('link', { name: 'SSR Page' }).click(); // navigation
+
+ const transaction = await navigationPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.navigation.react-router',
+ 'sentry.op': 'navigation',
+ 'sentry.source': 'url',
+ },
+ op: 'navigation',
+ origin: 'auto.navigation.react-router',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/ssr',
+ type: 'transaction',
+ transaction_info: { source: 'url' },
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/ssr'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+
+ test('should update navigation transaction for dynamic routes', async ({ page }) => {
+ const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/with/:param';
+ });
+
+ await page.goto(`/performance`); // pageload
+ await page.waitForTimeout(1000); // give it a sec before navigation
+ await page.getByRole('link', { name: 'With Param Page' }).click(); // navigation
+
+ const transaction = await txPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.navigation.react-router',
+ 'sentry.op': 'navigation',
+ 'sentry.source': 'route',
+ },
+ op: 'navigation',
+ origin: 'auto.navigation.react-router',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/with/:param',
+ type: 'transaction',
+ transaction_info: { source: 'route' },
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/with/sentry'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+});

dev-packages/e2e-tests/test-applications/react-router-7-framework/tests/performance/pageload.client.test.ts

@@ -53,6 +53,56 @@ test.describe('client - pageload performance', () => {
  });
  });
 
+ test('should update pageload transaction for dynamic routes', async ({ page }) => {
+ const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/with/:param';
+ });
+
+ await page.goto(`/performance/with/sentry`);
+
+ const transaction = await txPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.pageload.browser',
+ 'sentry.op': 'pageload',
+ 'sentry.source': 'route',
+ },
+ op: 'pageload',
+ origin: 'auto.pageload.browser',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/with/:param',
+ type: 'transaction',
+ transaction_info: { source: 'route' },
+ measurements: expect.any(Object),
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/with/sentry'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+
  // todo: this page is currently not prerendered (see react-router.config.ts)
  test('should send pageload transaction for prerendered pages', async ({ page }) => {
  const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {

packages/react-router/src/client/hydratedRouter.ts

@@ -0,0 +1,147 @@
+import { startBrowserTracingNavigationSpan } from '@sentry/browser';
+import type { Span } from '@sentry/core';
+import {
+ consoleSandbox,
+ getActiveSpan,
+ getClient,
+ getRootSpan,
+ GLOBAL_OBJ,
+ SEMANTIC_ATTRIBUTE_SENTRY_OP,
+ SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+ SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
+ spanToJSON,
+} from '@sentry/core';
+import type { DataRouter, RouterState } from 'react-router';
+import { DEBUG_BUILD } from '../common/debug-build';
+
+const GLOBAL_OBJ_WITH_DATA_ROUTER = GLOBAL_OBJ as typeof GLOBAL_OBJ & {
+ __reactRouterDataRouter?: DataRouter;
+};
+
+const MAX_RETRIES = 40; // 2 seconds at 50ms interval
+
+/**
+ * Instruments the React Router Data Router for pageloads and navigation.
+ *
+ * This function waits for the router to be available after hydration, then:
+ * 1. Updates the pageload transaction with parameterized route info
+ * 2. Patches router.navigate() to create navigation transactions
+ * 3. Subscribes to router state changes to update navigation transactions with parameterized routes
+ */
+export function instrumentHydratedRouter(): void {
+ function trySubscribe(): boolean {
+ const router = GLOBAL_OBJ_WITH_DATA_ROUTER.__reactRouterDataRouter;
+
+ if (router) {
+ // The first time we hit the router, we try to update the pageload transaction
+ // todo: update pageload tx here
+ const pageloadSpan = getActiveRootSpan();
+ const pageloadName = pageloadSpan ? spanToJSON(pageloadSpan).description : undefined;
+ const parameterizePageloadRoute = getParameterizedRoute(router.state);
+ if (
+ pageloadName &&
+ normalizePathname(router.state.location.pathname) === normalizePathname(pageloadName) && // this event is for the currently active pageload
+ normalizePathname(parameterizePageloadRoute) !== normalizePathname(pageloadName) // route is not parameterized yet
+ ) {
+ pageloadSpan?.updateName(parameterizePageloadRoute);
+ pageloadSpan?.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+ }
+
+ // Patching navigate for creating accurate navigation transactions
+ if (typeof router.navigate === 'function') {
+ const originalNav = router.navigate.bind(router);
+ router.navigate = function sentryPatchedNavigate(...args) {
+ maybeCreateNavigationTransaction(
+ String(args[0]) || '<unknown route>', // will be updated anyway
+ 'url', // this also will be updated once we have the parameterized route
+ );
+ return originalNav(...args);
+ };
+ }
+
+ // Subscribe to router state changes to update navigation transactions with parameterized routes
+ router.subscribe(newState => {
+ const navigationSpan = getActiveRootSpan();
+ const navigationSpanName = navigationSpan ? spanToJSON(navigationSpan).description : undefined;
+ const parameterizedNavRoute = getParameterizedRoute(newState);
+
+ if (
+ navigationSpanName && // we have an active pageload tx
+ newState.navigation.state === 'idle' && // navigation has completed
+ normalizePathname(newState.location.pathname) === normalizePathname(navigationSpanName) && // this event is for the currently active navigation
+ normalizePathname(parameterizedNavRoute) !== normalizePathname(navigationSpanName) // route is not parameterized yet
+ ) {
+ navigationSpan?.updateName(parameterizedNavRoute);
+ navigationSpan?.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+ }
+ });
+ return true;
+ }
+ return false;
+ }
+
+ // Wait until the router is available (since the SDK loads before hydration)
+ if (!trySubscribe()) {
+ let retryCount = 0;
+ // Retry until the router is available or max retries reached
+ const interval = setInterval(() => {
+ if (trySubscribe() || retryCount >= MAX_RETRIES) {
+ if (retryCount >= MAX_RETRIES) {
+ DEBUG_BUILD &&
+ consoleSandbox(() => {
+ // eslint-disable-next-line no-console
+ console.warn('Unable to instrument React Router: router not found after hydration.');
+ });
+ }
+ clearInterval(interval);
+ }
+ retryCount++;
+ }, 50);
+ }
+}
+
+function maybeCreateNavigationTransaction(name: string, source: 'url' | 'route'): Span | undefined {
+ const client = getClient();
+
+ if (!client) {
+ return undefined;
+ }
+
+ return startBrowserTracingNavigationSpan(client, {
+ name,
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: source,
+ [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'navigation',
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.navigation.react-router',
+ },
+ });
+}
+
+function getActiveRootSpan(): Span | undefined {
+ const activeSpan = getActiveSpan();
+ if (!activeSpan) {
+ return undefined;
+ }
+
+ const rootSpan = getRootSpan(activeSpan);
+
+ const op = spanToJSON(rootSpan).op;
+
+ // Only use this root span if it is a pageload or navigation span
+ return op === 'navigation' || op === 'pageload' ? rootSpan : undefined;
+}
+
+function getParameterizedRoute(routerState: RouterState): string {
+ const lastMatch = routerState.matches[routerState.matches.length - 1];
+ return normalizePathname(lastMatch?.route.path ?? routerState.location.pathname);
+}
+
+function normalizePathname(pathname: string): string {
+ // Ensure it starts with a single slash
+ let normalized = pathname.startsWith('/') ? pathname : `/${pathname}`;
+ // Remove trailing slash unless it's the root
+ if (normalized.length > 1 && normalized.endsWith('/')) {
+ normalized = normalized.slice(0, -1);
+ }
+ return normalized;
+}

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

@@ -1,3 +1,4 @@
 export * from '@sentry/browser';
 
 export { init } from './sdk';
+export { reactRouterTracingIntegration } from './tracingIntegration';

packages/react-router/src/client/sdk.ts

@@ -1,19 +1,33 @@
 import type { BrowserOptions } from '@sentry/browser';
 import { init as browserInit } from '@sentry/browser';
 import type { Client } from '@sentry/core';
-import { applySdkMetadata, setTag } from '@sentry/core';
+import { applySdkMetadata, consoleSandbox, setTag } from '@sentry/core';
+
+const BROWSER_TRACING_INTEGRATION_ID = 'BrowserTracing';
 
 /**
  * Initializes the client side of the React Router SDK.
  */
 export function init(options: BrowserOptions): Client | undefined {
- const opts = {
- ...options,
- };
+ // If BrowserTracing integration was passed to options, emit a warning
+ if (options.integrations && Array.isArray(options.integrations)) {
+ const hasBrowserTracing = options.integrations.some(
+ integration => integration.name === BROWSER_TRACING_INTEGRATION_ID,
+ );
+
+ if (hasBrowserTracing) {
+ consoleSandbox(() => {
+ // eslint-disable-next-line no-console
+ console.warn(
+ 'browserTracingIntegration is not fully compatible with @sentry/react-router. Please use reactRouterTracingIntegration instead.',
+ );
+ });
+ }
+ }
 
- applySdkMetadata(opts, 'react-router', ['react-router', 'browser']);
+ applySdkMetadata(options, 'react-router', ['react-router', 'browser']);
 
- const client = browserInit(opts);
+ const client = browserInit(options);
 
  setTag('runtime', 'browser');
 

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

@@ -8,7 +8,7 @@ Sentry.init({
  // todo: get this from env
  dsn: 'https://username@domain/123',
  tunnel: `http://localhost:3031/`, // proxy server
- integrations: [Sentry.browserTracingIntegration()],
+ integrations: [Sentry.reactRouterTracingIntegration()],
  tracesSampleRate: 1.0,
  tracePropagationTargets: [/^\//],
 });

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

@@ -12,6 +12,7 @@ export default [
  ]),
  ...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'),
  ]),

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

@@ -1,3 +1,13 @@
+import { Link } from 'react-router';
+
 export default function PerformancePage() {
- return <h1>Performance Page</h1>;
+ return (
+ <div>
+ <h1>Performance Page</h1>
+ <nav>
+ <Link to="/performance/ssr">SSR Page</Link>
+ <Link to="/performance/with/sentry">With Param Page</Link>
+ </nav>
+ </div>
+ );
 }

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

@@ -0,0 +1,7 @@
+export default function SsrPage() {
+ return (
+ <div>
+ <h1>SSR Page</h1>
+ </div>
+ );
+}

dev-packages/e2e-tests/test-applications/react-router-7-framework/tests/performance/navigation.client.test.ts

@@ -0,0 +1,107 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+import { APP_NAME } from '../constants';
+
+test.describe('client - navigation performance', () => {
+ test('should create navigation transaction', async ({ page }) => {
+ const navigationPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/ssr';
+ });
+
+ await page.goto(`/performance`); // pageload
+ await page.waitForTimeout(1000); // give it a sec before navigation
+ await page.getByRole('link', { name: 'SSR Page' }).click(); // navigation
+
+ const transaction = await navigationPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.navigation.react-router',
+ 'sentry.op': 'navigation',
+ 'sentry.source': 'url',
+ },
+ op: 'navigation',
+ origin: 'auto.navigation.react-router',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/ssr',
+ type: 'transaction',
+ transaction_info: { source: 'url' },
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/ssr'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+
+ test('should update navigation transaction for dynamic routes', async ({ page }) => {
+ const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/with/:param';
+ });
+
+ await page.goto(`/performance`); // pageload
+ await page.waitForTimeout(1000); // give it a sec before navigation
+ await page.getByRole('link', { name: 'With Param Page' }).click(); // navigation
+
+ const transaction = await txPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.navigation.react-router',
+ 'sentry.op': 'navigation',
+ 'sentry.source': 'route',
+ },
+ op: 'navigation',
+ origin: 'auto.navigation.react-router',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/with/:param',
+ type: 'transaction',
+ transaction_info: { source: 'route' },
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/with/sentry'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+});

dev-packages/e2e-tests/test-applications/react-router-7-framework/tests/performance/pageload.client.test.ts

@@ -53,6 +53,56 @@ test.describe('client - pageload performance', () => {
  });
  });
 
+ test('should update pageload transaction for dynamic routes', async ({ page }) => {
+ const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {
+ return transactionEvent.transaction === '/performance/with/:param';
+ });
+
+ await page.goto(`/performance/with/sentry`);
+
+ const transaction = await txPromise;
+
+ expect(transaction).toMatchObject({
+ contexts: {
+ trace: {
+ span_id: expect.any(String),
+ trace_id: expect.any(String),
+ data: {
+ 'sentry.origin': 'auto.pageload.browser',
+ 'sentry.op': 'pageload',
+ 'sentry.source': 'route',
+ },
+ op: 'pageload',
+ origin: 'auto.pageload.browser',
+ },
+ },
+ spans: expect.any(Array),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ transaction: '/performance/with/:param',
+ type: 'transaction',
+ transaction_info: { source: 'route' },
+ measurements: expect.any(Object),
+ platform: 'javascript',
+ request: {
+ url: expect.stringContaining('/performance/with/sentry'),
+ headers: expect.any(Object),
+ },
+ event_id: expect.any(String),
+ environment: 'qa',
+ sdk: {
+ integrations: expect.arrayContaining([expect.any(String)]),
+ name: 'sentry.javascript.react-router',
+ version: expect.any(String),
+ packages: [
+ { name: 'npm:@sentry/react-router', version: expect.any(String) },
+ { name: 'npm:@sentry/browser', version: expect.any(String) },
+ ],
+ },
+ tags: { runtime: 'browser' },
+ });
+ });
+
  // todo: this page is currently not prerendered (see react-router.config.ts)
  test('should send pageload transaction for prerendered pages', async ({ page }) => {
  const txPromise = waitForTransaction(APP_NAME, async transactionEvent => {

packages/react-router/src/client/hydratedRouter.ts

@@ -0,0 +1,147 @@
+import { startBrowserTracingNavigationSpan } from '@sentry/browser';
+import type { Span } from '@sentry/core';
+import {
+ consoleSandbox,
+ getActiveSpan,
+ getClient,
+ getRootSpan,
+ GLOBAL_OBJ,
+ SEMANTIC_ATTRIBUTE_SENTRY_OP,
+ SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+ SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
+ spanToJSON,
+} from '@sentry/core';
+import type { DataRouter, RouterState } from 'react-router';
+import { DEBUG_BUILD } from '../common/debug-build';
+
+const GLOBAL_OBJ_WITH_DATA_ROUTER = GLOBAL_OBJ as typeof GLOBAL_OBJ & {
+ __reactRouterDataRouter?: DataRouter;
+};
+
+const MAX_RETRIES = 40; // 2 seconds at 50ms interval
+
+/**
+ * Instruments the React Router Data Router for pageloads and navigation.
+ *
+ * This function waits for the router to be available after hydration, then:
+ * 1. Updates the pageload transaction with parameterized route info
+ * 2. Patches router.navigate() to create navigation transactions
+ * 3. Subscribes to router state changes to update navigation transactions with parameterized routes
+ */
+export function instrumentHydratedRouter(): void {
+ function trySubscribe(): boolean {
+ const router = GLOBAL_OBJ_WITH_DATA_ROUTER.__reactRouterDataRouter;
+
+ if (router) {
+ // The first time we hit the router, we try to update the pageload transaction
+ // todo: update pageload tx here
+ const pageloadSpan = getActiveRootSpan();
+ const pageloadName = pageloadSpan ? spanToJSON(pageloadSpan).description : undefined;
+ const parameterizePageloadRoute = getParameterizedRoute(router.state);
+ if (
+ pageloadName &&
+ normalizePathname(router.state.location.pathname) === normalizePathname(pageloadName) && // this event is for the currently active pageload
+ normalizePathname(parameterizePageloadRoute) !== normalizePathname(pageloadName) // route is not parameterized yet
+ ) {
+ pageloadSpan?.updateName(parameterizePageloadRoute);
+ pageloadSpan?.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+ }
+
+ // Patching navigate for creating accurate navigation transactions
+ if (typeof router.navigate === 'function') {
+ const originalNav = router.navigate.bind(router);
+ router.navigate = function sentryPatchedNavigate(...args) {
+ maybeCreateNavigationTransaction(
+ String(args[0]) || '<unknown route>', // will be updated anyway
+ 'url', // this also will be updated once we have the parameterized route
+ );
+ return originalNav(...args);
+ };
+ }
+
+ // Subscribe to router state changes to update navigation transactions with parameterized routes
+ router.subscribe(newState => {
+ const navigationSpan = getActiveRootSpan();
+ const navigationSpanName = navigationSpan ? spanToJSON(navigationSpan).description : undefined;
+ const parameterizedNavRoute = getParameterizedRoute(newState);
+
+ if (
+ navigationSpanName && // we have an active pageload tx
+ newState.navigation.state === 'idle' && // navigation has completed
+ normalizePathname(newState.location.pathname) === normalizePathname(navigationSpanName) && // this event is for the currently active navigation
+ normalizePathname(parameterizedNavRoute) !== normalizePathname(navigationSpanName) // route is not parameterized yet
+ ) {
+ navigationSpan?.updateName(parameterizedNavRoute);
+ navigationSpan?.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+ }
+ });
+ return true;
+ }
+ return false;
+ }
+
+ // Wait until the router is available (since the SDK loads before hydration)
+ if (!trySubscribe()) {
+ let retryCount = 0;
+ // Retry until the router is available or max retries reached
+ const interval = setInterval(() => {
+ if (trySubscribe() || retryCount >= MAX_RETRIES) {
+ if (retryCount >= MAX_RETRIES) {
+ DEBUG_BUILD &&
+ consoleSandbox(() => {
+ // eslint-disable-next-line no-console
+ console.warn('Unable to instrument React Router: router not found after hydration.');
+ });
+ }
+ clearInterval(interval);
+ }
+ retryCount++;
+ }, 50);
+ }
+}
+
+function maybeCreateNavigationTransaction(name: string, source: 'url' | 'route'): Span | undefined {
+ const client = getClient();
+
+ if (!client) {
+ return undefined;
+ }
+
+ return startBrowserTracingNavigationSpan(client, {
+ name,
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: source,
+ [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'navigation',
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.navigation.react-router',
+ },
+ });
+}
+
+function getActiveRootSpan(): Span | undefined {
+ const activeSpan = getActiveSpan();
+ if (!activeSpan) {
+ return undefined;
+ }
+
+ const rootSpan = getRootSpan(activeSpan);
+
+ const op = spanToJSON(rootSpan).op;
+
+ // Only use this root span if it is a pageload or navigation span
+ return op === 'navigation' || op === 'pageload' ? rootSpan : undefined;
+}
+
+function getParameterizedRoute(routerState: RouterState): string {
+ const lastMatch = routerState.matches[routerState.matches.length - 1];
+ return normalizePathname(lastMatch?.route.path ?? routerState.location.pathname);
+}
+
+function normalizePathname(pathname: string): string {
+ // Ensure it starts with a single slash
+ let normalized = pathname.startsWith('/') ? pathname : `/${pathname}`;
+ // Remove trailing slash unless it's the root
+ if (normalized.length > 1 && normalized.endsWith('/')) {
+ normalized = normalized.slice(0, -1);
+ }
+ return normalized;
+}

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

@@ -1,3 +1,4 @@
 export * from '@sentry/browser';
 
 export { init } from './sdk';
+export { reactRouterTracingIntegration } from './tracingIntegration';

packages/react-router/src/client/sdk.ts

@@ -1,19 +1,33 @@
 import type { BrowserOptions } from '@sentry/browser';
 import { init as browserInit } from '@sentry/browser';
 import type { Client } from '@sentry/core';
-import { applySdkMetadata, setTag } from '@sentry/core';
+import { applySdkMetadata, consoleSandbox, setTag } from '@sentry/core';
+
+const BROWSER_TRACING_INTEGRATION_ID = 'BrowserTracing';
 
 /**
  * Initializes the client side of the React Router SDK.
  */
 export function init(options: BrowserOptions): Client | undefined {
- const opts = {
- ...options,
- };
+ // If BrowserTracing integration was passed to options, emit a warning
+ if (options.integrations && Array.isArray(options.integrations)) {
+ const hasBrowserTracing = options.integrations.some(
+ integration => integration.name === BROWSER_TRACING_INTEGRATION_ID,
+ );
+
+ if (hasBrowserTracing) {
+ consoleSandbox(() => {
+ // eslint-disable-next-line no-console
+ console.warn(
+ 'browserTracingIntegration is not fully compatible with @sentry/react-router. Please use reactRouterTracingIntegration instead.',
+ );
+ });
+ }
+ }
 
- applySdkMetadata(opts, 'react-router', ['react-router', 'browser']);
+ applySdkMetadata(options, 'react-router', ['react-router', 'browser']);
 
- const client = browserInit(opts);
+ const client = browserInit(options);
 
  setTag('runtime', 'browser');