feat(tracing): Correlate deep links with the navigation they trigger

CHANGELOG.md

@@ -10,6 +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.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

@@ -900,7 +900,7 @@ export function wrapTurboModule<T extends object>(name: string, module: T | null
 // 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:220:3 - (ae-forgotten-export) The symbol "RouteOverrideProvider" needs to be exported by the entry point index.d.ts
+// src/js/tracing/reactnavigation.ts:228: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/integrations/deeplink.ts

@@ -2,6 +2,9 @@ import type { IntegrationFn } from '@sentry/core';
 
 import { addBreadcrumb, defineIntegration, getClient } from '@sentry/core';
 
+import type { DeepLinkSource } from '../tracing/pendingDeepLink';
+
+import { setPendingDeepLink } from '../tracing/pendingDeepLink';
 import { sanitizeUrl } from '../tracing/utils';
 
 export const INTEGRATION_NAME = 'DeepLink';
@@ -20,8 +23,11 @@ interface RNLinking {
  * to avoid capturing PII in path segments when `sendDefaultPii` is off.
  *
  * Only replaces segments that look like identifiers (all digits, UUIDs, or hex strings).
+ *
+ * Exported so the navigation integration can apply the same sanitization when
+ * attaching a deep link URL to a navigation span.
  */
-function sanitizeDeepLinkUrl(url: string): string {
+export function sanitizeDeepLinkUrl(url: string): string {
   const stripped = sanitizeUrl(url);
 
   // Split off the scheme+authority (e.g. "myapp://host") so the regex
@@ -55,7 +61,13 @@ function getBreadcrumbUrl(url: string): string {
   return sendDefaultPii ? url : sanitizeDeepLinkUrl(url);
 }
 
-function addDeepLinkBreadcrumb(url: string): void {
+function recordDeepLink(url: string, source: DeepLinkSource): void {
+  // Hand off to the navigation integration so the next idle navigation span
+  // can attribute itself to this deep link. Always stores the raw URL —
+  // sanitization (if any) happens at attach time, based on the client's
+  // `sendDefaultPii` option at that moment.
+  setPendingDeepLink(url, source);
+
   const breadcrumbUrl = getBreadcrumbUrl(url);
   addBreadcrumb({
     category: 'deeplink',
@@ -87,7 +99,7 @@ const _deeplinkIntegration: IntegrationFn = () => {
         .getInitialURL()
         .then((url: string | null) => {
           if (url) {
-            addDeepLinkBreadcrumb(url);
+            recordDeepLink(url, 'cold-start');
           }
         })
         .catch(() => {
@@ -97,7 +109,7 @@ const _deeplinkIntegration: IntegrationFn = () => {
       // Warm open: deep link received while app is running
       subscription = linking.addEventListener('url', (event: { url: string }) => {
         if (event?.url) {
-          addDeepLinkBreadcrumb(event.url);
+          recordDeepLink(event.url, 'warm-open');
         }
       });
 

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

@@ -0,0 +1,138 @@
+/**
+ * Cross-module hand-off between the {@link deeplinkIntegration} and the
+ * {@link reactNavigationIntegration} idle navigation span.
+ *
+ * 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.
+ */
+
+/**
+ * How the deep link reached the integration:
+ * - `cold-start` — from `Linking.getInitialURL()`. The app may have been
+ *   launched by the link; the *initial* navigation is plausibly its target,
+ *   so retroactive attribution to an already-mounted initial span is allowed.
+ * - `warm-open` — from the `'url'` event while the app was running. The
+ *   triggered navigation has not happened yet, so the URL must wait in the
+ *   pending slot — retroactively tagging the *previous* navigation would
+ *   attribute the link to the wrong span.
+ */
+export type DeepLinkSource = 'cold-start' | 'warm-open';
+
+export interface PendingDeepLink {
+  /** Raw URL as received from React Native's `Linking` API. */
+  url: string;
+  /** Wall-clock timestamp (ms since epoch) when the URL was received. */
+  receivedAtMs: number;
+  /** How the link arrived — governs retroactive attribution rules. */
+  source: DeepLinkSource;
+  /**
+   * Monotonic sequence number shared with `nextEventSeq()`. The navigation
+   * integration tags every dispatched nav span with a seq from the same
+   * sequence — a warm-open link must only consume the slot for spans whose
+   * seq is strictly greater than the link's, i.e. were dispatched *after* the
+   * link arrived.
+   */
+  seq: 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;
+let seqCounter = 0;
+
+/**
+ * Returns the next value in the shared monotonic sequence. Used by the
+ * navigation integration to stamp each dispatched nav span, so consumers can
+ * tell whether a pending link arrived before or after a given dispatch.
+ */
+export function nextEventSeq(): number {
+  return ++seqCounter;
+}
+
+/**
+ * Stores the most recently received deep link URL together with the current
+ * 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, source: DeepLinkSource): void {
+  const value: PendingDeepLink = {
+    url,
+    receivedAtMs: Date.now(),
+    source,
+    seq: nextEventSeq(),
+  };
+  if (listener?.(value)) {
+    return;
+  }
+  pending = value;
+}
+
+/**
+ * Returns the pending deep link without clearing the slot, applying the same
+ * staleness check as {@link consumePendingDeepLink}. A stale value is dropped
+ * (so subsequent calls do not return it) but no fresh value is returned.
+ */
+export function peekPendingDeepLink(maxAgeMs: number): PendingDeepLink | undefined {
+  if (!pending) {
+    return undefined;
+  }
+  if (Date.now() - pending.receivedAtMs > maxAgeMs) {
+    pending = undefined;
+    return undefined;
+  }
+  return pending;
+}
+
+/**
+ * Returns and clears the pending deep link, but only if it was received
+ * 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;
+  pending = undefined;
+  if (!value) {
+    return undefined;
+  }
+  if (Date.now() - value.receivedAtMs > maxAgeMs) {
+    return undefined;
+  }
+  return value;
+}
+
+/**
+ * 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, listener, and sequence counter. */
+export function clearPendingDeepLink(): void {
+  pending = undefined;
+  listener = undefined;
+  seqCounter = 0;
+}