fix(tracing): Address PR review on deep-link / navigation correlation

Addresses three findings from Cursor Bugbot and one from Sentry's review
bot on #6264:

* **Late deep link never tags span** (Cursor, medium). When Expo Router
  auto-handles `Linking.getInitialURL()` and finishes the initial
  navigation *before* our integration's own `getInitialURL().then(...)`
  chain resolves, the URL was never attributed to the resulting span.
  Fix: `pendingDeepLink` now supports a synchronous listener that the
  navigation integration registers in `afterAllSetup`. When a link
  arrives, the listener tags the in-flight (`latestNavigationSpan`) or
  most-recent still-recording (`lastIdleNavSpan`) span directly. If
  nothing live exists, the link falls through to the slot for the next
  dispatched navigation. A WeakSet guards against double-tagging.

* **Same-route path skips deeplink retry** (Cursor, low). The early
  return in `updateLatestNavigationSpanWithCurrentRoute` for matching
  route keys (legitimate when deep-linking to the screen you're already
  on) bypassed the attribution call. Fix: consume + tag in that branch
  too, before the span reference is dropped.

* **Early consume loses pending link** (Cursor, medium). Consuming the
  pending value inside `startIdleNavigationSpan` meant a later discard
  (noop / timeout / empty route) silently wasted the link — the real
  link-driven navigation that followed would not be attributed. Fix:
  removed the eager consume on dispatch. Pending values are now only
  consumed in `updateLatestNavigationSpanWithCurrentRoute` (post route
  mount) or by the listener (live span). Discards never touch the slot.

* **`deeplink.received_at` semantically misleading** (Sentry, medium).
  The attribute stored a duration but its `_at` suffix conventionally
  denotes a timestamp. Renamed to `deeplink.dispatch_delay_ms`, which
  accurately reflects the measured gap between URL receipt and span
  annotation.

Plus: changelog entry now references PR #6264 (Danger gate).

Author: alwx

CHANGELOG.md

@@ -10,7 +10,7 @@
 
 ### Features
 
-- Correlate deep links with the navigation transaction they trigger. The next idle navigation span started within `routeChangeTimeoutMs` of a deep link arrival is tagged with `navigation.trigger: 'deeplink'`, `deeplink.url` (sanitized, respects `sendDefaultPii`), and `deeplink.received_at` (ms gap between URL received and navigation dispatched). Covers both cold start (`Linking.getInitialURL()`) and warm open (`'url'` event) paths ([#6159](https://github.com/getsentry/sentry-react-native/issues/6159))
+- Correlate deep links with the navigation transaction they trigger. The next idle navigation span started within `routeChangeTimeoutMs` of a deep link arrival is tagged with `navigation.trigger: 'deeplink'`, `deeplink.url` (sanitized, respects `sendDefaultPii`), and `deeplink.dispatch_delay_ms` (ms gap between URL received and navigation dispatched). Covers both cold start (`Linking.getInitialURL()`) and warm open (`'url'` event) paths, including the late-arrival case where Expo Router auto-handles the link before our `getInitialURL()` chain resolves ([#6264](https://github.com/getsentry/sentry-react-native/pull/6264))
 - 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))

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

@@ -857,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:222:3 - (ae-forgotten-export) The symbol "RouteOverrideProvider" needs to be exported by the entry point index.d.ts
+// src/js/tracing/reactnavigation.ts:224: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/pendingDeepLink.ts

@@ -2,12 +2,20 @@
  * Cross-module hand-off between the {@link deeplinkIntegration} and the
  * {@link reactNavigationIntegration} idle navigation span.
  *
- * When a deep link is received (either via `Linking.getInitialURL()` on cold
- * start or via the `'url'` event on warm open), the integration stores the
- * raw URL together with a receive timestamp here. The navigation integration
- * then attaches it to the next idle navigation span started within
- * `routeChangeTimeoutMs` (default 1000ms), so traces can correlate
- * "deep link → navigation" timing.
+ * Two delivery modes are supported, both of which need to work in practice:
+ *
+ * 1. **Pre-navigation (warm open / normal cold start):** the deep link is
+ *    received before any navigation has been dispatched. The URL is stored in
+ *    a single slot here; the next idle navigation span consumes it inside
+ *    `updateLatestNavigationSpanWithCurrentRoute` (within `routeChangeTimeoutMs`).
+ *
+ * 2. **Late arrival (Expo Router auto-handled cold start):** Expo Router reads
+ *    `Linking.getInitialURL()` independently and may finish the initial
+ *    navigation *before* our integration's own `getInitialURL().then(...)`
+ *    chain resolves. To still attribute that span, a synchronous listener may
+ *    be registered (by the navigation integration) and receives every link as
+ *    it arrives. If it tags a still-recording span, it returns `true` and the
+ *    slot is left empty — otherwise the link falls through to the slot.
  */
 
 export interface PendingDeepLink {
@@ -17,20 +25,36 @@ export interface PendingDeepLink {
   receivedAtMs: number;
 }
 
+/**
+ * Synchronously notified for every deep link as it arrives. A `true` return
+ * value indicates the listener has already attributed the link to a live span,
+ * and the value should NOT be stored for a future navigation.
+ */
+export type PendingDeepLinkListener = (link: PendingDeepLink) => boolean;
+
 let pending: PendingDeepLink | undefined;
+let listener: PendingDeepLinkListener | undefined;
 
 /**
  * Stores the most recently received deep link URL together with the current
- * timestamp. Overwrites any previous pending value — only the latest link
+ * timestamp. If a listener is registered and consumes the link synchronously,
+ * the slot is left empty.
+ *
+ * Overwrites any previous unconsumed pending value — only the latest link
  * matters for correlation with the next navigation.
  */
 export function setPendingDeepLink(url: string): void {
-  pending = { url, receivedAtMs: Date.now() };
+  const value: PendingDeepLink = { url, receivedAtMs: Date.now() };
+  if (listener?.(value)) {
+    return;
+  }
+  pending = value;
 }
 
 /**
  * Returns and clears the pending deep link, but only if it was received
- * within `maxAgeMs` of "now". Stale entries are discarded.
+ * within `maxAgeMs` of "now". Stale entries are discarded and the slot is
+ * cleared in all cases.
  */
 export function consumePendingDeepLink(maxAgeMs: number): PendingDeepLink | undefined {
   const value = pending;
@@ -44,7 +68,17 @@ export function consumePendingDeepLink(maxAgeMs: number): PendingDeepLink | unde
   return value;
 }
 
-/** Test helper — clears the pending value without consuming it. */
+/**
+ * Registers a synchronous listener that is invoked on every {@link setPendingDeepLink}
+ * call. Pass `undefined` to unregister. Only a single listener is supported —
+ * a new registration replaces the previous one.
+ */
+export function setPendingDeepLinkListener(fn: PendingDeepLinkListener | undefined): void {
+  listener = fn;
+}
+
+/** Test helper — clears the pending value and listener without consuming them. */
 export function clearPendingDeepLink(): void {
   pending = undefined;
+  listener = undefined;
 }

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

@@ -15,6 +15,7 @@ import {
 } from '@sentry/core';
 
 import type { UnsafeAction } from '../vendor/react-navigation/types';
+import type { PendingDeepLink } from './pendingDeepLink';
 import type { ReactNativeTracingIntegration } from './reactnativetracing';
 
 import { getAppRegistryIntegration } from '../integrations/appRegistry';
@@ -28,7 +29,7 @@ import {
   markRootSpanForDiscard,
 } from './onSpanEndUtils';
 import { SPAN_ORIGIN_AUTO_NAVIGATION_REACT_NAVIGATION } from './origin';
-import { consumePendingDeepLink } from './pendingDeepLink';
+import { consumePendingDeepLink, setPendingDeepLinkListener } from './pendingDeepLink';
 import { consumePendingExpoRouterNavigation } from './pendingExpoRouterNavigation';
 import { getReactNativeTracingIntegration } from './reactnativetracing';
 import { SEMANTIC_ATTRIBUTE_NAVIGATION_ACTION_TYPE, SEMANTIC_ATTRIBUTE_SENTRY_SOURCE } from './semanticAttributes';
@@ -232,7 +233,28 @@ export const reactNavigationIntegration = ({
   let latestNavigationSpan: Span | undefined;
   let latestNavigationSpanNameCustomized: boolean = false;
   let navigationProcessingSpan: Span | undefined;
-  let deepLinkAppliedToLatestSpan: boolean = false;
+  /**
+   * Most recently created idle navigation span, retained even after
+   * `latestNavigationSpan` is cleared on state change. Used by the deep-link
+   * listener to attribute a link that arrives between "route mounted" and
+   * "idle span ended". Cleared when superseded by the next nav span.
+   */
+  let lastIdleNavSpan: Span | undefined;
+
+  /**
+   * Synchronous listener invoked the moment a deep link is recorded. If a live
+   * idle navigation span exists, tag it directly and tell the pendingDeepLink
+   * module that the link has been consumed — otherwise let the link fall through
+   * to the slot so the next dispatched navigation picks it up.
+   */
+  const handleLateDeepLink = (link: PendingDeepLink): boolean => {
+    const span = latestNavigationSpan ?? lastIdleNavSpan;
+    if (!span || !isSpanRecording(span)) {
+      return false;
+    }
+    tagSpanWithDeepLink(span, link);
+    return true;
+  };
 
   let initialStateHandled: boolean = false;
   let isSetupComplete: boolean = false;
@@ -257,6 +279,14 @@ export const reactNavigationIntegration = ({
       };
     }
 
+    // Listen for deep links as they arrive so we can attribute a span that has
+    // already mounted its route but not yet ended (e.g. Expo Router auto-handled
+    // the link before our integration's `getInitialURL()` chain resolved).
+    setPendingDeepLinkListener(handleLateDeepLink);
+    client.on('close', () => {
+      setPendingDeepLinkListener(undefined);
+    });
+
     if (initialStateHandled) {
       // We create an initial state here to ensure a transaction gets created before the first route mounts.
       // This assumes that the Sentry.init() call is made before the first route mounts.
@@ -467,14 +497,12 @@ export const reactNavigationIntegration = ({
       latestNavigationSpan.setAttribute('navigation.method', pendingExpoRouter.method);
     }
 
-    // Try to attribute this span to a recently received deep link. Covers the
-    // warm-open case (link arrives → navigation dispatches). The cold-start
-    // case is handled again in `updateLatestNavigationSpanWithCurrentRoute`
-    // because `Linking.getInitialURL()` may resolve after this point.
-    deepLinkAppliedToLatestSpan = false;
-    if (latestNavigationSpan) {
-      deepLinkAppliedToLatestSpan = applyPendingDeepLinkToSpan(latestNavigationSpan, routeChangeTimeoutMs);
-    }
+    // Hold a reference to the freshly-created idle span so the deep-link
+    // listener can still annotate it after `latestNavigationSpan` is cleared
+    // on state change. We deliberately do NOT consume the pending deep link
+    // here — if this span is later discarded (noop / timeout / empty route),
+    // a still-fresh pending value must remain available for the next nav.
+    lastIdleNavSpan = latestNavigationSpan;
     if (ignoreEmptyBackNavigationTransactions) {
       ignoreEmptyBackNavigation(getClient(), latestNavigationSpan);
     }
@@ -531,6 +559,11 @@ export const reactNavigationIntegration = ({
 
     if (previousRoute?.key === route.key) {
       debug.log(`[${INTEGRATION_NAME}] Navigation state changed, but route is the same as previous.`);
+      // Even a same-route state change is a legitimate destination for a
+      // deep link (e.g. deep-linking to the screen you're already on). Make
+      // sure the pending link still gets attributed before we drop the span
+      // reference.
+      applyPendingDeepLinkToSpan(latestNavigationSpan, routeChangeTimeoutMs);
       pushRecentRouteKey(route.key);
       latestRoute = route;
 
@@ -567,12 +600,10 @@ export const reactNavigationIntegration = ({
       routeName = getPathFromState(navigationState) || route.name;
     }
 
-    // Cold-start fallback: if the deep link arrived *after* the idle navigation
-    // span was started (e.g. `getInitialURL()` resolved post-`afterAllSetup`),
-    // try again now that the route has mounted.
-    if (!deepLinkAppliedToLatestSpan) {
-      deepLinkAppliedToLatestSpan = applyPendingDeepLinkToSpan(latestNavigationSpan, routeChangeTimeoutMs);
-    }
+    // Consume any pending deep link and attach it to this span. Done here
+    // (after route info is known) so the link is only attributed to a span
+    // that actually mounted a route — not one that was later discarded.
+    applyPendingDeepLinkToSpan(latestNavigationSpan, routeChangeTimeoutMs);
 
     navigationProcessingSpan?.updateName(`Navigation dispatch to screen ${routeName} mounted`);
     navigationProcessingSpan?.setStatus({ code: SPAN_STATUS_OK });
@@ -619,7 +650,6 @@ export const reactNavigationIntegration = ({
     }
     // Clear the latest transaction as it has been handled.
     latestNavigationSpan = undefined;
-    deepLinkAppliedToLatestSpan = false;
   };
 
   /** Pushes a recent route key, and removes earlier routes when there is greater than the max length */
@@ -644,7 +674,6 @@ export const reactNavigationIntegration = ({
     if (navigationProcessingSpan) {
       navigationProcessingSpan = undefined;
     }
-    deepLinkAppliedToLatestSpan = false;
   };
 
   const clearStateChangeTimeout = (): void => {
@@ -701,20 +730,49 @@ interface NavigationContainer {
  * `false` otherwise. Callers may invoke this multiple times against the same
  * span — once the pending value has been consumed it will not be re-applied.
  */
-function applyPendingDeepLinkToSpan(span: Span, maxAgeMs: number): boolean {
-  const pending = consumePendingDeepLink(maxAgeMs);
-  if (!pending) {
-    return false;
+/**
+ * Per-span guard against double-tagging deep-link attributes. Shared between
+ * the synchronous listener path (late arrival) and the post-state-change path.
+ */
+const taggedDeepLinkSpans = new WeakSet<Span>();
+
+/**
+ * Annotates the given span with deep-link attributes if it has not already
+ * been annotated. Safe to call multiple times — a span is tagged at most once.
+ */
+function tagSpanWithDeepLink(span: Span, link: PendingDeepLink): void {
+  if (taggedDeepLinkSpans.has(span)) {
+    return;
   }
+  taggedDeepLinkSpans.add(span);
 
   const sendDefaultPii = getClient()?.getOptions()?.sendDefaultPii ?? false;
-  const url = sendDefaultPii ? pending.url : sanitizeDeepLinkUrl(pending.url);
+  const url = sendDefaultPii ? link.url : sanitizeDeepLinkUrl(link.url);
 
   span.setAttributes({
     'navigation.trigger': 'deeplink',
     'deeplink.url': url,
-    'deeplink.received_at': Math.max(0, Date.now() - pending.receivedAtMs),
+    // Duration between URL receipt and the moment the span is annotated —
+    // approximates the gap between "link received" and "navigation dispatched
+    // / handled".
+    'deeplink.dispatch_delay_ms': Math.max(0, Date.now() - link.receivedAtMs),
   });
+}
+
+/** Returns true if the span is still recording (has not been ended). */
+function isSpanRecording(span: Span): boolean {
+  return spanToJSON(span).timestamp === undefined;
+}
+
+function applyPendingDeepLinkToSpan(span: Span, maxAgeMs: number): boolean {
+  if (taggedDeepLinkSpans.has(span)) {
+    return true;
+  }
+  const pending = consumePendingDeepLink(maxAgeMs);
+  if (!pending) {
+    return false;
+  }
+  tagSpanWithDeepLink(span, pending);
   return true;
 }
 

packages/core/test/tracing/pendingDeepLink.test.ts

@@ -1,4 +1,9 @@
-import { clearPendingDeepLink, consumePendingDeepLink, setPendingDeepLink } from '../../src/js/tracing/pendingDeepLink';
+import {
+  clearPendingDeepLink,
+  consumePendingDeepLink,
+  setPendingDeepLink,
+  setPendingDeepLinkListener,
+} from '../../src/js/tracing/pendingDeepLink';
 
 describe('pendingDeepLink', () => {
   afterEach(() => {
@@ -54,4 +59,53 @@ describe('pendingDeepLink', () => {
     clearPendingDeepLink();
     expect(consumePendingDeepLink(1_000)).toBeUndefined();
   });
+
+  describe('listener', () => {
+    it('is invoked synchronously on every set, with url + timestamp', () => {
+      const received: Array<{ url: string; receivedAtMs: number }> = [];
+      setPendingDeepLinkListener(link => {
+        received.push({ url: link.url, receivedAtMs: link.receivedAtMs });
+        return false;
+      });
+
+      setPendingDeepLink('myapp://a');
+      setPendingDeepLink('myapp://b');
+
+      expect(received.map(r => r.url)).toEqual(['myapp://a', 'myapp://b']);
+      expect(received[0]?.receivedAtMs).toBeGreaterThan(0);
+    });
+
+    it('skips storage when the listener returns true (already consumed)', () => {
+      setPendingDeepLinkListener(() => true);
+      setPendingDeepLink('myapp://consumed-by-listener');
+
+      expect(consumePendingDeepLink(1_000)).toBeUndefined();
+    });
+
+    it('falls through to storage when the listener returns false', () => {
+      setPendingDeepLinkListener(() => false);
+      setPendingDeepLink('myapp://stored');
+
+      expect(consumePendingDeepLink(1_000)?.url).toBe('myapp://stored');
+    });
+
+    it('can be unregistered with undefined', () => {
+      const fn = jest.fn().mockReturnValue(true);
+      setPendingDeepLinkListener(fn);
+      setPendingDeepLinkListener(undefined);
+
+      setPendingDeepLink('myapp://x');
+      expect(fn).not.toHaveBeenCalled();
+      expect(consumePendingDeepLink(1_000)?.url).toBe('myapp://x');
+    });
+
+    it('clearPendingDeepLink also removes the listener', () => {
+      const fn = jest.fn().mockReturnValue(true);
+      setPendingDeepLinkListener(fn);
+      clearPendingDeepLink();
+
+      setPendingDeepLink('myapp://x');
+      expect(fn).not.toHaveBeenCalled();
+    });
+  });
 });