@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/sdks/react-native/tracing.md

@@ -0,0 +1,1086 @@
+# Tracing & Performance Monitoring — Sentry React Native SDK
+
+> **Minimum SDK:** `@sentry/react-native` ≥ 5.20.0 for TTID/TTFD · ≥ 5.32.0 for
+> profiling · ≥ 8.0.0 recommended **Mobile-first note:** React Native has unique
+> performance capabilities web SDKs don’t provide — cold/warm app start tracking, JS
+> event loop stall detection, slow/frozen frame counting, and navigation-based
+> transactions. All are first-class citizens in the Sentry RN SDK.
+
+---
+
+## Table of Contents
+
+1. [Basic Tracing Setup](#1-basic-tracing-setup)
+2. [Automatic Instrumentation Setup](#2-automatic-instrumentation-setup)
+3. [App Start Tracing](#3-app-start-tracing)
+4. [Navigation Instrumentation](#4-navigation-instrumentation)
+5. [Screen Rendering: Time to Display](#5-screen-rendering-time-to-display)
+6. [Slow & Frozen Frames](#6-slow--frozen-frames)
+7. [Stall Tracking](#7-stall-tracking)
+8. [Network Request Tracing](#8-network-request-tracing)
+9. [Distributed Tracing](#9-distributed-tracing)
+10. [User Interaction Tracing](#10-user-interaction-tracing)
+11. [Custom Spans](#11-custom-spans)
+12. [React Component Profiler](#12-react-component-profiler)
+13. [Profiling (Native + Hermes)](#13-profiling-native--hermes)
+14. [Dynamic Sampling](#14-dynamic-sampling)
+15. [Configuration Reference](#15-configuration-reference)
+16. [Mobile vs Web: Feature Matrix](#16-mobile-vs-web-feature-matrix)
+17. [Troubleshooting](#17-troubleshooting)
+
+---
+
+## 1. Basic Tracing Setup
+
+Tracing requires **no additional imports** beyond the standard Sentry import — a key
+difference from the web SDK.
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+
+Sentry.init({
+  dsn: "YOUR_DSN",
+
+  // Option A: uniform sample rate (0.0–1.0)
+  // 1.0 = 100% of transactions captured — development/testing only
+  tracesSampleRate: 1.0,
+
+  // Option B: dynamic sampler — takes precedence over tracesSampleRate when both are set
+  // tracesSampler: ({ name, attributes, parentSampled }) => {
+  //   if (name === "checkout") return 1.0;
+  //   return 0.2;
+  // },
+});
+```
+
+> **Production recommendation:** Use `tracesSampleRate: 0.2` or lower, or switch to
+> `tracesSampler` for context-aware sampling.
+> 100% sampling causes high volume at scale.
+
+---
+
+## 2. Automatic Instrumentation Setup
+
+`reactNativeTracingIntegration` must be explicitly added to enable automatic tracing
+features. Two required setup steps:
+
+### Step 1 — Add the integration
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+
+Sentry.init({
+  dsn: "YOUR_DSN",
+  tracesSampleRate: 1.0,
+  integrations: [Sentry.reactNativeTracingIntegration()],
+});
+```
+
+### Step 2 — Wrap your root component
+
+Required for accurate App Start measurement (records to first component mount instead of
+JS initialization) and to enable User Interaction tracing:
+
+```typescript
+// App.tsx
+export default Sentry.wrap(App);
+```
+
+### Opt out of automatic instrumentation
+
+```typescript
+Sentry.init({
+  dsn: "YOUR_DSN",
+  enableAutoPerformanceTracing: false, // disables all auto instrumentation
+});
+```
+
+---
+
+## 3. App Start Tracing
+
+**Unique to mobile.** Tracks the duration from the earliest native process
+initialization to React Native root component mount.
+
+| Metric         | Measurement Key               | When it fires                                     |
+| -------------- | ----------------------------- | ------------------------------------------------- |
+| **Cold start** | `measurements.app_start_cold` | Process launched from scratch (not in memory)     |
+| **Warm start** | `measurements.app_start_warm` | Process was already in memory, activity recreated |
+
+> **Hot starts and resumes are not tracked.** They’re considered too fast to be
+> meaningful for monitoring.
+
+### Why `Sentry.wrap(App)` matters for App Start
+
+Without `Sentry.wrap(App)`, the App Start measurement ends at JS initialization rather
+than at first component mount.
+Wrapping is essential for accurate data that represents the real user experience.
+
+### How App Start appears in traces
+
+When a routing integration (React Navigation, Expo Router, RNN) is present, App Start
+data appears as **spans inside the first navigation transaction** — not as a standalone
+transaction. You’ll see it in the trace waterfall as a child span at the root of the
+first screen.
+
+### Platform accuracy notes
+
+Sentry follows Apple and Google’s official App Start guidelines.
+Reported values may be slightly longer than other tools, as they’re designed to most
+accurately represent real user experience rather than minimize measured time.
+
+### Optimizing App Start time
+
+Common causes of slow cold starts and how to address them:
+
+```typescript
+// ❌ Eager import — executes at bundle parse time
+import { HeavyModule } from "./heavy-module";
+
+// ✅ Lazy import — deferred until actually needed
+const loadHeavy = () => import("./heavy-module");
+
+// ❌ Synchronous AsyncStorage read at startup
+const theme = await AsyncStorage.getItem("theme"); // blocks JS thread
+
+// ✅ Use a synchronous-safe default, hydrate later
+const [theme, setTheme] = useState("light");
+useEffect(() => {
+  AsyncStorage.getItem("theme").then(setTheme);
+}, []);
+```
+
+---
+
+## 4. Navigation Instrumentation
+
+The routing integration determines how navigation events create transactions.
+Each screen transition becomes a transaction, with the screen name as the transaction
+name.
+
+### 4a. React Navigation (v5+)
+
+The most common setup.
+Creates a transaction for every route change automatically.
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+import {
+  NavigationContainer,
+  createNavigationContainerRef,
+} from "@react-navigation/native";
+
+// Step 1 — Create the integration BEFORE Sentry.init
+const navigationIntegration = Sentry.reactNavigationIntegration({
+  enableTimeToInitialDisplay: true,             // enable TTID measurement per screen
+  routeChangeTimeoutMs: 1_000,                  // discard transaction if screen doesn't mount within 1s
+  ignoreEmptyBackNavigationTransactions: true,  // drop back-nav transactions with no child spans
+  useDispatchedActionData: true,                // attach action data to transaction metadata
+});
+
+// Step 2 — Pass to Sentry.init
+Sentry.init({
+  dsn: "YOUR_DSN",
+  tracesSampleRate: 1.0,
+  integrations: [navigationIntegration],
+});
+
+// Step 3 — Register the container ref in onReady
+function App() {
+  const containerRef = createNavigationContainerRef();
+
+  return (
+    <NavigationContainer
+      ref={containerRef}
+      onReady={() => {
+        // Must be called inside onReady — not before the container is ready
+        navigationIntegration.registerNavigationContainer(containerRef);
+      }}
+    >
+      {/* screens */}
+    </NavigationContainer>
+  );
+}
+
+export default Sentry.wrap(App);
+```
+
+### 4b. React Native Navigation (Wix/RNN)
+
+Pass the `Navigation` object directly — no ref or container wrapping needed.
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+import { Navigation } from "react-native-navigation";
+
+Sentry.init({
+  dsn: "YOUR_DSN",
+  tracesSampleRate: 1.0,
+  integrations: [
+    Sentry.reactNativeNavigationIntegration({
+      navigation: Navigation, // required — the RNN Navigation object
+      routeChangeTimeoutMs: 1_000, // discard stale transactions
+      enableTabsInstrumentation: true, // create transactions on tab changes (default: false)
+      ignoreEmptyBackNavigationTransactions: true, // drop no-span back navigations
+    }),
+  ],
+});
+```
+
+### Customizing transaction names
+
+Transaction names default to the route/screen name (e.g., `LoginScreen`, `HomeTab`).
+Modify via `beforeStartSpan`:
+
+```typescript
+Sentry.reactNativeTracingIntegration({
+  beforeStartSpan: (context) => ({
+    ...context,
+    name: context.name.replace("Screen", ""),  // strip "Screen" suffix for cleaner names
+    attributes: {
+      ...context.attributes,
+      "app.version": "2.1.0",
+    },
+  }),
+}),
+```
+
+### Tab navigation
+
+Tab navigators preload screens, so auto-instrumentation only creates a transaction for
+the **initial** tab visit.
+For subsequent tab switches, use the `TimeToInitialDisplay` and `TimeToFullDisplay`
+components explicitly (see §5).
+
+### 4c. Expo Router Dynamic Route Params as Span Attributes
+
+When using Expo Router with dynamic route segments (e.g., `profile/[id]`,
+`posts/[...slug]`), the SDK automatically captures the dynamic parameter values as span
+attributes on navigation transactions.
+
+**Requirements:**
+
+- `sendDefaultPii: true` must be set in `Sentry.init` — these values are
+  user-identifiable
+- Route names must use Expo Router bracket notation: `[param]` or `[...param]`
+
+```typescript
+Sentry.init({
+  dsn: "YOUR_DSN",
+  tracesSampleRate: 1.0,
+  sendDefaultPii: true, // required — route param values may identify users
+
+  integrations: [navigationIntegration],
+});
+```
+
+When navigating to a route like `profile/[id]` with params `{ id: '123' }`, the
+navigation span receives:
+
+```
+route.name         → "profile/[id]"
+route.params.id    → "123"
+```
+
+For catch-all segments (`[...slug]`), array values are joined with `/`:
+
+```
+route.name           → "posts/[...slug]"
+route.params.slug    → "tech/react-native"
+```
+
+**Only structural params are captured** — query params and extra props that don’t match
+a dynamic segment in the route name are intentionally excluded.
+This prevents non-structural data (referrers, UTM parameters, etc.)
+from being captured as trace attributes.
+
+| Scenario                                          | Captured?                                |
+| ------------------------------------------------- | ---------------------------------------- |
+| `profile/[id]` with `{ id: '123' }`               | ✅ `route.params.id = "123"`             |
+| `posts/[...slug]` with `{ slug: ['tech', 'rn'] }` | ✅ `route.params.slug = "tech/rn"`       |
+| `StaticScreen` with `{ utm_source: 'email' }`     | ❌ No dynamic segment — nothing captured |
+| Any route with `sendDefaultPii: false`            | ❌ Opted out — nothing captured          |
+
+> **Privacy note:** Dynamic route param values (e.g., the `123` in `profile/[id]`) are
+> user-identifiable. They are only captured when `sendDefaultPii: true` is explicitly
+> set. Review your routes to ensure no sensitive values (tokens, PII) appear in path
+> segments before enabling this option.
+
+---
+
+## 5. Screen Rendering: Time to Display
+
+Two **Mobile Vitals** that have no web equivalent:
+
+| Metric                      | Abbreviation | What it measures                                                                |
+| --------------------------- | ------------ | ------------------------------------------------------------------------------- |
+| **Time to Initial Display** | TTID         | From navigation event → first rendered frame visible after Screen mounts        |
+| **Time to Full Display**    | TTFD         | From navigation event → all async content loaded and ready for user interaction |
+
+> **Requirements:** SDK ≥ `5.20.0` · Native build required (not available in Expo Go)
+
+### Automatic TTID (React Navigation only)
+
+Enable in the integration config.
+TTID spans automatically include animation completion time (except JS-driven animations
+on iOS, which are excluded).
+
+```typescript
+const navigationIntegration = Sentry.reactNavigationIntegration({
+  enableTimeToInitialDisplay: true, // that's it
+});
+```
+
+### Manual TTID override
+
+Use when you need to control exactly when “initial display” is considered complete:
+
+```tsx
+import * as Sentry from "@sentry/react-native";
+import { View } from "react-native";
+
+function ProductListScreen() {
+  return (
+    <View>
+      <Sentry.TimeToInitialDisplay record={true} />
+      {/* content */}
+    </View>
+  );
+}
+```
+
+### Time to Full Display (TTFD)
+
+Mark full display when all async content is loaded.
+The `record` prop fires once when it transitions from `false` to `true`:
+
+```tsx
+import * as Sentry from "@sentry/react-native";
+import { useState, useEffect } from "react";
+import { View, Text, ActivityIndicator } from "react-native";
+
+function ProductDetailScreen({ productId }: { productId: string }) {
+  const [product, setProduct] = useState<Product | null>(null);
+
+  useEffect(() => {
+    fetch(`https://api.example.com/products/${productId}`)
+      .then((res) => res.json())
+      .then(setProduct);
+  }, [productId]);
+
+  return (
+    <View>
+      {/* Fires once when product transitions from null to loaded */}
+      <Sentry.TimeToFullDisplay record={product !== null} />
+
+      {product ? <Text>{product.name}</Text> : <ActivityIndicator />}
+    </View>
+  );
+}
+```
+
+### Tab screens — explicit TTID + TTFD
+
+Because tab screens are preloaded, auto-detection only fires on the first visit.
+Add both components explicitly for every tab screen:
+
+```tsx
+function HomeTabScreen({ isLoading }: { isLoading: boolean }) {
+  return (
+    <View>
+      <Sentry.TimeToInitialDisplay record={true} />
+      <Sentry.TimeToFullDisplay record={!isLoading} />
+      {/* content */}
+    </View>
+  );
+}
+```
+
+> Both `<TimeToInitialDisplay />` and `<TimeToFullDisplay />` render as `<></>` — **zero
+> visual impact.**
+
+---
+
+## 6. Slow & Frozen Frames
+
+**Mobile Vitals** — automatically captured per transaction when tracing is enabled.
+No configuration required.
+
+| Frame type       | Threshold                                       | User experience            |
+| ---------------- | ----------------------------------------------- | -------------------------- |
+| **Slow frame**   | Takes longer than expected for the refresh rate | UI hitches, animation jank |
+| **Frozen frame** | Completely unresponsive                         | App appears hung           |
+
+> Web Vitals (LCP, FID, CLS) are **not** reported for React Native — slow/frozen frames
+> are the mobile equivalent.
+
+These appear in the **Mobile Vitals** section of every transaction in Sentry’s
+performance UI, alongside App Start time.
+
+### Android: AndroidX dependency
+
+Sentry uses `androidx.core` for accurate slow/frozen frame detection across all Android
+versions. It’s included automatically.
+If you explicitly remove it:
+
+```groovy
+// android/app/build.gradle — removes androidx.core AND disables frame reporting
+api('io.sentry:sentry-android:8.33.0') {
+    exclude group: 'androidx.core', module: 'core'
+}
+```
+
+> **Warning:** Removing `androidx.core` disables slow/frozen frame detection entirely.
+
+---
+
+## 7. Stall Tracking
+
+**Unique to React Native.** A “stall” is when the JavaScript event loop takes longer
+than expected to process a tick — it directly blocks UI rendering and all JS logic.
+
+Three metrics automatically attached to every transaction:
+
+| Metric                 | Description                                          |
+| ---------------------- | ---------------------------------------------------- |
+| **Longest Stall Time** | Duration (ms) of the single longest event loop stall |
+| **Total Stall Time**   | Combined ms of all stalls during the transaction     |
+| **Stall Count**        | Number of individual stalls                          |
+
+No configuration needed — stall tracking is enabled automatically by
+`reactNativeTracingIntegration`.
+
+### What causes stalls
+
+```typescript
+// ❌ Synchronous heavy computation on the JS thread — causes stalls
+const result = items.reduce((acc, item) => {
+  return acc + expensiveComputation(item); // blocks JS thread
+}, 0);
+
+// ✅ Offload to InteractionManager or requestAnimationFrame
+InteractionManager.runAfterInteractions(() => {
+  const result = items.reduce((acc, item) => {
+    return acc + expensiveComputation(item);
+  }, 0);
+  setState(result);
+});
+
+// ✅ Or better — move to a native module / worklet (Reanimated)
+```
+
+---
+
+## 8. Network Request Tracing
+
+Every `fetch` and `XMLHttpRequest` call made while a transaction is active automatically
+gets a child span. No code changes needed.
+
+Span data includes:
+
+- HTTP method and URL
+- Response status code
+- Request/response size
+- Duration (time-to-first-byte + total)
+
+### Filter which requests get spans
+
+```typescript
+Sentry.reactNativeTracingIntegration({
+  shouldCreateSpanForRequest: (url) => {
+    // Skip analytics pings and health checks
+    return !url.match(/\/(analytics|health|metrics)\/?(\?.*)?$/);
+  },
+}),
+```
+
+### Transaction idle and final timeouts
+
+```typescript
+Sentry.reactNativeTracingIntegration({
+  idleTimeoutMs: 1_000,    // end transaction after 1s of inactivity (default: 1000)
+  finalTimeoutMs: 600_000, // hard cap: 10 minutes max transaction duration (default: 600000)
+}),
+```
+
+---
+
+## 9. Distributed Tracing
+
+Connects mobile traces to backend traces so you can see the full request lifecycle —
+from the user’s tap to database query and back.
+
+### How it works
+
+When a `fetch` request fires inside a transaction, the SDK attaches two headers:
+
+| Header         | Purpose                                      |
+| -------------- | -------------------------------------------- |
+| `sentry-trace` | Carries the trace ID and span ID             |
+| `baggage`      | Carries sampling decision and trace metadata |
+
+Your backend Sentry SDK reads these headers and links its spans to the same trace, so
+you see one unified waterfall in Sentry.
+
+### `tracePropagationTargets` — control where headers attach
+
+```typescript
+Sentry.init({
+  dsn: "YOUR_DSN",
+  tracesSampleRate: 1.0,
+
+  // Default on mobile: [/.*/] — attaches to ALL outgoing requests
+  // Restrict to your own APIs:
+  tracePropagationTargets: [
+    "api.myapp.com", // string — matched against the full URL
+    /^https:\/\/api\./, // regex — matched against the full URL
+    "localhost", // useful for local development
+  ],
+});
+```
+
+> **Important:** `tracePropagationTargets` matches against the **entire URL string**,
+> not just the domain.
+
+### CORS requirements for web APIs
+
+If your React Native app calls web APIs that run CORS preflight checks, the backend must
+allow the Sentry headers:
+
+```
+Access-Control-Allow-Headers: sentry-trace, baggage
+```
+
+Without this, browsers (and React Native on web) will reject the preflight and the
+request will fail.
+
+### End-to-end example: RN → Node.js API
+
+```typescript
+// React Native — starts the trace
+await Sentry.startSpan({ name: "addToCart", op: "ui.action" }, async () => {
+  // This fetch will carry sentry-trace + baggage headers to api.myapp.com
+  const response = await fetch("https://api.myapp.com/cart/items", {
+    method: "POST",
+    body: JSON.stringify({ productId: "abc-123" }),
+  });
+  return response.json();
+});
+
+// Node.js backend (with @sentry/node) — automatically continues the trace
+// The backend span appears as a child in the same trace waterfall
+```
+
+```python
+# Python backend (with sentry-sdk) — also continues the trace automatically
+# No extra code needed beyond standard Sentry initialization
+```
+
+---
+
+## 10. User Interaction Tracing
+
+Captures transactions and breadcrumbs for touch events.
+Transaction names are automatically composed as `ScreenName > element_label`.
+
+### Enable
+
+```typescript
+Sentry.init({
+  dsn: "YOUR_DSN",
+  enableUserInteractionTracing: true, // disabled by default
+  tracesSampleRate: 1.0,
+  integrations: [navigationIntegration],
+});
+
+// Wrapping is required for interaction tracing to work
+export default Sentry.wrap(App);
+
+// Or with a custom label prop name:
+export default Sentry.wrap(App, {
+  touchEventBoundaryProps: { labelName: "tracking-id" }, // defaults to "sentry-label"
+});
+```
+
+### Label interactive elements
+
+```tsx
+// Without a label, no transaction is created — the tap is silently ignored
+<Pressable
+  sentry-label="add_to_cart_button"
+  onPress={handleAddToCart}
+>
+  <Text>Add to Cart</Text>
+</Pressable>
+
+// Also works on TouchableOpacity, TouchableHighlight, etc.
+<TouchableOpacity sentry-label="checkout_button" onPress={handleCheckout}>
+  <Text>Checkout</Text>
+</TouchableOpacity>
+```
+
+> Transactions with no child spans are automatically dropped — only meaningful
+> interactions are recorded.
+
+### Custom span attributes on interactions (experimental)
+
+```tsx
+<Pressable
+  sentry-label="checkout"
+  sentry-span-attributes={{
+    "user.plan": userPlan, // string
+    "cart.item_count": itemCount, // number
+    "cart.has_coupon": hasCoupon, // boolean
+  }}
+  onPress={handleCheckout}
+>
+  <Text>Checkout</Text>
+</Pressable>
+```
+
+> `sentry-span-attributes` is **experimental** — API may change.
+> The SDK traverses the component tree to find it, so it can be placed on a parent
+> element.
+
+### Gesture Handler (RNGH v2)
+
+```tsx
+import { Gesture, GestureDetector } from "react-native-gesture-handler";
+import { sentryTraceGesture } from "@sentry/react-native";
+
+function ZoomableImage() {
+  const pinch = Gesture.Pinch();
+  const longPress = Gesture.LongPress();
+
+  const gesture = Gesture.Race(
+    sentryTraceGesture("pinch-to-zoom", pinch), // label must be unique per screen
+    sentryTraceGesture("long-press-cancel", longPress),
+  );
+
+  return (
+    <GestureDetector gesture={gesture}>
+      <Image source={imageSource} />
+    </GestureDetector>
+  );
+}
+```
+
+> Only RNGH **API v2** is supported.
+> Both transactions and breadcrumbs are created automatically.
+
+---
+
+## 11. Custom Spans
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+```
+
+### `startSpan` — Active, auto-ending (recommended)
+
+The span becomes the active parent for any child spans created inside the callback.
+Ends automatically when the callback resolves (sync or async).
+
+```typescript
+// Synchronous
+const total = Sentry.startSpan({ name: "computeCartTotal", op: "function" }, () => {
+  return items.reduce((sum, item) => sum + item.price, 0);
+});
+
+// Async
+const data = await Sentry.startSpan({ name: "fetchUserProfile", op: "http.client" }, async () => {
+  const res = await fetch("https://api.example.com/profile");
+  return res.json();
+});
+
+// Nested — child spans automatically attach to their enclosing parent
+await Sentry.startSpan({ name: "checkout", op: "function" }, async () => {
+  await Sentry.startSpan({ name: "validateCart", op: "function" }, validateCart);
+  await Sentry.startSpan({ name: "processPayment", op: "function" }, processPayment);
+  await Sentry.startSpan({ name: "sendConfirmation", op: "http.client" }, sendEmail);
+});
+```
+
+### `startSpanManual` — Active, manually ended
+
+Use when the span lifetime doesn’t map cleanly to a function scope (e.g., spans across
+event callbacks):
+
+```typescript
+function trackAnimationPerformance() {
+  return Sentry.startSpanManual({ name: "heroAnimation", op: "ui.render" }, (span) => {
+    const animation = Animated.timing(translateY, {
+      toValue: 0,
+      duration: 300,
+      useNativeDriver: true,
+    });
+    animation.start(({ finished }) => {
+      span.setAttribute("animation.completed", finished);
+      span.end(); // must call end() manually
+    });
+  });
+}
+```
+
+### `startInactiveSpan` — Inactive, manually ended
+
+Inactive spans never become automatic parents for child spans.
+Use for fire-and-forget measurements:
+
+```typescript
+// Start a background sync span without it affecting the current active span
+const syncSpan = Sentry.startInactiveSpan({ name: "backgroundSync", op: "function" });
+
+await syncLocalDatabase();
+
+syncSpan.end();
+```
+
+### Span options
+
+| Option             | Type                                                   | Description                                                      |
+| ------------------ | ------------------------------------------------------ | ---------------------------------------------------------------- |
+| `name`             | `string`                                               | **Required.** Display name in Sentry UI                          |
+| `op`               | `string`                                               | Operation type — use standard values for enhanced UI (see below) |
+| `attributes`       | `Record<string, string \| number \| boolean \| array>` | Key/value metadata attached to the span                          |
+| `startTime`        | `number`                                               | Custom start timestamp (Unix epoch, seconds)                     |
+| `parentSpan`       | `Span`                                                 | Explicit parent — overrides the active span                      |
+| `onlyIfParent`     | `boolean`                                              | Skip this span if there’s no active parent                       |
+| `forceTransaction` | `boolean`                                              | Force the span to appear as a top-level transaction in the UI    |
+
+### Standard operation types for mobile
+
+Using well-known `op` values unlocks enhanced Sentry UI features (grouping, filtering,
+icons):
+
+```typescript
+Sentry.startSpan({ name: "GET /api/products", op: "http.client" }, fetchProducts);
+Sentry.startSpan({ name: "SELECT * FROM users", op: "db" }, queryDatabase);
+Sentry.startSpan({ name: "parseProductData", op: "function" }, parseData);
+Sentry.startSpan({ name: "HomeScreen render", op: "ui.render" }, render);
+Sentry.startSpan({ name: "readProductsCache", op: "file.read" }, readCache);
+Sentry.startSpan({ name: "writeOrdersCache", op: "file.write" }, writeCache);
+```
+
+Full operation list:
+[develop.sentry.dev/sdk/performance/span-operations](https://develop.sentry.dev/sdk/performance/span-operations/#list-of-operations)
+
+### Adding attributes
+
+```typescript
+// At creation time
+await Sentry.startSpan(
+  {
+    name: "loadFeed",
+    op: "http.client",
+    attributes: {
+      "feed.type": "following",
+      "feed.page": 1,
+      "feed.has_cache": false,
+    },
+  },
+  loadFeed,
+);
+
+// On an existing span
+const span = Sentry.getActiveSpan();
+if (span) {
+  span.setAttribute("result.count", 42);
+  span.setAttributes({ "filter.applied": true, "filter.type": "category" });
+  span.updateName("loadFeed:following"); // rename mid-flight
+}
+```
+
+### Span utilities
+
+```typescript
+// Get the currently active span
+const activeSpan = Sentry.getActiveSpan();
+
+// Get the root span (the transaction) from any span
+const rootSpan = activeSpan ? Sentry.getRootSpan(activeSpan) : undefined;
+
+// Explicitly set a span as the active parent for a block
+const parent = Sentry.startInactiveSpan({ name: "parent" });
+Sentry.withActiveSpan(parent, () => {
+  Sentry.startSpan({ name: "child" }, () => {
+    /* child attaches to parent */
+  });
+});
+
+// Create a root-level span regardless of current context
+Sentry.withActiveSpan(null, () => {
+  Sentry.startSpan({ name: "isolated" }, () => {
+    /* no parent */
+  });
+});
+
+// Prevent a specific operation from creating spans
+Sentry.suppressTracing(() => {
+  fetch("https://analytics.internal/ping"); // no span created for this request
+});
+```
+
+### Span hierarchy: flat vs. nested
+
+By default (mobile and browser environments), all spans are flat children of the root
+transaction to avoid async parent misattribution:
+
+```typescript
+// Default behavior — both fetches become siblings under the root, not children of their span
+await Sentry.startSpan({ name: "span1" }, async () => {
+  await fetch("https://api.example.com/a"); // child of root transaction
+});
+await Sentry.startSpan({ name: "span2" }, async () => {
+  await fetch("https://api.example.com/b"); // child of root transaction
+});
+
+// Opt into full nesting (may cause incorrect parent attribution with async/await)
+Sentry.init({ parentSpanIsAlwaysRootSpan: false });
+```
+
+---
+
+## 12. React Component Profiler
+
+Track individual React component lifecycle (mount, update, unmount) as child spans
+within the current route transaction.
+Useful for identifying slow renders and unnecessary re-renders.
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+
+// Wrap any component with withProfiler
+const ProductCard = Sentry.withProfiler(({ product }) => {
+  return <View>{/* component content */}</View>;
+});
+
+// Or wrap the export
+export default Sentry.withProfiler(HeavyListScreen);
+```
+
+Profiler spans show up in the transaction waterfall under `ui.react.render` and
+`ui.react.update` operations.
+
+> **Production builds warning:** React Native minifies class/function names in
+> production. Configure the Sentry Gradle/Xcode plugin + source maps to preserve
+> component names in production profiler data.
+> See the SDK
+> [source maps guide](https://docs.sentry.io/platforms/react-native/sourcemaps/).
+
+---
+
+## 13. Profiling (Native + Hermes)
+
+Profiling samples the call stack at regular intervals to surface hot code paths.
+Requires tracing to be enabled first — only traced transactions are profiled.
+
+**Minimum SDK version:** `5.32.0`
+
+### Basic setup
+
+`profilesSampleRate` is **relative to `tracesSampleRate`** — a transaction must first be
+sampled for tracing before profiling applies:
+
+```typescript
+Sentry.init({
+  dsn: "YOUR_DSN",
+
+  tracesSampleRate: 1.0, // 100% traced
+  profilesSampleRate: 1.0, // 100% of traced → 100% profiled (dev/testing only)
+
+  // Production example:
+  // tracesSampleRate: 0.2,    // 20% traced
+  // profilesSampleRate: 0.5,  // 50% of those → 10% of all transactions profiled
+});
+```
+
+### Hermes + native platform profilers
+
+By default both layers are profiled simultaneously:
+
+1. **Hermes profiler** — JavaScript code executing in the Hermes engine
+2. **Platform profilers** — native code (Swift/ObjC on iOS, Kotlin/Java on Android)
+
+Control with `hermesProfilingIntegration`:
+
+```typescript
+Sentry.init({
+  dsn: "YOUR_DSN",
+  tracesSampleRate: 1.0,
+  profilesSampleRate: 1.0,
+  integrations: [
+    Sentry.hermesProfilingIntegration({
+      platformProfilers: true, // default: true — profile native code alongside JS
+      // Set false to profile ONLY JS (Hermes) without native code (SDK ≥ 5.33.0)
+    }),
+  ],
+});
+```
+
+### UI Profiling (experimental)
+
+Continuous profiling tied to the app lifecycle rather than individual transactions.
+Useful for catching performance issues that span multiple transactions.
+
+```typescript
+Sentry.init({
+  dsn: "YOUR_DSN",
+  tracesSampleRate: 1.0,
+
+  _experiments: {
+    profilingOptions: {
+      profileSessionSampleRate: 1.0, // fraction of app sessions to profile
+      lifecycle: "trace", // "trace" = profile only during active transactions
+      startOnAppStart: true, // begin profiling from the very first frame
+    },
+  },
+});
+```
+
+> `androidProfilingOptions` is **deprecated** — use `profilingOptions` inside
+> `_experiments` instead.
+
+### Profiling version requirements
+
+| Feature                      | Min SDK                            | Platforms    |
+| ---------------------------- | ---------------------------------- | ------------ |
+| `profilesSampleRate` (basic) | `5.32.0`                           | iOS, Android |
+| `platformProfilers: false`   | `5.33.0`                           | iOS, Android |
+| UI Profiling (experimental)  | `7.9.0` (Android) · `7.12.0` (iOS) | iOS, Android |
+
+---
+
+## 14. Dynamic Sampling
+
+`tracesSampler` gives you full control over sampling based on transaction properties at
+the time the trace starts.
+
+```typescript
+Sentry.init({
+  dsn: "YOUR_DSN",
+
+  tracesSampler: ({ name, attributes, parentSampled }) => {
+    // Always sample critical user flows
+    if (name === "checkout" || name === "PaymentScreen") {
+      return 1.0;
+    }
+
+    // Never sample health checks
+    if (name.includes("HealthCheck")) {
+      return 0;
+    }
+
+    // Respect parent sampling decision for distributed traces
+    // (keeps frontend + backend in the same trace or both dropped)
+    if (parentSampled !== undefined) {
+      return parentSampled ? 1.0 : 0;
+    }
+
+    // Default: sample 10%
+    return 0.1;
+  },
+});
+```
+
+### Head-based vs. tail-based sampling
+
+| Approach                                              | How                                             | Tradeoff                                                         |
+| ----------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------- |
+| **Head-based** (`tracesSampleRate` / `tracesSampler`) | Decision made at trace start                    | Low overhead, but can’t sample based on outcome                  |
+| **Tail-based** (Sentry Dynamic Sampling rules)        | Decision made server-side after trace completes | Can prioritize errors/slow traces, requires Sentry Business plan |
+
+For most React Native apps, head-based sampling with a `tracesSampler` is sufficient.
+
+---
+
+## 15. Configuration Reference
+
+### `Sentry.init` options
+
+| Option                         | Type                   | Default            | Description                                                   |
+| ------------------------------ | ---------------------- | ------------------ | ------------------------------------------------------------- |
+| `tracesSampleRate`             | `number` (0–1)         | `undefined`        | Uniform transaction sample rate                               |
+| `tracesSampler`                | `function`             | `undefined`        | Dynamic sampler — overrides `tracesSampleRate` when set       |
+| `profilesSampleRate`           | `number` (0–1)         | `undefined`        | Profile sample rate, relative to traced transactions          |
+| `tracePropagationTargets`      | `(string \| RegExp)[]` | `[/.*/]` on mobile | URLs/patterns that receive `sentry-trace` + `baggage` headers |
+| `enableUserInteractionTracing` | `boolean`              | `false`            | Capture touch interaction transactions                        |
+| `enableAutoPerformanceTracing` | `boolean`              | `true`             | Master switch for all automatic instrumentation               |
+| `parentSpanIsAlwaysRootSpan`   | `boolean`              | `true`             | Flat span hierarchy — safe for async/await contexts           |
+
+### `reactNativeTracingIntegration` options
+
+| Option                       | Type                   | Default   | Description                                              |
+| ---------------------------- | ---------------------- | --------- | -------------------------------------------------------- |
+| `beforeStartSpan`            | `(context) => context` | —         | Mutate span context before each navigation/pageload span |
+| `shouldCreateSpanForRequest` | `(url) => boolean`     | —         | Filter which outgoing requests get a span                |
+| `idleTimeoutMs`              | `number`               | `1_000`   | Ms of inactivity before ending the current transaction   |
+| `finalTimeoutMs`             | `number`               | `600_000` | Hard maximum duration for any single transaction         |
+
+### `reactNavigationIntegration` options
+
+| Option                                  | Type      | Default | Description                                                  |
+| --------------------------------------- | --------- | ------- | ------------------------------------------------------------ |
+| `enableTimeToInitialDisplay`            | `boolean` | `false` | Auto-measure TTID per screen                                 |
+| `routeChangeTimeoutMs`                  | `number`  | `1_000` | Discard transaction if screen doesn’t mount within this time |
+| `ignoreEmptyBackNavigationTransactions` | `boolean` | `true`  | Drop back-nav transactions with no child spans               |
+| `useDispatchedActionData`               | `boolean` | `false` | Include navigation action data in transaction metadata       |
+
+### `reactNativeNavigationIntegration` options (Wix RNN)
+
+| Option                                  | Type         | Default      | Description                         |
+| --------------------------------------- | ------------ | ------------ | ----------------------------------- |
+| `navigation`                            | `Navigation` | **required** | The RNN Navigation object           |
+| `routeChangeTimeoutMs`                  | `number`     | `1_000`      | Discard stale transactions          |
+| `enableTabsInstrumentation`             | `boolean`    | `false`      | Create transactions on tab switches |
+| `ignoreEmptyBackNavigationTransactions` | `boolean`    | `true`       | Drop no-span back navigations       |
+
+### `hermesProfilingIntegration` options
+
+| Option              | Type      | Default | Description                                                 |
+| ------------------- | --------- | ------- | ----------------------------------------------------------- |
+| `platformProfilers` | `boolean` | `true`  | Profile native (Swift/ObjC/Kotlin/Java) alongside Hermes JS |
+
+---
+
+## 16. Mobile vs Web: Feature Matrix
+
+| Capability                     | Web SDK          | React Native SDK                                       |
+| ------------------------------ | ---------------- | ------------------------------------------------------ |
+| App cold start tracking        | ❌               | ✅ `measurements.app_start_cold`                       |
+| App warm start tracking        | ❌               | ✅ `measurements.app_start_warm`                       |
+| Slow frames (Mobile Vital)     | ❌               | ✅ Auto (requires `reactNativeTracingIntegration`)     |
+| Frozen frames (Mobile Vital)   | ❌               | ✅ Auto (requires `reactNativeTracingIntegration`)     |
+| JS event loop stall tracking   | ❌               | ✅ Auto (3 metrics: count, longest, total)             |
+| Time to Initial Display (TTID) | ❌               | ✅ `enableTimeToInitialDisplay: true`                  |
+| Time to Full Display (TTFD)    | ❌               | ✅ `<Sentry.TimeToFullDisplay record={...} />`         |
+| Touch interaction tracing      | ❌               | ✅ `enableUserInteractionTracing: true`                |
+| Gesture tracing (RNGH v2)      | ❌               | ✅ `sentryTraceGesture()`                              |
+| Hermes JS profiling            | ❌               | ✅ `profilesSampleRate` + `hermesProfilingIntegration` |
+| Native platform profiling      | ❌               | ✅ `platformProfilers: true`                           |
+| Navigation transactions        | ✅ (SPA routers) | ✅ React Navigation · Expo Router · RNN                |
+| Network span tracing           | ✅               | ✅ fetch + XHR auto-instrumented                       |
+| Distributed tracing            | ✅               | ✅ `tracePropagationTargets`                           |
+| Web Vitals (LCP, FID, CLS)     | ✅               | ❌ (replaced by Mobile Vitals)                         |
+
+---
+
+## 17. Troubleshooting
+
+| Issue                                        | Cause                                            | Solution                                                                                   |
+| -------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| No transactions in Sentry                    | Tracing not enabled                              | Add `tracesSampleRate` > 0 and `reactNativeTracingIntegration()` to `integrations`         |
+| App Start span missing                       | `Sentry.wrap(App)` not used                      | Wrap root component: `export default Sentry.wrap(App)`                                     |
+| App Start time seems too long                | Sentry follows platform vendor guidelines        | Expected — Sentry measures the full user-perceptible start time, not internal JS init      |
+| Navigation transactions not created          | Integration not registered                       | Call `navigationIntegration.registerNavigationContainer(ref)` inside `onReady`, not before |
+| TTID/TTFD not appearing                      | Feature not enabled or wrong SDK version         | Requires `enableTimeToInitialDisplay: true` and SDK ≥ 5.20.0, native build required        |
+| TTID not firing on tab screens               | Tab screens are preloaded                        | Add `<Sentry.TimeToInitialDisplay record={true} />` explicitly to each tab screen          |
+| No interaction transactions                  | Missing `sentry-label` prop                      | Add `sentry-label="my_button"` to every interactive element you want to track              |
+| `sentry-trace` header missing from requests  | `tracePropagationTargets` doesn’t match URL      | Check the full URL against your patterns — it matches against the entire URL string        |
+| Backend receives header but trace not linked | Backend SDK not initialized                      | Ensure your backend uses a Sentry SDK with distributed tracing support                     |
+| Slow/frozen frames missing on Android        | Missing `androidx.core`                          | Don’t exclude `androidx.core` from the Sentry Android dependency                           |
+| Profiling data not appearing                 | Profiling sample rate is 0 or traces not sampled | `profilesSampleRate` is relative to `tracesSampleRate` — both must be > 0                  |
+| Component names minified in profiler         | Production bundle minification                   | Configure Sentry Gradle/Xcode plugins and upload source maps                               |
+| Gesture spans not appearing                  | Wrong RNGH version                               | Only RNGH API v2 is supported — upgrade `react-native-gesture-handler`                     |
+| Stall metrics missing                        | `reactNativeTracingIntegration` not added        | Stall tracking requires the integration — add it to `integrations: []`                     |
+| Transactions never finish                    | No idle timeout / long background spans          | Adjust `idleTimeoutMs` in `reactNativeTracingIntegration` options                          |