@danieljvdm/dev-kit 1.0.2 → 2.0.0

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

@@ -0,0 +1,411 @@
+# Metrics — Sentry Next.js SDK
+
+> Minimum SDK: `@sentry/nextjs` ≥10.25.0 (stable `Sentry.metrics.*` API)\
+> `enableMetrics` top-level option: ≥10.24.0 (default: `true`)\
+> `beforeSendMetric` hook: ≥10.24.0\
+> Scope attributes on metrics: ≥10.33.0
+>
+> Available in **all three runtimes**: browser, Node.js server, and Edge.
+
+---
+
+## Overview
+
+Sentry Metrics let you track counters, current values, and value distributions.
+They appear in Sentry alongside related errors and can be correlated with traces.
+
+Key characteristics:
+
+- Metrics are **enabled by default** — no configuration required for basic use
+- Work across all three Next.js runtimes: browser, Node.js server, and Edge
+- Buffered in memory (max 1000 entries) and sent periodically
+- High-cardinality attributes **degrade backend performance** — keep attribute
+  cardinality low
+- Use `Sentry.logger.*` (not metrics) when you need per-user or per-request detail
+
+---
+
+## Initialization
+
+Metrics are on by default in all three runtime config files.
+No additional configuration is needed.
+`enableMetrics`, `beforeSendMetric`, and all `Sentry.metrics.*` calls work identically
+in every runtime.
+
+**`instrumentation-client.ts` (browser runtime):**
+
+```typescript
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+  // Metrics are enabled by default — no config needed
+
+  // To disable entirely:
+  // enableMetrics: false,
+
+  beforeSendMetric: (metric) => {
+    // optional filter/transform
+    if (metric.name === "debug_metric") return null;
+    return metric;
+  },
+});
+```
+
+**`sentry.server.config.ts` (Node.js runtime):**
+
+```typescript
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  // Metrics are enabled by default
+  // enableMetrics, beforeSendMetric can be configured here too
+});
+```
+
+**`sentry.edge.config.ts` (Edge runtime):**
+
+```typescript
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  // Metrics are enabled by default
+  // enableMetrics, beforeSendMetric can be configured here too
+});
+```
+
+---
+
+## Metrics API
+
+Three methods. No `increment()` or `set()` — those do not exist in v10:
+
+```typescript
+Sentry.metrics.count(name, value?, options?)
+Sentry.metrics.gauge(name, value, options?)
+Sentry.metrics.distribution(name, value, options?)
+```
+
+**Full TypeScript signatures:**
+
+```typescript
+interface MetricOptions {
+  unit?: string; // see unit table below
+  attributes?: Record<string, unknown>; // filterable dimensions
+  scope?: Scope; // optional scope override
+}
+
+function count(name: string, value?: number, options?: MetricOptions): void;
+// value defaults to 1
+
+function gauge(name: string, value: number, options?: MetricOptions): void;
+
+function distribution(name: string, value: number, options?: MetricOptions): void;
+```
+
+---
+
+## Metric Types
+
+| Method         | Underlying Type | Use For                                         |
+| -------------- | --------------- | ----------------------------------------------- |
+| `count`        | counter         | Event frequency — requests, errors, signups     |
+| `gauge`        | gauge           | Current snapshot value — queue depth, CPU %     |
+| `distribution` | distribution    | Value histograms/ranges — latencies, file sizes |
+
+```typescript
+// count — how many times something happened
+Sentry.metrics.count("user.signups", 1);
+Sentry.metrics.count("api.errors", 1, { attributes: { endpoint: "/checkout" } });
+
+// gauge — what the current state is
+Sentry.metrics.gauge("queue.depth", 42);
+Sentry.metrics.gauge("memory.usage", 512, { unit: "megabyte" });
+
+// distribution — spread of a measured value
+Sentry.metrics.distribution("api.latency", 187.5, { unit: "millisecond" });
+Sentry.metrics.distribution("payload.size", 1024, { unit: "byte" });
+```
+
+---
+
+## Next.js Patterns
+
+### API Routes (App Router)
+
+Track request timing and business events in route handlers:
+
+**`app/api/orders/route.ts`**
+
+```typescript
+import * as Sentry from "@sentry/nextjs";
+
+export async function POST(request: Request) {
+  const start = Date.now();
+
+  try {
+    const order = await createOrder(request);
+
+    Sentry.metrics.count("orders_created", 1, {
+      attributes: { status: "success" },
+    });
+
+    return Response.json(order);
+  } catch (error) {
+    Sentry.metrics.count("orders_created", 1, {
+      attributes: { status: "failed" },
+    });
+    throw error;
+  } finally {
+    Sentry.metrics.distribution("order_latency", Date.now() - start, {
+      unit: "millisecond",
+    });
+  }
+}
+```
+
+### Server Actions
+
+Track form submissions and mutations:
+
+**`app/actions.ts`**
+
+```typescript
+"use server";
+
+import * as Sentry from "@sentry/nextjs";
+
+export async function submitCheckout(formData: FormData) {
+  Sentry.metrics.count("checkout_attempts", 1);
+
+  try {
+    const result = await processCheckout(formData);
+    Sentry.metrics.count("checkout_success", 1);
+    return result;
+  } catch (error) {
+    Sentry.metrics.count("checkout_failures", 1);
+    throw error;
+  }
+}
+```
+
+### Proxy / Middleware
+
+Track request patterns at the edge.
+Next.js 16+ uses `proxy.ts`, while earlier versions use `middleware.ts`. The pattern is
+the same:
+
+**`proxy.ts`**
+
+```typescript
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+import * as Sentry from "@sentry/nextjs";
+
+export function proxy(request: NextRequest) {
+  // Use a bounded route pattern, not the raw pathname (which is high-cardinality)
+  const route = request.nextUrl.pathname.split("/").slice(0, 3).join("/"); // e.g. "/api/orders"
+
+  Sentry.metrics.count("requests", 1, {
+    attributes: {
+      route,
+      method: request.method,
+    },
+  });
+
+  return NextResponse.next();
+}
+```
+
+---
+
+## Units
+
+Pass a `unit` string in `MetricOptions`. Used for display formatting in Sentry.
+
+| Category  | Unit Values                                                               |
+| --------- | ------------------------------------------------------------------------- |
+| Time      | `millisecond`, `second`, `minute`, `hour`, `day`, `week`                  |
+| Storage   | `bit`, `byte`, `kilobyte`, `megabyte`, `gigabyte`, `terabyte`, `petabyte` |
+| Fractions | `ratio`, `percent`                                                        |
+| None      | `none` (or omit `unit`)                                                   |
+
+```typescript
+Sentry.metrics.distribution("api.latency", 187.5, { unit: "millisecond" });
+Sentry.metrics.distribution("job.duration", 3.2, { unit: "second" });
+Sentry.metrics.gauge("memory.usage", 512, { unit: "megabyte" });
+Sentry.metrics.gauge("cache.hit_rate", 0.87, { unit: "ratio" });
+Sentry.metrics.gauge("disk.usage_pct", 72.4, { unit: "percent" });
+Sentry.metrics.count("user.logins"); // omit unit for plain counts
+```
+
+---
+
+## Attributes (Tags)
+
+Use `attributes` in `MetricOptions` to add filterable/groupable dimensions.
+
+**Size limit:** 2 KB per metric envelope.
+Metrics exceeding this are **dropped**.
+
+```typescript
+Sentry.metrics.count("api.requests", 1, {
+  attributes: {
+    endpoint: "/api/orders",
+    method: "POST",
+    status_code: 200,
+    user_tier: "pro",
+    region: "us-west-2",
+    version: "v2",
+  },
+});
+
+Sentry.metrics.distribution("db.query_time", 45.3, {
+  unit: "millisecond",
+  attributes: {
+    table: "orders",
+    operation: "SELECT",
+    index_used: true,
+    rows_scanned: 1240,
+  },
+});
+```
+
+---
+
+## Cardinality
+
+Sentry’s Application Metrics are **trace-connected and high-cardinality by design**.
+Unlike tags, metric `attributes` have no per-value restrictions, so high-cardinality
+values such as per-user IDs or request UUIDs are valid attribute values — you do not
+need to bucket them into bounded enums first.
+
+```typescript
+Sentry.metrics.count("page.view", 1, {
+  attributes: {
+    user_id: "uuid-abc-123", // high-cardinality values are supported
+    page: "/dashboard",
+    user_tier: "pro",
+    region: "us-east-1",
+  },
+});
+```
+
+The practical limit is the **2 KB per-metric envelope size** (metrics exceeding it are
+dropped — see above), not the cardinality of individual attribute values.
+
+---
+
+## Scope-Based Attributes (SDK ≥10.33.0)
+
+Set attributes on a scope and they auto-attach to all metrics emitted within it:
+
+```typescript
+// Global scope — applies to all metrics app-wide
+Sentry.getGlobalScope().setAttributes({
+  service: "payments",
+  deploy_env: "production",
+});
+
+// Per-request scope
+Sentry.withScope((scope) => {
+  scope.setAttribute("step", "checkout");
+  scope.setAttribute("user_tier", "enterprise");
+
+  // Both metrics inherit the scope attributes above
+  Sentry.metrics.count("checkout.attempts", 1);
+  Sentry.metrics.gauge("cart.value", 249.99);
+});
+```
+
+---
+
+## Auto-Attached Default Attributes
+
+| Attribute                            | Value                               | Context     |
+| ------------------------------------ | ----------------------------------- | ----------- |
+| `sentry.environment`                 | From `Sentry.init({ environment })` | Always      |
+| `sentry.release`                     | From `Sentry.init({ release })`     | Always      |
+| `sentry.sdk.name`                    | SDK identifier                      | Always      |
+| `sentry.sdk.version`                 | e.g., `"10.42.0"`                   | Always      |
+| `user.id`, `user.name`, `user.email` | If user is set in scope             | When set    |
+| `browser.name`, `browser.version`    | Browser info                        | Client-side |
+| `sentry.replay_id`                   | Session replay ID                   | Client-side |
+| `server.address`                     | Server hostname                     | Server-side |
+
+---
+
+## `beforeSendMetric` Hook
+
+Filter or modify metrics before transmission.
+Return `null` to drop.
+Configure in any runtime config file (`instrumentation-client.ts`,
+`sentry.server.config.ts`, or `sentry.edge.config.ts`):
+
+**`sentry.server.config.ts`**
+
+```typescript
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  beforeSendMetric: (metric) => {
+    // metric: { name, value, type, unit?, attributes? }
+
+    // Drop internal debug metrics
+    if (metric.name.startsWith("_internal.")) {
+      return null;
+    }
+
+    // Normalize metric names
+    metric.name = metric.name.toLowerCase().replace(/[^a-z0-9_.]/g, "_");
+
+    // Add global context
+    metric.attributes = {
+      ...metric.attributes,
+      deploy_id: process.env.DEPLOY_ID,
+    };
+
+    return metric;
+  },
+});
+```
+
+---
+
+## Flushing
+
+Metrics are buffered (up to 1000 entries) and flushed periodically.
+In serverless or edge environments, the function may terminate before the buffer flushes
+automatically. Use `flush()` to send pending metrics while keeping the client alive
+(suitable for reusable function instances), or `close()` to flush and permanently shut
+down the client:
+
+```typescript
+await Sentry.flush(2000); // send pending data, keep client alive (use in serverless)
+await Sentry.close(2000); // send pending data + tear down client (use on permanent shutdown)
+```
+
+This is especially important for:
+
+- **Serverless / Vercel API routes** — function instances may terminate or freeze before
+  the buffer auto-flushes
+- **Edge runtime handlers** — short-lived execution contexts with no background flush
+  opportunity
+
+---
+
+## Troubleshooting
+
+| Problem                       | Likely Cause                 | Fix                                                                 |
+| ----------------------------- | ---------------------------- | ------------------------------------------------------------------- |
+| Metrics not appearing         | SDK < 10.24.0                | Upgrade to ≥10.24.0                                                 |
+| `Sentry.metrics` is undefined | SDK < 10.25.0                | Upgrade to ≥10.25.0                                                 |
+| Metrics silently dropped      | Attribute envelope > 2 KB    | Reduce number or size of `attributes`                               |
+| `increment()` not found       | Renamed in v10               | Use `count()` instead                                               |
+| `set()` not found             | Removed in v10               | No equivalent; use `count()` with bounded attributes                |
+| Scope attributes missing      | SDK < 10.33.0                | Upgrade to ≥10.33.0                                                 |
+| Metrics lost in serverless    | Buffer not flushed           | Call `await Sentry.flush(2000)` before function returns             |
+| Metrics missing on edge       | Edge runtime not initialized | Ensure `sentry.edge.config.ts` has `Sentry.init()`                  |
+| High-cardinality issues       | Unbounded attribute values   | Keep attributes to bounded enums/sets                               |
+| Metrics not in server actions | Server config missing        | Verify `sentry.server.config.ts` is loaded via `instrumentation.ts` |