feat(tracing): Wrap Expo Router push, replace, navigate, back, dismiss in addition to prefetch (#6221)

* Wrap push, replace, navigate, back, dismiss in addition to prefetch

* fix(tracing): Guard Expo Router navigation breadcrumbs and spans behind sendDefaultPii

Expo Router `push`/`replace`/`navigate`/`back`/`dismiss` (and `prefetch`)
wrappers previously emitted the raw `href` and route `params` on both
the navigation breadcrumb and span attributes regardless of the client
options. Dynamic segments like `/users/123` and parameter values such
as `{ id: '123' }` can carry user identifiers and other PII, so the
existing `reactnavigation.ts` integration already gates them behind
`sendDefaultPii`. The new Expo Router wrappers should follow the same
contract.

This change:

- Reads `sendDefaultPii` from the client options and only attaches
  `href` (raw string or stringified object form) and `params` to the
  breadcrumb `data` and span attributes when it is enabled.
- Keeps the non-PII fields — `method`, `pathname` (route template),
  and `route.name` — unconditional so navigations remain visible and
  groupable in Sentry without leaking user data.
- Applies the same guard to the `prefetch` span's `route.href`
  attribute, which was newly added in this PR.
- Adds dedicated `sendDefaultPii` test cases and updates the existing
  default-off assertions for all wrapped methods.
- Adds a changelog entry for #6221.

* Fixes

* Changelog fix

* test(tracing): Cover pendingExpoRouterNavigation hand-off in reactNavigationIntegration

The Expo Router wrapper sets a pending navigation value that the
React Navigation idle-span listener is supposed to consume and apply
to the resulting transaction as the `navigation.method` attribute.
Previously only the setter side (in expoRouter.test.ts) was tested;
the consumer side had no coverage, so a regression in
reactnavigation.ts would have gone undetected.

Add three integration-level tests against the live
reactNavigationIntegration:

- the next navigation transaction is tagged with `navigation.method`
  matching the pending Expo Router call
- the pending value is consumed exactly once and does not leak into
  the following navigation
- no `navigation.method` attribute is set when nothing is pending

Surfaced by Warden review (4UA-DHD).

* fix(tracing): Drain pendingExpoRouterNavigation even when the idle-span listener short-circuits

`startIdleNavigationSpan` has several early-return paths (dispatched
noops, PRELOAD with prefetch tracking, SET_PARAMS, drawer actions, and
`useDispatchedActionData` calls without a route name in the payload).
Previously `consumePendingExpoRouterNavigation()` lived after those
returns, so a wrapped Expo Router call that ended up taking one of the
short-circuit paths left its pending value in the module-level slot.
The next, unrelated navigation then incorrectly inherited the wrong
`navigation.method` attribute.

Move the `consumePendingExpoRouterNavigation()` call to the very top of
the listener so the value is always drained on the listener invocation
triggered by the wrapper. Apply it to the span only if we actually
create one.

Add a regression test covering the dispatched-action-without-payload
early-return path; the test fails on the previous code and passes with
the fix.

Surfaced by sentry-bot and cursor-bot reviews.

* fix(tracing): Use spec-compliant `auto.navigation.expo_router` origin

Per the Sentry trace-origin spec
(https://develop.sentry.dev/sdk/telemetry/traces/trace-origin/), the
`sentry.origin` value uses the format `type.category.integration-name`,
where `category` is a span operation category such as `navigation`.

The new origin for wrapped Expo Router push/replace/navigate/back/dismiss
calls was `auto.expo_router.navigation`, which swaps the category and
integration name. Align it with the existing
`auto.navigation.react_navigation` and
`auto.navigation.react_native_navigation` constants so server-side
filtering and downstream tools recognize these as navigation spans.

The pre-existing `auto.expo_router.prefetch` origin has the same
inverted ordering but is left unchanged here \u2014 it is already shipped
and changing it would break consumers that filter by it.

Surfaced by cursor-bot review.

* docs(changelog): Note Expo Router prefetch PII-gating behavior change

The PR also tightened PII handling for the pre-existing `prefetch`
instrumentation: when `sendDefaultPii` is off (the default),
`route.href` is dropped and concrete pathnames derived from string
hrefs (e.g. `/users/42`) are replaced with `'unknown'` for
`route.name`. Templated object hrefs are unaffected.

Document this so users with dashboards or alerts filtering on
prefetch `route.name`/`route.href` notice the change.

Surfaced by cursor-bot review.

* refactor(tracing): Drop unused fields from PendingExpoRouterNavigation

The consumer in `reactnavigation.ts` only reads `.method`; the `href`,
`pathname`, and `params` fields were populated by `wrapExpoRouter` but
never used. Remove them from the interface and the setter call so the
type accurately reflects what the hand-off actually carries.

Surfaced by code review (antonis).

Author: alwx

CHANGELOG.md

@@ -12,6 +12,8 @@
 
 - Add memory, CPU, and frame measurements to Android profiling ([#6250](https://github.com/getsentry/sentry-react-native/pull/6250))
 - Add `enableAutoConsoleLogs` option to opt out of automatic `console.*` capture while keeping `enableLogs: true` for manual `Sentry.logger.*` calls ([#6235](https://github.com/getsentry/sentry-react-native/pull/6235))
+- Instrument Expo Router `push`, `replace`, `navigate`, `back`, and `dismiss` (in addition to `prefetch`) with breadcrumbs and spans, and tag the resulting idle navigation span with the initiating `navigation.method` ([#6221](https://github.com/getsentry/sentry-react-native/pull/6221))
+  - Note: Expo Router span/breadcrumb attributes that may contain user identifiers (`route.href`, `route.params`, and concrete pathnames derived from string hrefs such as `/users/42`) are now gated behind `sendDefaultPii`. When `sendDefaultPii` is off (the default), prefetch spans for string hrefs use `route.name: 'unknown'` and omit `route.href`. Templated object hrefs (e.g. `{ pathname: '/users/[id]' }`) are unaffected.
 - Warn when Gradle resolves `sentry-android` to a version incompatible with the SDK ([#6238](https://github.com/getsentry/sentry-react-native/pull/6238))
 
 ### Fixes

packages/core/etc/sentry-react-native.api.md

@@ -272,12 +272,13 @@ export interface ExpoRouter {
     // (undocumented)
     back?: () => void;
     // (undocumented)
+    dismiss?: (count?: number) => void;
+    // (undocumented)
     navigate?: (...args: unknown[]) => void;
+    // Warning: (ae-forgotten-export) The symbol "ExpoRouterHref" needs to be exported by the entry point index.d.ts
+    //
     // (undocumented)
-    prefetch?: (href: string | {
-        pathname?: string;
-        params?: Record<string, unknown>;
-    }) => void | Promise<void>;
+    prefetch?: (href: ExpoRouterHref) => void | Promise<void>;
     // (undocumented)
     push?: (...args: unknown[]) => void;
     // (undocumented)
@@ -856,7 +857,7 @@ export function wrapExpoRouter<T extends ExpoRouter>(router: T): T;
 // src/js/feedback/integration.ts:21:5 - (ae-forgotten-export) The symbol "ScreenshotButtonProps" needs to be exported by the entry point index.d.ts
 // src/js/feedback/integration.ts:23:5 - (ae-forgotten-export) The symbol "FeedbackFormTheme" needs to be exported by the entry point index.d.ts
 // src/js/tracing/reactnativetracing.ts:90:3 - (ae-forgotten-export) The symbol "ReactNativeTracingState" needs to be exported by the entry point index.d.ts
-// src/js/tracing/reactnavigation.ts:219:3 - (ae-forgotten-export) The symbol "RouteOverrideProvider" needs to be exported by the entry point index.d.ts
+// src/js/tracing/reactnavigation.ts:220:3 - (ae-forgotten-export) The symbol "RouteOverrideProvider" needs to be exported by the entry point index.d.ts
 
 // (No @packageDocumentation comment for this package)
 

packages/core/src/js/tracing/expoRouter.ts

@@ -1,64 +1,118 @@
-import { SPAN_STATUS_ERROR, SPAN_STATUS_OK, startInactiveSpan } from '@sentry/core';
+import { addBreadcrumb, getClient, SPAN_STATUS_ERROR, SPAN_STATUS_OK, startInactiveSpan } from '@sentry/core';
 
-import { SPAN_ORIGIN_AUTO_EXPO_ROUTER_PREFETCH } from './origin';
+import { SPAN_ORIGIN_AUTO_EXPO_ROUTER_NAVIGATION, SPAN_ORIGIN_AUTO_EXPO_ROUTER_PREFETCH } from './origin';
+import { clearPendingExpoRouterNavigation, setPendingExpoRouterNavigation } from './pendingExpoRouterNavigation';
+
+type ExpoRouterHref = string | { pathname?: string; params?: Record<string, unknown> };
 
 /**
- * Type definition for Expo Router's router object
+ * Type definition for Expo Router's router object.
  */
 export interface ExpoRouter {
-  prefetch?: (href: string | { pathname?: string; params?: Record<string, unknown> }) => void | Promise<void>;
-  // Other router methods can be added here if needed
+  prefetch?: (href: ExpoRouterHref) => void | Promise<void>;
   push?: (...args: unknown[]) => void;
   replace?: (...args: unknown[]) => void;
-  back?: () => void;
   navigate?: (...args: unknown[]) => void;
+  back?: () => void;
+  dismiss?: (count?: number) => void;
+}
+
+type NavigationMethod = 'push' | 'replace' | 'navigate' | 'back' | 'dismiss';
+
+interface ParsedHref {
+  href?: unknown;
+  /** A label used for span/transaction naming. May be PII when {@link concretePathname} is true. */
+  routeName: string;
+  /** Pathname extracted from the href, if any. May be PII when {@link concretePathname} is true. */
+  pathname?: string;
+  params?: Record<string, unknown>;
+  /**
+   * Whether `pathname` / `routeName` came from a concrete string href (e.g. `/users/42`)
+   * rather than a templated object href (e.g. `{ pathname: '/users/[id]' }`).
+   *
+   * Concrete pathnames can contain user identifiers and must be gated behind
+   * `sendDefaultPii`. Templated pathnames are structural and safe.
+   */
+  concretePathname: boolean;
 }
 
 /**
- * Wraps Expo Router. It currently only does one thing: extends prefetch() method
- * to add automated performance monitoring.
+ * Wraps Expo Router methods to add automated performance monitoring and breadcrumbs.
+ *
+ * Currently wraps:
+ *  - `prefetch` — wraps the call in a `navigation.prefetch` span.
+ *  - `push` / `replace` / `navigate` / `back` / `dismiss` — adds a navigation
+ *    breadcrumb, wraps the call in a short-lived span that mirrors prefetch's
+ *    error/status handling, and tags the subsequent idle navigation transaction
+ *    with the initiating `navigation.method` so the resulting span can be
+ *    attributed back to the call site.
  *
- * This function instruments the `prefetch` method of an Expo Router instance
- * to create performance spans that measure how long route prefetching takes.
+ * Safe to call repeatedly — guarded by a single `__sentryWrapped` flag.
  *
  * @param router - The Expo Router instance from `useRouter()` hook
- * @returns The same router instance with an instrumented prefetch method
+ * @returns The same router instance with instrumented methods
  */
 export function wrapExpoRouter<T extends ExpoRouter>(router: T): T {
-  if (!router?.prefetch) {
+  if (!router) {
     return router;
   }
 
-  // Check if already wrapped to avoid double-wrapping
-  if ((router as T & { __sentryPrefetchWrapped?: boolean }).__sentryPrefetchWrapped) {
+  const wrappedRouter = router as T & { __sentryWrapped?: boolean };
+  if (wrappedRouter.__sentryWrapped) {
     return router;
   }
 
-  const originalPrefetch = router.prefetch.bind(router);
+  if (router.prefetch) {
+    wrapPrefetch(router);
+  }
 
-  router.prefetch = ((href: Parameters<NonNullable<ExpoRouter['prefetch']>>[0]) => {
-    // Extract route name from href for better span naming
-    let routeName = 'unknown';
-    if (typeof href === 'string') {
-      routeName = href;
-    } else if (href && typeof href === 'object' && 'pathname' in href && href.pathname) {
-      routeName = href.pathname;
-    }
+  if (router.push) {
+    router.push = wrapNavigationMethod(router, 'push', router.push.bind(router));
+  }
+  if (router.replace) {
+    router.replace = wrapNavigationMethod(router, 'replace', router.replace.bind(router));
+  }
+  if (router.navigate) {
+    router.navigate = wrapNavigationMethod(router, 'navigate', router.navigate.bind(router));
+  }
+  if (router.back) {
+    router.back = wrapNavigationMethod(router, 'back', router.back.bind(router)) as NonNullable<T['back']>;
+  }
+  if (router.dismiss) {
+    const originalDismiss = router.dismiss.bind(router) as (...args: unknown[]) => unknown;
+    router.dismiss = wrapNavigationMethod(router, 'dismiss', originalDismiss) as NonNullable<T['dismiss']>;
+  }
+
+  wrappedRouter.__sentryWrapped = true;
+  return router;
+}
+
+function wrapPrefetch<T extends ExpoRouter>(router: T): void {
+  const originalPrefetch = router.prefetch!.bind(router);
+
+  router.prefetch = ((href: ExpoRouterHref) => {
+    const parsed = parseHref(href);
+    const sendPii = isSendDefaultPiiEnabled();
+    // For concrete string hrefs (e.g. `/users/42`), `routeName` may carry
+    // user identifiers — gate it behind `sendDefaultPii`. For templated
+    // object hrefs (e.g. `{ pathname: '/users/[id]' }`) it is structural.
+    const safeRouteName = parsed.concretePathname && !sendPii ? 'unknown' : parsed.routeName;
 
     const span = startInactiveSpan({
       op: 'navigation.prefetch',
-      name: `Prefetch ${routeName}`,
+      name: `Prefetch ${safeRouteName}`,
       attributes: {
         'sentry.origin': SPAN_ORIGIN_AUTO_EXPO_ROUTER_PREFETCH,
-        'route.href': typeof href === 'string' ? href : JSON.stringify(href),
-        'route.name': routeName,
+        'route.name': safeRouteName,
+        // `route.href` may contain dynamic segment values (e.g. `/users/42`)
+        // or stringified `params`, so it is gated behind `sendDefaultPii`.
+        ...(sendPii ? { 'route.href': serializeHref(href) } : undefined),
       },
     });
 
     try {
       const result = originalPrefetch(href);
 
-      // Handle both promise and synchronous returns
       if (result && typeof result === 'object' && 'then' in result && typeof result.then === 'function') {
         return result
           .then(res => {
@@ -71,21 +125,119 @@ export function wrapExpoRouter<T extends ExpoRouter>(router: T): T {
             span?.end();
             throw error;
           });
-      } else {
-        // Synchronous completion
-        span?.setStatus({ code: SPAN_STATUS_OK });
-        span?.end();
-        return result;
       }
+
+      span?.setStatus({ code: SPAN_STATUS_OK });
+      span?.end();
+      return result;
     } catch (error) {
       span?.setStatus({ code: SPAN_STATUS_ERROR, message: String(error) });
       span?.end();
       throw error;
     }
   }) as NonNullable<T['prefetch']>;
+}
 
-  // Mark as wrapped to prevent double-wrapping
-  (router as T & { __sentryPrefetchWrapped?: boolean }).__sentryPrefetchWrapped = true;
+function wrapNavigationMethod(
+  router: ExpoRouter,
+  method: NavigationMethod,
+  original: (...args: unknown[]) => unknown,
+): (...args: unknown[]) => unknown {
+  return (...args: unknown[]) => {
+    const parsed = parseMethodArgs(method, args);
+    const sendPii = isSendDefaultPiiEnabled();
+    // For concrete string hrefs (e.g. `/users/42`) the pathname carries the
+    // resolved URL — gate it behind `sendDefaultPii`. Templated pathnames from
+    // object hrefs (e.g. `{ pathname: '/users/[id]' }`) are structural and safe.
+    const safePathname = parsed.concretePathname && !sendPii ? undefined : parsed.pathname;
+    const safeRouteName = parsed.concretePathname && !sendPii ? method : parsed.routeName;
 
-  return router;
+    addBreadcrumb({
+      category: 'navigation',
+      type: 'navigation',
+      message: `Expo Router ${method}${safePathname ? ` to ${safePathname}` : ''}`,
+      data: {
+        method,
+        ...(safePathname ? { pathname: safePathname } : undefined),
+        // `href` (raw URL form) and `params` may contain user identifiers or
+        // other PII (e.g. `/users/42`, `{ id: '42' }`). Mirror the behavior of
+        // `reactnavigation.ts` and only include them when `sendDefaultPii` is on.
+        ...(sendPii && parsed.href !== undefined ? { href: serializeHref(parsed.href) } : undefined),
+        ...(sendPii && parsed.params ? { params: parsed.params } : undefined),
+      },
+    });
+
+    setPendingExpoRouterNavigation({ method });
+
+    const span = startInactiveSpan({
+      op: `navigation.${method}`,
+      name: `Navigation ${method}${safePathname ? ` to ${safePathname}` : ''}`,
+      attributes: {
+        'sentry.origin': SPAN_ORIGIN_AUTO_EXPO_ROUTER_NAVIGATION,
+        'navigation.method': method,
+        ...(safeRouteName ? { 'route.name': safeRouteName } : undefined),
+        ...(sendPii && parsed.href !== undefined ? { 'route.href': serializeHref(parsed.href) } : undefined),
+      },
+    });
+
+    try {
+      const result = original.apply(router, args);
+      span?.setStatus({ code: SPAN_STATUS_OK });
+      span?.end();
+      return result;
+    } catch (error) {
+      // Clear the pending value so a failed navigation does not leak its
+      // method/href onto the next successful idle navigation span.
+      clearPendingExpoRouterNavigation();
+      span?.setStatus({ code: SPAN_STATUS_ERROR, message: String(error) });
+      span?.end();
+      throw error;
+    }
+  };
+}
+
+function parseMethodArgs(method: NavigationMethod, args: unknown[]): ParsedHref {
+  if (method === 'back' || method === 'dismiss') {
+    return { routeName: method, concretePathname: false };
+  }
+  return parseHref(args[0] as ExpoRouterHref | undefined);
+}
+
+function parseHref(href: ExpoRouterHref | undefined): ParsedHref {
+  if (typeof href === 'string') {
+    return { href, routeName: href, pathname: href, concretePathname: true };
+  }
+  if (href && typeof href === 'object') {
+    const pathname = typeof href.pathname === 'string' ? href.pathname : undefined;
+    return {
+      href,
+      routeName: pathname ?? 'unknown',
+      pathname,
+      params: href.params,
+      concretePathname: false,
+    };
+  }
+  return { routeName: 'unknown', concretePathname: false };
+}
+
+/**
+ * Serializes an href into a string for inclusion in spans/breadcrumbs.
+ *
+ * Wrapped in `try/catch` because `params` may contain values that `JSON.stringify`
+ * cannot serialize (BigInt, Symbol, circular references). A failure here must
+ * never prevent the underlying navigation from running.
+ */
+function serializeHref(href: unknown): string {
+  if (typeof href === 'string') {
+    return href;
+  }
+  try {
+    return JSON.stringify(href);
+  } catch {
+    return '[unserializable href]';
+  }
+}
+
+function isSendDefaultPiiEnabled(): boolean {
+  return getClient()?.getOptions()?.sendDefaultPii ?? false;
 }

packages/core/src/js/tracing/origin.ts

@@ -12,5 +12,6 @@ export const SPAN_ORIGIN_AUTO_UI_TIME_TO_DISPLAY = 'auto.ui.time_to_display';
 export const SPAN_ORIGIN_MANUAL_UI_TIME_TO_DISPLAY = 'manual.ui.time_to_display';
 
 export const SPAN_ORIGIN_AUTO_EXPO_ROUTER_PREFETCH = 'auto.expo_router.prefetch';
+export const SPAN_ORIGIN_AUTO_EXPO_ROUTER_NAVIGATION = 'auto.navigation.expo_router';
 export const SPAN_ORIGIN_AUTO_RESOURCE_EXPO_IMAGE = 'auto.resource.expo_image';
 export const SPAN_ORIGIN_AUTO_RESOURCE_EXPO_ASSET = 'auto.resource.expo_asset';

packages/core/src/js/tracing/pendingExpoRouterNavigation.ts

@@ -0,0 +1,33 @@
+/**
+ * Cross-module hand-off between {@link wrapExpoRouter} and the
+ * {@link reactNavigationIntegration} idle navigation span.
+ *
+ * When an Expo Router method (push / replace / navigate / back / dismiss) is
+ * called, it stores the initiating method here. The next idle navigation span
+ * consumes (and clears) this value so the span can be attributed to the call
+ * site via the `navigation.method` attribute.
+ */
+
+export interface PendingExpoRouterNavigation {
+  /** The Expo Router method that initiated the navigation. */
+  method: 'push' | 'replace' | 'navigate' | 'back' | 'dismiss';
+}
+
+let pending: PendingExpoRouterNavigation | undefined;
+
+/** Stores the initiating Expo Router navigation call. Overwrites any previous pending value. */
+export function setPendingExpoRouterNavigation(value: PendingExpoRouterNavigation): void {
+  pending = value;
+}
+
+/** Returns and clears the pending Expo Router navigation, if any. */
+export function consumePendingExpoRouterNavigation(): PendingExpoRouterNavigation | undefined {
+  const value = pending;
+  pending = undefined;
+  return value;
+}
+
+/** Test helper — clears the pending value without consuming it. */
+export function clearPendingExpoRouterNavigation(): void {
+  pending = undefined;
+}

packages/core/src/js/tracing/reactnavigation.ts

@@ -27,6 +27,7 @@ import {
   markRootSpanForDiscard,
 } from './onSpanEndUtils';
 import { SPAN_ORIGIN_AUTO_NAVIGATION_REACT_NAVIGATION } from './origin';
+import { consumePendingExpoRouterNavigation } from './pendingExpoRouterNavigation';
 import { getReactNativeTracingIntegration } from './reactnativetracing';
 import { SEMANTIC_ATTRIBUTE_NAVIGATION_ACTION_TYPE, SEMANTIC_ATTRIBUTE_SENTRY_SOURCE } from './semanticAttributes';
 import {
@@ -350,6 +351,13 @@ export const reactNavigationIntegration = ({
     const actionType = event?.data?.action?.type;
     const targetRouteName = getRouteNameFromAction(event);
 
+    // Always drain the pending Expo Router value on this listener invocation —
+    // even if we end up short-circuiting below (noop / PRELOAD / drawer /
+    // missing route name). If the underlying router call did not produce an
+    // idle nav span, the value must not leak onto the next, unrelated
+    // navigation. Apply it only if we actually create `latestNavigationSpan`.
+    const pendingExpoRouter = consumePendingExpoRouterNavigation();
+
     if (event && !isAppRestart && !event.data?.noop) {
       addBreadcrumb({
         category: 'navigation.dispatch',
@@ -451,6 +459,10 @@ export const reactNavigationIntegration = ({
     latestNavigationSpan = startGenericIdleNavigationSpan(finalSpanOptions, { ...idleSpanOptions, isAppRestart });
     latestNavigationSpan?.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, SPAN_ORIGIN_AUTO_NAVIGATION_REACT_NAVIGATION);
     latestNavigationSpan?.setAttribute(SEMANTIC_ATTRIBUTE_NAVIGATION_ACTION_TYPE, navigationActionType);
+
+    if (pendingExpoRouter && latestNavigationSpan) {
+      latestNavigationSpan.setAttribute('navigation.method', pendingExpoRouter.method);
+    }
     if (ignoreEmptyBackNavigationTransactions) {
       ignoreEmptyBackNavigation(getClient(), latestNavigationSpan);
     }