@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/sdks/node/profiling.md

@@ -0,0 +1,373 @@
+# Profiling — Sentry Node.js SDK
+
+> Node.js profiling: `@sentry/profiling-node` — must match your `@sentry/node` version
+> exactly\
+> **Bun and Deno are NOT supported.** The profiler is a native C++ addon (`node-gyp`)
+> that only runs in Node.js.
+
+---
+
+## Overview
+
+Profiling captures V8 CPU call stacks at ~100 samples/second alongside your traces.
+Profiles attach to spans, giving you flame graphs to identify hot paths directly from a
+slow trace.
+
+Profiling is **Node.js only**:
+
+| Runtime     | Profiling | Notes                                     |
+| ----------- | --------- | ----------------------------------------- |
+| Node.js ≥18 | ✅        | Full support via `@sentry/profiling-node` |
+| Bun         | ❌        | Native addon not supported                |
+| Deno        | ❌        | Native addon not supported                |
+
+---
+
+## How Profiling Relates to Tracing
+
+Profiles attach to **spans** — they require tracing to be enabled:
+
+1. `tracesSampleRate` / `tracesSampler` decides whether a request is traced at all
+2. `profileSessionSampleRate` decides whether the session opts into profiling
+3. A profile is only collected when **both** sampling decisions are “yes”
+
+```
+tracesSampleRate: 0.1   +  profileSessionSampleRate: 0.5
+→ ~5% of requests will have both a trace AND a profile attached
+```
+
+In `trace` lifecycle mode, you can drill from a slow span in the Performance UI directly
+into a flame graph:
+
+```
+Trace: "POST /api/checkout" (850ms)
+  ├── "validateCart" (45ms)   → [Profile attached] → shows DB driver hot paths
+  ├── "processPayment" (620ms)
+  └── "updateInventory" (185ms) → [Profile attached] → shows ORM overhead
+```
+
+---
+
+## Installation
+
+```bash
+npm install @sentry/profiling-node --save
+```
+
+> ⚠️ **Version pinning is required.** `@sentry/profiling-node` must exactly match your
+> `@sentry/node` version.
+> Mismatched versions cause silent failures or startup crashes.
+
+```bash
+# Both must be the same version
+npm install @sentry/node@latest @sentry/profiling-node@latest
+```
+
+---
+
+## SDK Configuration
+
+### Trace Mode (Recommended)
+
+Profiles auto-attach to all sampled spans with no additional code:
+
+```typescript
+import * as Sentry from "@sentry/node";
+import { nodeProfilingIntegration } from "@sentry/profiling-node";
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+
+  integrations: [nodeProfilingIntegration()],
+
+  tracesSampleRate: 1.0,
+
+  // Session-level sampling: decision made once at process startup
+  profileSessionSampleRate: process.env.NODE_ENV === "production" ? 0.1 : 1.0,
+
+  // "trace" = profiles auto-attach to every sampled span
+  profileLifecycle: "trace",
+});
+```
+
+### Manual Mode
+
+Start and stop profiling around specific code paths:
+
+```typescript
+import * as Sentry from "@sentry/node";
+import { nodeProfilingIntegration } from "@sentry/profiling-node";
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  integrations: [nodeProfilingIntegration()],
+  tracesSampleRate: 1.0,
+  profileSessionSampleRate: 1.0,
+  profileLifecycle: "manual",
+});
+
+// Explicit start/stop around critical code:
+Sentry.profiler.startProfiler();
+await heavyComputation();
+Sentry.profiler.stopProfiler();
+```
+
+---
+
+## Continuous Profiling
+
+For long-running processes, batch jobs, or background workers that don’t map cleanly to
+request spans, use the profiler API directly:
+
+```typescript
+import * as Sentry from "@sentry/node";
+import { nodeProfilingIntegration } from "@sentry/profiling-node";
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  integrations: [nodeProfilingIntegration()],
+});
+
+// Start profiling at process startup
+Sentry.profiler.startProfiler();
+
+// Profile is chunked automatically into ~60-second intervals and uploaded
+// All spans created during this window have profile data attached
+
+// Stop when done (e.g. graceful shutdown)
+process.on("SIGTERM", () => {
+  Sentry.profiler.stopProfiler();
+  process.exit(0);
+});
+```
+
+### Profile Chunk Architecture
+
+The V2 profiler divides data into 60-second chunks that upload automatically:
+
+```
+Process lifetime:
+┌─── 60 seconds ───┬─── 60 seconds ───┬─── 60 seconds ───┐
+│   Chunk 1        │   Chunk 2        │   Chunk 3        │
+│   Spans: [...]   │   Spans: [...]   │   Spans: [...]   │
+│   Sent at 60s    │   Sent at 120s   │   Sent at 180s   │
+└──────────────────┴──────────────────┴──────────────────┘
+```
+
+This means there’s no 30-second max like in the legacy V1 API — the profiler runs as
+long as your process does.
+
+---
+
+## Profiler API Reference
+
+### `Sentry.profiler.startProfiler()`
+
+Starts the V8 CpuProfiler.
+Call this once at process startup or before the code you want to profile.
+
+```typescript
+Sentry.profiler.startProfiler();
+```
+
+- No-ops gracefully if already running
+- Takes effect immediately
+- Overhead is low; safe to call at startup in production
+
+### `Sentry.profiler.stopProfiler()`
+
+Stops the profiler and flushes remaining profile data to Sentry.
+
+```typescript
+Sentry.profiler.stopProfiler();
+```
+
+- Flushes the current in-progress chunk
+- Call on graceful shutdown to avoid losing the last partial chunk
+
+### Manual Start/Stop Pattern
+
+```typescript
+// Profile a specific batch job, not the entire process
+async function runNightlyBatch() {
+  Sentry.profiler.startProfiler();
+  try {
+    await Sentry.startSpan({ op: "batch", name: "nightly-sync" }, async () => {
+      await syncUsers();
+      await syncOrders();
+      await syncInventory();
+    });
+  } finally {
+    Sentry.profiler.stopProfiler();
+  }
+}
+```
+
+---
+
+## Configuration Reference
+
+| Parameter                    | Type                  | Description                                                                                |
+| ---------------------------- | --------------------- | ------------------------------------------------------------------------------------------ |
+| `profileSessionSampleRate`   | `0.0–1.0`             | Session-level sampling. Decision made once at process startup.                             |
+| `profileLifecycle`           | `"trace" \| "manual"` | `"trace"` = auto-attach to spans; `"manual"` = explicit `startProfiler()`/`stopProfiler()` |
+| `nodeProfilingIntegration()` | integration           | Enables V8 CpuProfiler. Must be in `integrations` array.                                   |
+
+### `profileSessionSampleRate` Semantics
+
+The profiling sampling decision is made **once per process startup** — not per request.
+
+A “profiling session” either opts in or opts out for its entire lifetime.
+Within a profiling session, every traced span gets a profile attached (in `trace` mode).
+
+```typescript
+// 10% of Node.js processes will profile all their requests
+profileSessionSampleRate: 0.1;
+```
+
+### `profileLifecycle` Modes
+
+| Mode       | Trigger                              | Best for                                  |
+| ---------- | ------------------------------------ | ----------------------------------------- |
+| `"trace"`  | Auto-attached to every sampled span  | Broad production coverage, web servers    |
+| `"manual"` | `startProfiler()` / `stopProfiler()` | Batch jobs, specific hot paths, CLI tools |
+
+---
+
+## Supported Platforms
+
+Precompiled native binaries are available for:
+
+| OS                  | Architecture          | Node.js |
+| ------------------- | --------------------- | ------- |
+| macOS               | x64 (Intel)           | 18–24   |
+| macOS               | ARM64 (Apple Silicon) | 18–24   |
+| Linux (glibc)       | x64                   | 18–24   |
+| Linux (glibc)       | ARM64                 | 18–24   |
+| Linux (musl/Alpine) | x64                   | 18–24   |
+| Linux (musl/Alpine) | ARM64                 | 18–24   |
+| Windows             | x64                   | 18–24   |
+
+> ❌ **FreeBSD, 32-bit systems, Bun, and Deno are not supported.**\
+> The native addon requires Node.js — it cannot run in other runtimes.
+
+### Alpine Linux / Docker
+
+The musl libc variant is included automatically.
+If you see missing binary errors on Alpine:
+
+```dockerfile
+# Ensure you're installing native dependencies
+RUN npm install --include=optional
+```
+
+Or rebuild from source:
+
+```dockerfile
+RUN apk add --no-cache python3 make g++ && npm rebuild @sentry/profiling-node
+```
+
+---
+
+## Environment Variables
+
+```bash
+# Override profiler binary path (for custom builds or non-standard environments)
+SENTRY_PROFILER_BINARY_PATH=/custom/path/sentry_cpu_profiler.node
+
+# Override binary directory
+SENTRY_PROFILER_BINARY_DIR=/path/to/dir
+
+# Profiler logging mode:
+# "eager" (default) — faster startProfiler calls, slightly more CPU overhead
+# "lazy"            — lower CPU overhead, slightly slower startProfiler
+SENTRY_PROFILER_LOGGING_MODE=lazy node server.js
+```
+
+---
+
+## Production Recommendations
+
+```typescript
+Sentry.init({
+  integrations: [nodeProfilingIntegration()],
+  tracesSampleRate: process.env.NODE_ENV === "production" ? 0.1 : 1.0,
+  profileSessionSampleRate: process.env.NODE_ENV === "production" ? 0.1 : 1.0,
+  profileLifecycle: "trace",
+});
+```
+
+**Performance impact notes:**
+
+- **Sampling rate (~100Hz):** The V8 CpuProfiler adds CPU overhead.
+  Test with realistic load before deploying `profileSessionSampleRate: 1.0` to
+  high-traffic production.
+- **Memory:** Each 60-second chunk uses ~10–20 MB of buffer.
+  Capped at 50 chunks (~100 MB max).
+- **Network:** One profiling upload per 60-second window per process.
+
+> “For high-throughput environments, we recommend testing prior to deployment to ensure
+> that your service’s performance characteristics maintain expectations.”
+> — Sentry docs
+
+For high-traffic servers, start conservative:
+
+```typescript
+// Start at 1–5% and increase after measuring overhead
+profileSessionSampleRate: 0.01;
+```
+
+---
+
+## Complete Setup Example
+
+```typescript
+// instrument.ts (loaded before app code)
+import * as Sentry from "@sentry/node";
+import { nodeProfilingIntegration } from "@sentry/profiling-node";
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+
+  integrations: [nodeProfilingIntegration()],
+
+  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
+  profileSessionSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
+  profileLifecycle: "trace",
+});
+```
+
+```typescript
+// app.ts
+import "./instrument"; // Must be first import
+import express from "express";
+import * as Sentry from "@sentry/node";
+
+const app = express();
+
+app.get("/api/users", async (req, res) => {
+  // Automatically traced + profiled (in profiling sessions)
+  const users = await db.query("SELECT * FROM users");
+  res.json(users);
+});
+
+Sentry.setupExpressErrorHandler(app);
+app.listen(3000);
+```
+
+---
+
+## Troubleshooting
+
+| Issue                                         | Solution                                                                                                         |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| No profiles appearing in Sentry               | Verify `@sentry/profiling-node` version exactly matches `@sentry/node` version (`npm ls @sentry/profiling-node`) |
+| `Cannot find module '@sentry/profiling-node'` | Run `npm install @sentry/profiling-node` and confirm it’s in `dependencies` (not `devDependencies`)              |
+| Native addon fails to load                    | Check you’re on Node.js ≥18; check OS/arch is in the supported platforms table                                   |
+| Profiles not linked to spans                  | Confirm `profileLifecycle: "trace"` is set and `tracesSampleRate` > 0; both are required                         |
+| High CPU usage                                | Lower `profileSessionSampleRate`; use `SENTRY_PROFILER_LOGGING_MODE=lazy`                                        |
+| Alpine/musl Linux binary error                | Run `npm rebuild @sentry/profiling-node` after installing build tools (`apk add python3 make g++`)               |
+| Profiling works locally but not in Docker     | Ensure `npm install --include=optional` runs in the Docker build; musl variant must be present                   |
+| Flame graphs show minified names              | Upload source maps via `authToken` in Sentry config; use `NODE_OPTIONS=--enable-source-maps`                     |
+| Last ~60s of data lost on shutdown            | Call `Sentry.profiler.stopProfiler()` in your SIGTERM/SIGINT handler before `process.exit()`                     |
+| Bun or Deno profiling doesn’t work            | Native addon only supports Node.js — profiling is not available in Bun or Deno                                   |