@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/sdks/browser/session-replay.md

@@ -0,0 +1,586 @@
+# Session Replay — Sentry Browser SDK
+
+> Minimum SDK: `@sentry/browser` ≥7.27.0\
+> `replayCanvasIntegration` available since SDK ≥7.50.0\
+> `beforeAddRecordingEvent` available since SDK ≥7.53.0\
+> `beforeErrorSampling` available since SDK ≥7.56.0\
+> Node 12+ required; browsers newer than IE11
+
+---
+
+## Basic Setup
+
+```javascript
+import * as Sentry from "@sentry/browser";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  replaysSessionSampleRate: 0.1, // 10% of all sessions recorded in full
+  replaysOnErrorSampleRate: 1.0, // 100% of sessions with errors buffered and sent
+  integrations: [Sentry.replayIntegration()],
+});
+```
+
+---
+
+## Sampling Rates
+
+### `replaysSessionSampleRate` vs. `replaysOnErrorSampleRate`
+
+| Option                     | Default | Behavior                                                                                                                                     |
+| -------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `replaysSessionSampleRate` | `0`     | Percentage of sessions to record **in full** from start to end. `1.0` = 100%, `0` = none.                                                    |
+| `replaysOnErrorSampleRate` | `0`     | Percentage of sessions to record **when an error occurs**. Buffers up to 60 seconds before the error, then continues until the session ends. |
+
+### How Sampling Works
+
+1. `replaysSessionSampleRate` is checked first at session start.
+   - If sampled → full session recording starts immediately, sent to Sentry in real-time
+     chunks (**Session mode**).
+   - If not sampled → recording is buffered in memory (last 60 seconds only) (**Buffer
+     mode**).
+2. If an error occurs in a buffered session:
+   - `replaysOnErrorSampleRate` is checked.
+   - If sampled → 60-second buffer + rest of session is sent to Sentry.
+   - If not sampled → buffer is discarded.
+
+**When data leaves the browser:**
+
+| Scenario                               | Data Sent                                   |
+| -------------------------------------- | ------------------------------------------- |
+| Selected for session sampling          | Immediately (real-time chunks)              |
+| Not selected, no error                 | Never (buffer discarded)                    |
+| Not selected, error occurs and sampled | After error (60s buffer + everything after) |
+
+**Recommended rates by traffic volume:**
+
+| Traffic               | `replaysSessionSampleRate` | `replaysOnErrorSampleRate` |
+| --------------------- | -------------------------- | -------------------------- |
+| High (100k+/day)      | `0.01` (1%)                | `1.0`                      |
+| Medium (10k–100k/day) | `0.1` (10%)                | `1.0`                      |
+| Low (<10k/day)        | `0.25` (25%)               | `1.0`                      |
+
+> **Tip:** Keep `replaysOnErrorSampleRate` at `1.0` — error sessions provide the most
+> debugging value.\
+> **Dev tip:** Set `replaysSessionSampleRate: 1.0` during development to capture every
+> session.
+
+---
+
+## `replayIntegration()` — Configuration Reference
+
+### General Options
+
+| Option                     | Type                       | Default               | Description                                                                                              |
+| -------------------------- | -------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------- |
+| `stickySession`            | `boolean`                  | `true`                | Track the user across page refreshes. Closing a tab ends the session; multiple tabs = multiple sessions. |
+| `mutationLimit`            | `number`                   | `10000`               | Upper bound of DOM mutations before replay stops recording (protects performance).                       |
+| `mutationBreadcrumbLimit`  | `number`                   | `750`                 | Threshold at which a breadcrumb warning is emitted for large mutations.                                  |
+| `minReplayDuration`        | `number`                   | `5000` (ms)           | Minimum replay length before sending. Max configurable: 15000ms.                                         |
+| `maxReplayDuration`        | `number`                   | `3600000` (ms = 1 hr) | Maximum replay length. Max value: 3600000ms.                                                             |
+| `workerUrl`                | `string`                   | `undefined`           | URL for a self-hosted compression worker (avoids CSP issues, reduces bundle size).                       |
+| `beforeAddRecordingEvent`  | `(event) => event \| null` | identity fn           | Filter or modify console log and network recording events before they are sent. Return `null` to drop.   |
+| `beforeErrorSampling`      | `(event) => boolean`       | `() => true`          | In buffer mode only — return `false` to skip error-based sampling for a specific error event.            |
+| `slowClickIgnoreSelectors` | `string[]`                 | `[]`                  | CSS selectors for elements where slow/rage click detection should be disabled.                           |
+
+### Privacy Options
+
+| Option          | Type                       | Default                                      | Description                                                                           |
+| --------------- | -------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `maskAllText`   | `boolean`                  | `true`                                       | Mask all text content (replaced with `*` characters).                                 |
+| `maskAllInputs` | `boolean`                  | `true`                                       | Mask all `<input>` element values.                                                    |
+| `blockAllMedia` | `boolean`                  | `true`                                       | Block all media: `img`, `svg`, `video`, `object`, `picture`, `embed`, `map`, `audio`. |
+| `mask`          | `string[]`                 | `[".sentry-mask", "[data-sentry-mask]"]`     | Additional CSS selectors to mask. Appended to defaults.                               |
+| `unmask`        | `string[]`                 | `[]`                                         | CSS selectors to unmask (overrides `maskAllText`).                                    |
+| `block`         | `string[]`                 | `[".sentry-block", "[data-sentry-block]"]`   | Additional CSS selectors to block (replaced with same-size empty placeholder).        |
+| `unblock`       | `string[]`                 | `[]`                                         | CSS selectors to unblock (overrides `blockAllMedia`).                                 |
+| `ignore`        | `string[]`                 | `[".sentry-ignore", "[data-sentry-ignore]"]` | Input fields whose events are ignored (no keystroke recording).                       |
+| `maskFn`        | `(text: string) => string` | `(s) => "*".repeat(s.length)`                | Custom text masking function.                                                         |
+
+### Network Options
+
+| Option                   | Type                   | Default | Description                                                                                          |
+| ------------------------ | ---------------------- | ------- | ---------------------------------------------------------------------------------------------------- |
+| `networkDetailAllowUrls` | `(string \| RegExp)[]` | `[]`    | URLs/patterns for which request/response details are captured (opt-in, SDK ≥7.50.0).                 |
+| `networkDetailDenyUrls`  | `(string \| RegExp)[]` | `[]`    | URLs/patterns to exclude from network capture. Takes precedence over `networkDetailAllowUrls`.       |
+| `networkCaptureBodies`   | `boolean`              | `true`  | Whether to capture request/response bodies for allowed URLs.                                         |
+| `networkRequestHeaders`  | `string[]`             | `[]`    | Additional request headers to capture. Default captured: `Content-Type`, `Content-Length`, `Accept`. |
+| `networkResponseHeaders` | `string[]`             | `[]`    | Additional response headers to capture.                                                              |
+
+---
+
+## Privacy & Masking
+
+### Three Privacy Methods
+
+| Method     | Effect                                                   | Default Trigger                          |
+| ---------- | -------------------------------------------------------- | ---------------------------------------- |
+| **Mask**   | Replaces text with `*` characters (preserving length)    | `.sentry-mask`, `[data-sentry-mask]`     |
+| **Block**  | Replaces entire element with same-size empty placeholder | `.sentry-block`, `[data-sentry-block]`   |
+| **Ignore** | Stops recording input events on matched fields           | `.sentry-ignore`, `[data-sentry-ignore]` |
+
+### HTML Attribute Usage
+
+```html
+<!-- Mask text content -->
+<p class="sentry-mask">Sensitive user data</p>
+<p data-sentry-mask>Sensitive user data</p>
+
+<!-- Block entire element (credit card form, PII section) -->
+<div class="sentry-block">
+  <input type="text" placeholder="Credit card number" />
+</div>
+<div data-sentry-block>Blocked content</div>
+
+<!-- Ignore input events (no keystrokes recorded) -->
+<input class="sentry-ignore" type="password" />
+<input data-sentry-ignore type="text" placeholder="SSN" />
+
+<!-- Unmask when maskAllText=true -->
+<p class="sentry-unmask">Safe to show in replay</p>
+<p data-sentry-unmask>Safe to show</p>
+
+<!-- Unblock media when blockAllMedia=true -->
+<img class="sentry-unblock" src="product-image.png" alt="Product" />
+<img data-sentry-unblock src="logo.svg" alt="Logo" />
+```
+
+### Configuration Examples
+
+**Disable all default masking (show everything):**
+
+```javascript
+Sentry.replayIntegration({
+  maskAllText: false,
+  blockAllMedia: false,
+});
+```
+
+**Mask and block specific selectors:**
+
+```javascript
+Sentry.replayIntegration({
+  mask: [".user-pii", "[data-sensitive]", "#account-details"],
+  unmask: [".replay-safe"],
+  block: ["#payment-form", ".credit-card-widget"],
+  unblock: [".product-image"],
+  ignore: [".password-field", "[type='password']"],
+});
+```
+
+**Custom masking function:**
+
+```javascript
+Sentry.replayIntegration({
+  maskFn: (text) => text.replace(/\S/g, "X"), // Replace non-whitespace with X
+});
+```
+
+**Custom recording event filter:**
+
+```javascript
+Sentry.replayIntegration({
+  beforeAddRecordingEvent: (event) => {
+    // Drop any event tagged "foo"
+    if (event.data.tag === "foo") return null;
+
+    // Only capture network events for 500 errors
+    if (
+      event.data.tag === "performanceSpan" &&
+      (event.data.payload.op === "resource.fetch" || event.data.payload.op === "resource.xhr") &&
+      event.data.payload.data.statusCode !== 500
+    ) {
+      return null;
+    }
+
+    return event;
+  },
+});
+```
+
+---
+
+## Network Capture
+
+By default, Session Replay captures basic information about all outgoing fetch and XHR
+requests (URL, size, method, status code).
+
+Request/response **bodies and additional headers require explicit opt-in** (SDK
+≥7.50.0):
+
+```javascript
+Sentry.replayIntegration({
+  networkDetailAllowUrls: [window.location.origin],
+});
+```
+
+**Advanced — multiple patterns with custom headers:**
+
+```javascript
+Sentry.replayIntegration({
+  networkDetailAllowUrls: [
+    window.location.origin,
+    "api.example.com",
+    /^https:\/\/api\.example\.com/,
+  ],
+  networkCaptureBodies: true, // default: true — capture request/response bodies
+  networkRequestHeaders: ["Cache-Control", "X-Request-ID"],
+  networkResponseHeaders: ["Referrer-Policy", "X-Trace-ID"],
+});
+```
+
+**Constraints:**
+
+- Bodies are truncated to **150,000 characters** maximum
+- `networkDetailDenyUrls` takes precedence over `networkDetailAllowUrls`
+- Set `networkCaptureBodies: false` to keep header capture while disabling body capture
+
+---
+
+## Canvas Recording
+
+Canvas elements are not captured by default.
+Add `replayCanvasIntegration()` to enable:
+
+```javascript
+import * as Sentry from "@sentry/browser";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  replaysSessionSampleRate: 0.1,
+  replaysOnErrorSampleRate: 1.0,
+  integrations: [Sentry.replayIntegration(), Sentry.replayCanvasIntegration()],
+});
+```
+
+> ⚠️ **There is currently no PII scrubbing in canvas recordings.** Review canvas content
+> carefully before enabling.
+
+### 3D / WebGL Canvases — Manual Snapshot Mode
+
+For WebGL or 3D canvases, use manual snapshotting to optimize performance:
+
+```javascript
+Sentry.replayCanvasIntegration({
+  enableManualSnapshot: true,
+});
+
+// Call in your render loop to capture the canvas
+function paint() {
+  const canvasRef = document.querySelector("#my-canvas");
+  Sentry.getClient()?.getIntegrationByName("ReplayCanvas")?.snapshot(canvasRef);
+}
+```
+
+### WebGPU Canvases
+
+```javascript
+Sentry.replayCanvasIntegration({
+  enableManualSnapshot: true,
+});
+
+function paint() {
+  const canvasRef = document.querySelector("#my-canvas");
+  const canvasIntegration = Sentry.getClient()?.getIntegrationByName("ReplayCanvas");
+
+  canvasIntegration?.snapshot(canvasRef, {
+    skipRequestAnimationFrame: true,
+  });
+}
+```
+
+---
+
+## Lazy Loading
+
+Defer loading the Replay bundle to avoid impacting initial page load:
+
+```javascript
+// Initialize Sentry without Replay
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [],
+});
+
+// Lazy-load Replay later (e.g., after user interaction or route change)
+import("@sentry/browser").then((lazySentry) => {
+  Sentry.addIntegration(
+    lazySentry.replayIntegration({
+      maskAllText: true,
+      blockAllMedia: true,
+    }),
+  );
+});
+```
+
+**For Loader Script users** (CDN), use `lazyLoadIntegration`:
+
+```javascript
+window.sentryOnLoad = function () {
+  Sentry.init({ dsn: "___PUBLIC_DSN___" });
+
+  Sentry.lazyLoadIntegration("replayIntegration")
+    .then((replayIntegration) => {
+      Sentry.addIntegration(replayIntegration());
+    })
+    .catch(() => {
+      // Network error — Replay not enabled
+    });
+};
+```
+
+---
+
+## Session Modes & Manual Control
+
+### Session Initialization Modes
+
+| Configuration                                        | Mode             | Behavior                                                   |
+| ---------------------------------------------------- | ---------------- | ---------------------------------------------------------- |
+| `replaysSessionSampleRate > 0` and sampled           | **Session mode** | Records continuously; uploads data in real time            |
+| Not sampled, `replaysOnErrorSampleRate > 0`          | **Buffer mode**  | Records but keeps only last 60 seconds in memory (~2–5 MB) |
+| Both rates = `0`, or integration added without rates | **Inactive**     | Nothing recorded until manually started                    |
+
+**Session mode:** sessions end after **15 minutes of inactivity** or **60 minutes
+maximum duration**, then reinitialize.
+
+**Buffer mode:** stores ~2–5 MB in memory (lightweight DOM event logs: clicks, scrolls,
+mutations — not video files).
+On sampled error, the 60-second buffer + subsequent recording are uploaded.
+
+---
+
+### Manual Session Control API
+
+```javascript
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  replaysSessionSampleRate: 0,
+  replaysOnErrorSampleRate: 0,
+  integrations: [Sentry.replayIntegration()],
+});
+
+const replay = Sentry.getReplay();
+
+replay.start(); // Start recording in session mode
+replay.startBuffering(); // Start recording in buffer mode
+
+await replay.flush(); // Upload pending data (keeps recording active)
+await replay.stop(); // Flush data and end session permanently
+
+const replayId = replay.getReplayId(); // Get current replay ID for external linking
+```
+
+---
+
+### Deferred Initialization (External Sampling Service)
+
+Use when you want to determine sampling rates via an external feature flag service
+before starting the SDK:
+
+```javascript
+async function initReplay(sessionSampleRate, errorSampleRate) {
+  const client = Sentry.getClient();
+  const options = client.getOptions();
+  options.replaysSessionSampleRate = sessionSampleRate;
+  options.replaysOnErrorSampleRate = errorSampleRate;
+
+  const replay = Sentry.replayIntegration({
+    maskAllText: true,
+    blockAllMedia: true,
+  });
+
+  client.addIntegration(replay);
+}
+
+// Call after fetching remote config
+fetchFeatureFlags().then((flags) => {
+  initReplay(flags.replaySessionRate, flags.replayErrorRate);
+});
+```
+
+---
+
+### Custom Sampling Patterns
+
+**Employee-only recordings:**
+
+Force a full recording for a specific cohort (e.g. internal employees) after they
+authenticate. Because `flush()` only uploads _already-active_ recording data, guard on
+`replay.getReplayId()`: if a replay is already active (session mode, or buffer mode when
+`replaysOnErrorSampleRate > 0`) flush it to send immediately and keep recording;
+otherwise call `replay.start()` to begin a new session-mode recording.
+`replay.start()` records regardless of sample rate and is a safe no-op if a session is
+already running.
+
+```javascript
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  replaysSessionSampleRate: 0.1,
+  replaysOnErrorSampleRate: 1.0,
+  integrations: [Sentry.replayIntegration()],
+});
+
+// After authentication, always record a replay for internal employees
+if (loggedInUser.isEmployee) {
+  const replay = Sentry.getReplay();
+
+  if (replay.getReplayId()) {
+    // A replay is already active (session or buffer mode):
+    // flush uploads the pending data and continues recording.
+    replay.flush();
+  } else {
+    // Nothing recording yet: start a full session-mode recording.
+    replay.start();
+  }
+}
+```
+
+**URL-specific recording:**
+
+```javascript
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  replaysSessionSampleRate: 0,
+  replaysOnErrorSampleRate: 0,
+  integrations: [Sentry.replayIntegration()],
+});
+
+navigation.addEventListener("navigate", (event) => {
+  const url = new URL(event.destination.url);
+  const replay = Sentry.getReplay();
+  if (url.pathname.startsWith("/checkout/")) {
+    replay.start();
+  } else {
+    replay.stop();
+  }
+});
+```
+
+**Error filtering in buffer mode:**
+
+```javascript
+Sentry.replayIntegration({
+  beforeErrorSampling: (event) => {
+    // Skip replay capture for this specific error type
+    return !event.exception?.values?.[0]?.value?.includes("drop me");
+  },
+});
+```
+
+---
+
+### Support Widget Integration
+
+Link replay sessions to support tickets:
+
+```javascript
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  replaysSessionSampleRate: 0.1,
+  replaysOnErrorSampleRate: 0.5,
+  integrations: [Sentry.replayIntegration()],
+});
+
+MySupportWidget.on("open", async () => {
+  const replay = Sentry.getReplay();
+  await replay.flush();
+  const replayId = replay.getReplayId();
+
+  MySupportWidget.setTag("replayId", replayId);
+  // Replay URL format:
+  // https://<org-slug>.sentry.io/replays/<replay-id>/
+});
+```
+
+---
+
+## Performance Impact
+
+### Buffer Mode is Lightweight
+
+Buffer mode stores ~2–5 MB in memory — these are DOM event logs (clicks, scrolls,
+mutations), not video files.
+The real-time encoding is handled by a WebWorker.
+
+### Mutation Limits
+
+Protect against performance degradation from excessive DOM mutations:
+
+```javascript
+Sentry.replayIntegration({
+  mutationBreadcrumbLimit: 1000, // Emit breadcrumb warning at this threshold
+  mutationLimit: 1500, // Stop recording at this threshold
+});
+```
+
+### Custom Compression Worker
+
+Reduces bundle size and avoids CSP violations by self-hosting the compression worker:
+
+```javascript
+Sentry.replayIntegration({
+  workerUrl: "/assets/sentry-replay-worker.min.js",
+});
+```
+
+**Bundler plugin optimization** (excludes worker from main bundle):
+
+```javascript
+sentryVitePlugin({
+  bundleSizeOptimizations: {
+    excludeReplayWorker: true,
+  },
+});
+```
+
+### Content Security Policy
+
+Session Replay uses a WebWorker for compression.
+Add to your CSP:
+
+```
+worker-src 'self' blob:;
+child-src 'self' blob:;
+```
+
+> Safari ≤15.4 requires `child-src`. Use a self-hosted `workerUrl` as an alternative.
+
+---
+
+## Best Practices
+
+- **Keep `replaysOnErrorSampleRate` at `1.0`** — error sessions are the highest value
+  for debugging.
+- **Use `maskAllText: true` in production** — default behavior, protects PII. Only
+  disable for internal tools.
+- **Opt-in to network details explicitly** — set `networkDetailAllowUrls` only for your
+  own API origins, not third-party services.
+- **Never enable `replayCanvasIntegration` without reviewing canvas content** — there is
+  no automatic PII scrubbing for canvas.
+- **Test masking before deploying** — use `replaysSessionSampleRate: 1.0` in staging and
+  review replays to verify PII is hidden.
+- **Use `workerUrl` to self-host the compression worker** if you have strict CSP or want
+  to reduce bundle size.
+- **Use `beforeAddRecordingEvent`** to filter out high-frequency recording events that
+  don’t add debugging value.
+- **Set `minReplayDuration`** to avoid sending trivially short sessions (default: 5s is
+  usually fine).
+
+---
+
+## Troubleshooting
+
+| Issue                                      | Solution                                                                                                                                          |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Replay not recording                       | Check that `replaysSessionSampleRate` or `replaysOnErrorSampleRate` is > 0. Confirm `replayIntegration()` is in the `integrations` array.         |
+| CSP errors blocking worker                 | Add `worker-src 'self' blob:; child-src 'self' blob:;` to your CSP, or use `workerUrl` to self-host the worker.                                   |
+| Replay stops after mutation spike          | The `mutationLimit` (default: 10000) was hit. Increase it or reduce DOM mutation frequency in your app.                                           |
+| Sensitive data visible in replays          | Add `.sentry-mask` / `.sentry-block` to elements, or use `mask`/`block` selector options. Verify with `replaysSessionSampleRate: 1.0` in staging. |
+| Canvas not recorded                        | Add `replayCanvasIntegration()` alongside `replayIntegration()`. Requires SDK ≥7.50.0.                                                            |
+| Network request bodies not captured        | Set `networkDetailAllowUrls` to include your API origin. Bodies are opt-in by default.                                                            |
+| Replay ID unavailable                      | Call `replay.getReplayId()` only after `replay.start()` or `replay.startBuffering()` has been called.                                             |
+| Error replays missing the 60-second buffer | Ensure `replaysOnErrorSampleRate > 0` and the replay integration is initialized before the error occurs.                                          |
+| Large bundle size from replay              | Use the bundler plugin option `excludeReplayWorker: true` and self-host the worker via `workerUrl`.                                               |
+| `beforeErrorSampling` not firing           | Only runs in **buffer mode** (when the session was not selected for full session recording).                                                      |
+| Safari CSP issues                          | Safari ≤15.4 requires `child-src` in addition to `worker-src`. Use `workerUrl` as an alternative.                                                 |