@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/sdks/nextjs/tracing.md

@@ -0,0 +1,628 @@
+# Tracing — Sentry Next.js SDK
+
+> Minimum SDK: `@sentry/nextjs` ≥8.0.0\
+> `withServerActionInstrumentation`: ≥8.0.0\
+> `enableLongAnimationFrame`: ≥8.18.0\
+> `ignoreSpans`: ≥10.2.0
+
+---
+
+## How Tracing Is Activated
+
+Tracing is enabled by setting **`tracesSampleRate`** or **`tracesSampler`** in all three
+runtime config files.
+Without one of these, no spans are created.
+
+| Config file                 | Runtime | What it traces                                                 |
+| --------------------------- | ------- | -------------------------------------------------------------- |
+| `instrumentation-client.ts` | Browser | Page loads, navigations, fetch/XHR, Web Vitals, INP            |
+| `sentry.server.config.ts`   | Node.js | API routes, RSC renders, `getServerSideProps`, background work |
+| `sentry.edge.config.ts`     | Edge    | Next.js middleware                                             |
+
+> ⚠️ **All three must have tracing configured.** Missing one means that runtime produces
+> no spans.
+
+---
+
+## `tracesSampleRate` — Uniform Sampling
+
+A number between `0.0` and `1.0`. Set the same option in all three configs:
+
+```typescript
+// Recommended: 100% in development, lower in production
+tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
+```
+
+> **To disable tracing entirely:** omit both `tracesSampleRate` and `tracesSampler`.
+> Setting `tracesSampleRate: 0` is not the same — it still activates instrumentation but
+> sends nothing.
+
+---
+
+## `tracesSampler` — Dynamic Per-Request Sampling
+
+When defined, `tracesSampler` takes **precedence** over `tracesSampleRate`. Receives a
+`SamplingContext` and returns a number (0–1) or boolean.
+
+```typescript
+// TypeScript: SamplingContext shape
+interface SamplingContext {
+  name: string; // e.g. "GET /api/users"
+  attributes: SpanAttributes | undefined;
+  parentSampled: boolean | undefined; // parent's sampling decision
+  parentSampleRate: number | undefined;
+  inheritOrSampleWith: (fallbackRate: number) => number;
+}
+```
+
+### Route-Based Sampling
+
+```typescript
+Sentry.init({
+  tracesSampler: ({ name, inheritOrSampleWith }) => {
+    // Always drop health checks
+    if (name.includes("/health") || name.includes("/ping")) return 0;
+
+    // Always sample critical flows
+    if (name.includes("/checkout") || name.includes("/payment")) return 1.0;
+
+    // Sample admin routes at 50%
+    if (name.includes("/admin")) return 0.5;
+
+    // For everything else: honor parent's decision, fall back to 10%
+    return inheritOrSampleWith(0.1);
+  },
+});
+```
+
+### With Parent Trace Inheritance
+
+```typescript
+Sentry.init({
+  tracesSampler: ({ name, parentSampled, inheritOrSampleWith }) => {
+    if (name.includes("healthcheck")) return 0;
+    if (name.includes("auth")) return 1;
+    // inheritOrSampleWith: respects parent decision if present, else uses fallback
+    return inheritOrSampleWith(0.5);
+  },
+});
+```
+
+**Why use `inheritOrSampleWith` instead of checking `parentSampled` directly?**\
+It ensures consistent rates flow through distributed traces, enables accurate metric
+extrapolation, and sets the correct `sentry-sampled` value in downstream `baggage`.
+
+### Sampling Precedence
+
+1. `tracesSampler` function (if defined) — evaluated first
+2. Parent’s sampling decision (propagated via `sentry-trace` header)
+3. `tracesSampleRate` (uniform fallback)
+
+---
+
+## Auto-Instrumented Operations
+
+### Client-Side (Browser)
+
+| Operation              | Op                        | What’s captured                                           |
+| ---------------------- | ------------------------- | --------------------------------------------------------- |
+| Initial page load      | `pageload`                | LCP, CLS, FCP, TTFB Web Vitals; resource load child spans |
+| Client-side navigation | `navigation`              | Route change duration; child fetch/XHR spans              |
+| `fetch()` requests     | `http.client`             | URL, method, status code, duration, HTTP timings          |
+| `XMLHttpRequest`       | `http.client`             | Same as fetch                                             |
+| User interactions      | `ui.interaction`          | INP (Interaction to Next Paint) — emitted on page hide    |
+| Long Tasks (> 50ms)    | `ui.long-task`            | Main-thread blocking events                               |
+| Long Animation Frames  | `ui.long-animation-frame` | LoAF rendering work — SDK ≥8.18.0                         |
+
+### Server-Side (Node.js)
+
+| Operation                         | Op            | Notes                                    |
+| --------------------------------- | ------------- | ---------------------------------------- |
+| API route handlers (App Router)   | `http.server` | `app/api/*/route.ts` — auto-instrumented |
+| API route handlers (Pages Router) | `http.server` | `pages/api/*.ts` — auto-instrumented     |
+| React Server Components           | `http.server` | RSC render times                         |
+| `getServerSideProps`              | `http.server` | Pages Router SSR data fetching           |
+| Edge Middleware                   | `http.server` | Via `sentry.edge.config.ts`              |
+
+> ⚠️ **Server Actions are NOT auto-instrumented.** Wrap each with
+> `withServerActionInstrumentation()` — see below.
+
+---
+
+## `browserTracingIntegration` Options
+
+```typescript
+// instrumentation-client.ts
+Sentry.init({
+  integrations: [
+    Sentry.browserTracingIntegration({
+      // Page Load & Navigation
+      instrumentPageLoad: true, // default: true
+      instrumentNavigation: true, // default: true
+
+      // HTTP spans
+      traceFetch: true, // default: true
+      traceXHR: true, // default: true
+      enableHTTPTimings: true, // default: true
+      shouldCreateSpanForRequest: (url) => !url.includes("/health"),
+
+      // Performance observations
+      enableLongTask: true, // default: true
+      enableLongAnimationFrame: true, // default: true (SDK ≥8.18.0)
+      enableInp: true, // INP spans
+
+      // Span lifecycle
+      idleTimeout: 1000, // ms: wait after last child before ending
+      finalTimeout: 30000, // ms: hard cap on span duration
+      childSpanTimeout: 15000, // ms: max time for child spans
+
+      // Span naming — parameterize URLs
+      beforeStartSpan: (context) => ({
+        ...context,
+        name: context.name.replace(/\/\d+/g, "/<id>"),
+      }),
+
+      // Span filtering
+      ignoreResourceSpans: ["resource.css", "resource.script", "resource.img"],
+    }),
+  ],
+});
+```
+
+---
+
+## Custom Spans
+
+### `Sentry.startSpan()` — Active, Auto-Ending (Recommended)
+
+Wraps a block of work.
+The span becomes active (children nest under it) and ends automatically when the
+callback returns or resolves:
+
+```typescript
+// Async
+const data = await Sentry.startSpan(
+  {
+    name: "fetchUserProfile",
+    op: "http.client",
+    attributes: { "user.id": userId, "cache.hit": false },
+  },
+  async () => {
+    const res = await fetch(`/api/users/${userId}`);
+    return res.json();
+  },
+);
+
+// Sync
+const result = Sentry.startSpan({ name: "computeRecommendations", op: "function" }, () =>
+  expensiveComputation(),
+);
+```
+
+### Nested Spans (Parent–Child Hierarchy)
+
+```typescript
+await Sentry.startSpan({ name: "checkout-flow", op: "function" }, async () => {
+  // These are automatically children of "checkout-flow"
+  const cart = await Sentry.startSpan({ name: "fetchCart", op: "db.query" }, () =>
+    db.cart.findUnique({ where: { userId } }),
+  );
+
+  const payment = await Sentry.startSpan({ name: "processPayment", op: "http.client" }, () =>
+    stripe.paymentIntents.create({ amount: cart.total }),
+  );
+
+  return { cart, payment };
+});
+```
+
+### `Sentry.startSpanManual()` — Active, Manual End
+
+Use when the span lifetime cannot be enclosed in a callback:
+
+```typescript
+function authMiddleware(req: Request, res: Response, next: NextFunction) {
+  return Sentry.startSpanManual({ name: "auth.verify", op: "middleware" }, (span) => {
+    res.once("finish", () => {
+      span.setStatus({ code: res.statusCode < 400 ? 1 : 2 });
+      span.end(); // ← required
+    });
+    return next();
+  });
+}
+```
+
+### `Sentry.startInactiveSpan()` — Not Active, Manual End
+
+Creates a span that is **never** automatically made active.
+Use for parallel work or event-based tracking:
+
+```typescript
+// Parallel independent operations
+const spanA = Sentry.startInactiveSpan({ name: "operation-a" });
+const spanB = Sentry.startInactiveSpan({ name: "operation-b" });
+
+await Promise.all([doA(), doB()]);
+
+spanA.end();
+spanB.end();
+
+// Explicit parent assignment
+const parent = Sentry.startInactiveSpan({ name: "parent" });
+const child = Sentry.startInactiveSpan({ name: "child", parentSpan: parent });
+child.end();
+parent.end();
+```
+
+### Browser: `setActiveSpanInBrowser()` — Persistent Active Span
+
+When a callback-based API isn’t practical (e.g., UI event handlers), keep a span active
+across event calls. Available since SDK v10.15.0:
+
+```typescript
+let checkoutSpan: Sentry.Span | undefined;
+
+onCheckoutStart(() => {
+  checkoutSpan = Sentry.startInactiveSpan({ name: "checkout-flow" });
+  Sentry.setActiveSpanInBrowser(checkoutSpan);
+});
+
+onCheckoutComplete(() => {
+  checkoutSpan?.end();
+});
+```
+
+> ⚠️ `setActiveSpanInBrowser` is **browser-only**.
+
+---
+
+## Span Options Reference
+
+```typescript
+interface StartSpanOptions {
+  name: string; // Required: label shown in the UI
+  op?: string; // Operation category (see table below)
+  attributes?: Record<string, string | number | boolean>;
+  parentSpan?: Span; // Override automatic parent
+  onlyIfParent?: boolean; // Skip span if no active parent exists
+  forceTransaction?: boolean; // Force display as root transaction in UI
+  startTime?: number; // Unix timestamp in seconds
+}
+```
+
+**Common `op` values:**
+
+| `op`                              | Use for                                  |
+| --------------------------------- | ---------------------------------------- |
+| `http.client`                     | Outgoing HTTP requests (fetch, XHR)      |
+| `http.server`                     | Incoming HTTP requests (API routes, SSR) |
+| `db` / `db.query`                 | Database queries                         |
+| `db.redis`                        | Redis operations                         |
+| `function`                        | General function calls                   |
+| `ui.render`                       | Component render time                    |
+| `ui.action.click`                 | Click event handling                     |
+| `cache.get` / `cache.put`         | Cache reads/writes                       |
+| `queue.publish` / `queue.process` | Message queue operations                 |
+| `task`                            | Background / scheduled work              |
+
+---
+
+## Span Enrichment
+
+```typescript
+// Set attributes on the currently active span
+const span = Sentry.getActiveSpan();
+if (span) {
+  span.setAttribute("db.table", "users");
+  span.setAttributes({
+    "http.method": "POST",
+    "order.total": 99.99,
+    "user.tier": "premium",
+  });
+
+  // Status: 0=unset, 1=ok, 2=error
+  span.setStatus({ code: 1 });
+  span.setStatus({ code: 2, message: "Payment declined" });
+}
+
+// Rename a span at runtime
+const span = Sentry.getActiveSpan();
+if (span) Sentry.updateSpanName(span, "GET /users/:id");
+
+// Modify all spans globally before sending
+Sentry.init({
+  beforeSendSpan(span) {
+    span.data = {
+      ...span.data,
+      "deployment.region": process.env.AWS_REGION ?? "unknown",
+    };
+    return span; // return null to drop (but prefer ignoreSpans for that)
+  },
+});
+```
+
+---
+
+## Server Actions — `withServerActionInstrumentation()`
+
+Server Actions are not auto-instrumented.
+Wrap each with `withServerActionInstrumentation()`:
+
+```typescript
+// app/actions/order.ts
+"use server";
+import * as Sentry from "@sentry/nextjs";
+import { headers } from "next/headers";
+
+export async function createOrder(formData: FormData) {
+  return Sentry.withServerActionInstrumentation(
+    "createOrder", // Action name (becomes span name)
+    {
+      headers: await headers(), // Enables distributed trace continuation
+      formData, // Logged as span data
+      recordResponse: true, // Capture the return value
+    },
+    async () => {
+      const order = await db.orders.create({
+        data: { items: formData.get("items"), userId: getCurrentUser() },
+      });
+      return { success: true, orderId: order.id };
+    },
+  );
+}
+```
+
+**Options:**
+
+| Option           | Type       | Description                                                                 |
+| ---------------- | ---------- | --------------------------------------------------------------------------- |
+| `formData`       | `FormData` | Logged with the span                                                        |
+| `headers`        | `Headers`  | Required for distributed trace continuation — always pass `await headers()` |
+| `recordResponse` | `boolean`  | Whether to capture the return value as span data                            |
+
+---
+
+## Distributed Tracing
+
+### How It Works
+
+Sentry injects two HTTP headers into outgoing requests:
+
+| Header         | Format                           | Purpose                              |
+| -------------- | -------------------------------- | ------------------------------------ |
+| `sentry-trace` | `{traceId}-{spanId}-{sampled}`   | Carries trace context                |
+| `baggage`      | W3C Baggage with `sentry-*` keys | Carries sampling decision + metadata |
+
+Backends must allowlist these headers for CORS:
+
+```
+Access-Control-Allow-Headers: sentry-trace, baggage
+```
+
+### `tracePropagationTargets`
+
+Controls which outgoing requests get trace headers.
+Accepts strings (substring match) and/or RegExp:
+
+```typescript
+// instrumentation-client.ts
+Sentry.init({
+  tracePropagationTargets: [
+    "localhost", // any URL containing "localhost"
+    /^https:\/\/api\.yourapp\.com/, // your API
+    /^https:\/\/auth\.yourapp\.com/, // auth service
+    /^\//, // all same-origin relative paths
+  ],
+});
+```
+
+**Default:** `['localhost', /^\//]` — only localhost and same-origin requests.\
+**Disable entirely:** `tracePropagationTargets: []`
+
+> ⚠️ If your API is at `http://localhost:3001`, use `"localhost:3001"` or a regex
+> matching the port — `"localhost"` alone won’t match.
+
+### Automatic SSR → Client Trace Continuation
+
+When Next.js server-renders a page, Sentry emits trace context as `<meta>` tags in
+`<head>`. The browser SDK reads them automatically to continue the same trace:
+
+```html
+<!-- Auto-injected by Next.js SDK — no configuration needed -->
+<meta name="sentry-trace" content="12345678...-1234567890123456-1" />
+<meta name="baggage" content="sentry-trace_id=12345678...,sentry-sample_rate=0.1,..." />
+```
+
+This means a single distributed trace spans the server render **and** subsequent
+client-side activity.
+
+### Manual Trace Propagation (Non-HTTP Channels)
+
+For WebSockets, message queues, or other protocols:
+
+```typescript
+// Sender — extract current trace context
+const traceData = Sentry.getTraceData();
+// Returns: { "sentry-trace": "...", "baggage": "..." }
+
+webSocket.send(
+  JSON.stringify({
+    payload: myData,
+    _sentryMeta: {
+      sentryTrace: traceData["sentry-trace"],
+      baggage: traceData["baggage"],
+    },
+  }),
+);
+
+// Receiver — continue the trace
+const { sentryTrace, baggage } = message._sentryMeta;
+
+Sentry.continueTrace({ sentryTrace, baggage }, () => {
+  return Sentry.startSpan({ name: "handleWebSocketMessage" }, () => {
+    processMessage(message);
+  });
+});
+```
+
+### Head-Based Sampling
+
+The originating (head) service makes the sampling decision.
+That decision propagates to all downstream services via `sentry-trace`. All services
+either all sample or all drop the trace — ensuring complete traces, never partial ones.
+
+---
+
+## Advanced Span APIs
+
+### `continueTrace()` — Continue Incoming Trace
+
+```typescript
+// When receiving trace headers from a message queue, cron trigger, etc.
+Sentry.continueTrace(
+  {
+    sentryTrace: incomingHeaders["sentry-trace"],
+    baggage: incomingHeaders["baggage"],
+  },
+  () => {
+    return Sentry.startSpan({ name: "processJob", op: "function" }, () => doWork());
+  },
+);
+```
+
+### `startNewTrace()` — Force a New Trace
+
+```typescript
+// Break the distributed chain — start a completely independent trace
+Sentry.startNewTrace(() => {
+  return Sentry.startSpan({ name: "isolated-operation" }, () => doWork());
+});
+```
+
+### `suppressTracing()` — Prevent Span Capture
+
+```typescript
+// Prevent spans inside this callback from being sent to Sentry
+const result = Sentry.suppressTracing(() => {
+  return fetch("/internal/health"); // No span created
+});
+```
+
+### `getActiveSpan()`, `getRootSpan()`
+
+```typescript
+const span = Sentry.getActiveSpan();
+if (span) {
+  span.setAttribute("custom.key", "value");
+  const root = Sentry.getRootSpan(span);
+  console.log(Sentry.spanToJSON(root).name);
+}
+```
+
+### `withActiveSpan()` — Run Code with a Specific Active Span
+
+```typescript
+const mySpan = Sentry.startInactiveSpan({ name: "background-task" });
+
+await Sentry.withActiveSpan(mySpan, async (scope) => {
+  scope.setTag("task.type", "email");
+  await sendEmails(); // Errors associate with mySpan
+});
+
+mySpan.end();
+```
+
+### `forceTransaction` and `onlyIfParent`
+
+```typescript
+// Forces span to appear as root transaction in Sentry UI
+Sentry.startSpan({ name: "background-job", op: "function", forceTransaction: true }, () =>
+  runBackgroundJob(),
+);
+
+// Only creates span when an active parent exists (drops orphan spans)
+Sentry.startSpan({ name: "optional-metric", onlyIfParent: true }, () => measureSomething());
+```
+
+### Browser Flat Span Hierarchy
+
+In browsers, all child spans are attached flat to the root span by default.
+To opt into true nesting (use with care — can produce incorrect data with concurrent
+async operations):
+
+```typescript
+Sentry.init({
+  parentSpanIsAlwaysRootSpan: false,
+});
+```
+
+---
+
+## Complete Config Example (All Three Runtimes)
+
+```typescript
+// instrumentation-client.ts (Browser)
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+  environment: process.env.NODE_ENV,
+
+  integrations: [
+    Sentry.browserTracingIntegration({
+      shouldCreateSpanForRequest: (url) => !url.match(/\/health$/),
+    }),
+  ],
+
+  tracesSampler: ({ name, inheritOrSampleWith }) => {
+    if (name.includes("health")) return 0;
+    if (name.includes("/checkout")) return 1.0;
+    return inheritOrSampleWith(0.1);
+  },
+
+  tracePropagationTargets: ["localhost", /^https:\/\/api\.myapp\.com/],
+});
+```
+
+```typescript
+// sentry.server.config.ts (Node.js)
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  environment: process.env.NODE_ENV,
+
+  tracesSampler: ({ name, inheritOrSampleWith }) => {
+    if (name.includes("healthcheck")) return 0;
+    return inheritOrSampleWith(0.1);
+  },
+});
+```
+
+```typescript
+// sentry.edge.config.ts (Edge)
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  tracesSampleRate: 0.1,
+});
+```
+
+---
+
+## Troubleshooting
+
+| Issue                                            | Solution                                                                                                                  |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| No transactions in Performance dashboard         | Verify `tracesSampleRate` or `tracesSampler` is set; confirm it’s set in all three runtime configs                        |
+| Server Actions not traced                        | Wrap each with `withServerActionInstrumentation()`; it’s not auto-instrumented                                            |
+| Distributed trace not linking frontend → backend | Add backend URL to `tracePropagationTargets`; verify `Access-Control-Allow-Headers: sentry-trace, baggage` on the backend |
+| SSR page load not linked to server trace         | This is automatic — verify both client and server use the same DSN                                                        |
+| API requests missing `sentry-trace` header       | Check CORS preflight — backend must allow `sentry-trace` and `baggage`                                                    |
+| Transaction names show raw URLs (`/users/42`)    | Use `beforeStartSpan` to parameterize: replace `/\d+/g` with `/<id>`                                                      |
+| `tracesSampler` not working                      | When both `tracesSampler` and `tracesSampleRate` are set, `tracesSampler` wins — expected behavior                        |
+| Spans missing after async gap (browser)          | Browser uses flat hierarchy; use `startInactiveSpan` with explicit `parentSpan` across async boundaries                   |
+| `tracePropagationTargets` port not matching      | `"localhost"` won’t match `localhost:3001` — use `"localhost:3001"` or a regex                                            |
+| High transaction volume                          | Use `tracesSampler` to return `0` for health checks; lower default rate with `inheritOrSampleWith(0.02)`                  |
+| Server-only spans not appearing                  | Verify `instrumentation.ts` exports `onRequestError = Sentry.captureRequestError` and loads the server config             |