` | ✅ Blocked — replaced with same-size placeholder rectangle |
| Network request/response bodies | ❌ Not captured — opt-in required |
| Network headers beyond Content-Type/Length/Accept | ❌ Not captured — opt-in required |
### The Three Privacy Primitives
| Primitive | Effect | Visual result in replay |
|-----------|--------|------------------------|
| **Mask** | Replaces text content character-by-character with `*` | Element shape preserved; text unreadable |
| **Block** | Replaces entire element with opaque placeholder box | Solid grey/black rectangle same size as element |
| **Ignore** | Suppresses interaction events (clicks, keystrokes) on the element | Element visible; no input captured |
**Mask vs Block distinction:** Masked elements show their layout (you see the form structure, field labels, button positions) but no readable text. Blocked elements are completely opaque — you can't see anything inside. Use mask for forms where structure matters; use block for images, payment widgets, or entire sensitive sections.
### `maskAllText` and `maskAllInputs`
```typescript
// Defaults (most secure):
Sentry.replayIntegration({
maskAllText: true, // every text node → ***
maskAllInputs: true, // every {user.fullName}
// Safe to display even with maskAllText: true:
Welcome to Our App
// Block entire subtree — shows as grey box in replay:
// Show this image even with blockAllMedia: true:
// Child can opt out of parent masking:
{/* masked */}
Account Type {/* visible */}
// Block a payment widget; unblock the logo inside:
{/* shows in replay */}
```
### `beforeAddRecordingEvent` — Custom Event Scrubbing
Available since v7.53.0. Intercepts every recording event before it is buffered. Return `null` to drop, return the event (mutated or not) to keep:
```typescript
Sentry.replayIntegration({
beforeAddRecordingEvent: (event) => {
// Drop noisy console breadcrumbs
if (event.data.tag === 'breadcrumb' && event.data.payload?.category === 'console') {
return null;
}
// Only capture network events for 4xx/5xx responses
if (
event.data.tag === 'performanceSpan' &&
(event.data.payload.op === 'resource.fetch' ||
event.data.payload.op === 'resource.xhr')
) {
const status = event.data.payload.data?.statusCode;
if (status && status < 400) return null;
}
return event;
},
});
```
### Scrubbing URLs via `addEventProcessor`
To redact sensitive data from URLs in the replay event metadata (not the recording stream):
```typescript
Sentry.addEventProcessor((event) => {
if (event.type !== 'replay_event') return event;
const scrub = (url: string) =>
url.replace(/\/users\/[a-z0-9-]+\//gi, '/users/[id]/');
event.urls = event.urls?.map(scrub);
return event;
});
```
### `srcdoc` Iframe Warning
Elements using the `srcdoc` attribute bypass masking logic. Always block them explicitly:
```typescript
Sentry.replayIntegration({
block: ['iframe[srcdoc]'],
});
```
---
## Network Request Recording
### What Is Captured by Default
For every `fetch` and `XHR` request, without any configuration:
| Field | Captured? |
|-------|-----------|
| URL | ✅ Yes |
| HTTP method | ✅ Yes |
| HTTP status code | ✅ Yes |
| Request body size (bytes) | ✅ Yes |
| Response body size (bytes) | ✅ Yes |
| Request/response body content | ❌ No |
| Custom headers | ❌ No |
### `networkDetailAllowUrls` — Enable Body and Header Capture
Body and header capture is **opt-in** and only activates for URLs that match this list:
```typescript
Sentry.replayIntegration({
networkDetailAllowUrls: [
window.location.origin, // same-origin (recommended minimum)
'https://api.myapp.com', // specific domain
/^https:\/\/api\.myapp\.com\//, // regex pattern
'/api/', // substring match
'graphql', // matches any URL containing "graphql"
],
});
```
> **Security:** Only allowlist your own APIs. Never include third-party payment processors, auth providers, or analytics endpoints.
### `networkDetailDenyUrls` — Exclude Sensitive Endpoints
Takes precedence over `networkDetailAllowUrls`. Matching URLs never have bodies/headers captured:
```typescript
Sentry.replayIntegration({
networkDetailAllowUrls: [window.location.origin],
networkDetailDenyUrls: [
'/api/auth',
'/api/login',
'/api/payment',
'/api/users/me',
/\/sensitive\//,
/\/admin\//,
],
});
```
### `networkCaptureBodies` (boolean, default: `true`)
Controls whether request/response bodies are captured for allowlisted URLs. Set `false` to capture only headers and metadata without body content:
```typescript
Sentry.replayIntegration({
networkDetailAllowUrls: ['https://api.myapp.com'],
networkCaptureBodies: false, // headers yes, bodies no
});
```
**Body format support:**
| Format | Captured |
|--------|----------|
| `application/json` | ✅ Yes |
| XML | ✅ Yes |
| `text/plain` | ✅ Yes |
| `multipart/form-data` (text fields) | ✅ Yes |
| Binary / byte arrays | ❌ No |
| File uploads | ❌ No |
| Blobs / media streams | ❌ No |
Bodies are truncated at **150,000 characters** (150 KB). This limit is not configurable.
### `networkRequestHeaders` and `networkResponseHeaders`
By default, only `Content-Type`, `Content-Length`, and `Accept` are captured. Add more:
```typescript
Sentry.replayIntegration({
networkDetailAllowUrls: [window.location.origin],
networkRequestHeaders: [
'Cache-Control',
'X-Request-ID',
'X-Correlation-ID',
// ⚠️ Avoid: 'Authorization', 'Cookie' — contain credentials
],
networkResponseHeaders: [
'Referrer-Policy',
'X-Request-ID',
'X-Response-Time',
'CF-Ray',
'X-Cache',
],
});
```
> ⚠️ Never capture `Authorization`, `Cookie`, or `Set-Cookie` headers in production. They contain bearer tokens and session credentials.
### Capturing GraphQL Operation Names
GraphQL requests all go to the same endpoint. To distinguish operations, capture the request body and filter by operation name in `beforeAddRecordingEvent`:
```typescript
Sentry.replayIntegration({
networkDetailAllowUrls: ['https://api.myapp.com/graphql'],
networkCaptureBodies: true,
beforeAddRecordingEvent: (event) => {
// Optionally: drop mutations from replay to reduce noise
if (
event.data.tag === 'performanceSpan' &&
event.data.payload.op === 'resource.fetch'
) {
const body = event.data.payload.data?.request?.body;
if (body?.operationName === 'InternalAdminMutation') return null;
}
return event;
},
});
```
### Apollo Client Body Capture Issue
Apollo uses an `AbortController` to cancel in-flight queries on component unmount. This abort fires before Replay can read the response body, resulting in empty response bodies.
**Workaround:** Supply a custom signal that doesn't abort the Replay read:
```typescript
import { HttpLink } from '@apollo/client';
const httpLink = new HttpLink({
uri: '/graphql',
// Don't pass an AbortController signal here, or use your own
// that only cancels at route-change boundaries rather than component unmount
});
```
---
## Canvas Recording
### Setup — `replayCanvasIntegration()`
Canvas elements are **not** recorded by default. Add a second integration:
```typescript
import * as Sentry from "@sentry/react";
Sentry.init({
dsn: "...",
replaysSessionSampleRate: 0.1,
replaysOnErrorSampleRate: 1.0,
integrations: [
Sentry.replayIntegration(),
Sentry.replayCanvasIntegration(), // requires @sentry/react ≥7.98.0
],
});
```
> ⚠️ **No PII scrubbing in canvas recordings.** If your canvas renders sensitive data (user documents, medical images, profile photos), either avoid canvas recording or sanitize the canvas content before each snapshot.
### Standard 2D Canvas
For standard 2D canvas, the default configuration records automatically — no extra code needed. The integration periodically snapshots the canvas content.
### 3D / WebGL Canvas — Manual Snapshotting
WebGL requires `enableManualSnapshot: true` because:
1. The integration must enable `preserveDrawingBuffer` on the WebGL context to read pixel data
2. `preserveDrawingBuffer` prevents the GPU from discarding draw buffers after compositing — this can degrade performance on complex scenes
3. Manual mode lets you control exactly when snapshots are taken
```typescript
Sentry.init({
integrations: [
Sentry.replayIntegration(),
Sentry.replayCanvasIntegration({ enableManualSnapshot: true }),
],
});
// React ref + render loop:
import { useRef, useEffect } from 'react';
function WebGLScene() {
const canvasRef = useRef(null);
useEffect(() => {
const canvas = canvasRef.current!;
const gl = canvas.getContext('webgl');
function render() {
// ... your WebGL rendering ...
// After rendering, snapshot for Replay:
const canvasIntegration = Sentry.getClient()?.getIntegrationByName('ReplayCanvas');
canvasIntegration?.snapshot(canvas);
requestAnimationFrame(render);
}
requestAnimationFrame(render);
}, []);
return Contact Support ;
}
```
### Deferred Initialization (Feature Flags / A/B Testing)
If your sampling rates come from an external feature flag service:
```typescript
// Start Sentry without replay
Sentry.init({
dsn: "...",
integrations: [],
});
// After feature flags resolve:
async function initReplayFromFlags() {
const flags = await featureFlagService.getFlags();
const client = Sentry.getClient();
if (!client) return;
const options = client.getOptions();
options.replaysSessionSampleRate = flags.replaySessionRate;
options.replaysOnErrorSampleRate = flags.replayErrorRate;
const replay = Sentry.replayIntegration({ maskAllText: true });
client.addIntegration(replay);
}
```
### Route-Based Recording (Selective Pages)
```typescript
Sentry.init({
dsn: "...",
replaysSessionSampleRate: 0,
replaysOnErrorSampleRate: 0,
integrations: [Sentry.replayIntegration()],
});
// React Router example: only record checkout flow
import { useLocation } from 'react-router-dom';
import { useEffect } from 'react';
function ReplayController() {
const location = useLocation();
useEffect(() => {
const replay = Sentry.getReplay();
const isCheckout = location.pathname.startsWith('/checkout');
if (isCheckout && !replay.getReplayId()) {
replay.start();
} else if (!isCheckout && replay.getReplayId()) {
replay.stop();
}
}, [location.pathname]);
return null;
}
```
---
## Understanding Sessions
### What Is a Session vs a Segment
- **Replay Session:** The full recording from start to end — one replay visible in the Sentry UI. Has a unique `replayId`.
- **Segment:** A chunk of recording data transmitted to the server. Large recordings are split into segments sent in sequence and reassembled server-side.
One session = multiple segments streamed over time.
### Session Lifecycle
| Event | Session behavior |
|-------|-----------------|
| SDK initializes | Sampling evaluated; session or buffer mode begins |
| User is inactive 15+ minutes | Session ends; new session starts on next interaction |
| Total duration exceeds `maxReplayDuration` | Session ends; new session starts (re-sampled) |
| User closes the tab | Session ends; `sessionStorage` is cleared |
| `replay.stop()` called | Session ends; pending data flushed |
An "interaction" that resets the idle timer = mouse click OR browser navigation event.
### Session Mode vs Buffer Mode
| Aspect | Session Mode | Buffer Mode |
|--------|-------------|-------------|
| Activated when | `replaysSessionSampleRate > 0` AND session is sampled | Only `replaysOnErrorSampleRate > 0` |
| Data transmission | Continuous real-time chunks to Sentry | Held in memory; sent only on error |
| Memory usage | Low (continuously streamed out) | ~2–5 MB in RAM (last ~60 seconds) |
| What appears in Sentry | Full session from start | 60s before error + rest of session |
| Idle timeout | 15 minutes | 15 minutes |
| Max duration | `maxReplayDuration` | `maxReplayDuration` |
### How Buffer Mode Flushes on Error
1. Error occurs in the browser
2. Sentry SDK captures the error event
3. `beforeErrorSampling(event)` is called — `return false` to abort
4. Dice roll against `replaysOnErrorSampleRate` — fail → buffer discarded
5. Pass → buffered ~60 seconds of DOM events sent to Sentry
6. Recording continues in session mode for the remainder of the session
7. Error event is linked to the replay via `replayId` tag
---
## Performance Considerations
### Bundle Size
| Component | Size (gzipped) |
|-----------|---------------|
| `replayIntegration()` | ~50 KB |
| `replayCanvasIntegration()` | Additional (small) |
| Compression Web Worker | Extracted as separate chunk |
**Reduction strategies:**
- Use `lazyLoadIntegration('replayIntegration')` to keep it out of the critical bundle
- Set `excludeReplayWorker: true` in the Sentry bundler plugin
### Runtime Overhead
| Operation | Performance impact |
|-----------|------------------|
| DOM observation (MutationObserver) | Low — reads, doesn't write |
| Compression | Off main thread via Web Worker |
| Network interception (fetch/XHR) | Low — thin wrappers |
| Canvas recording (2D) | Moderate — pixel buffer reads |
| Canvas recording (WebGL with `preserveDrawingBuffer`) | High — prevents GPU buffer discard |
| High DOM mutation rate | High — can trigger `mutationLimit` stop |
**Errors-only mode has near-zero overhead** when no error occurs — the in-memory buffer (~2–5 MB) is the only cost.
---
## CSP Requirements
Without correct CSP headers, Replay **fails silently** — no error in the console, no replay recorded.
### Required Directives
```
worker-src 'self' blob:;
child-src 'self' blob:; ← required for Safari ≤15.4
```
**As an HTTP response header:**
```http
Content-Security-Policy: default-src 'self'; worker-src 'self' blob:; child-src 'self' blob:;
```
**As a meta tag:**
```html
.ingest.sentry.io;
```
Or with `tunnel: "/sentry-tunnel"`:
```
connect-src 'self'; ← all requests go to your own origin
```
---
## Troubleshooting
| Issue | Cause | Solution |
|-------|-------|----------|
| No replays appearing at all | CSP blocks Web Worker blob URL | Add `worker-src 'self' blob:` and `child-src 'self' blob:` to CSP |
| No replays appearing | `replayIntegration()` not in init | Confirm it's in the `integrations` array in `Sentry.init()` |
| No replays appearing | Both sample rates are `0` | Set `replaysSessionSampleRate: 0.1` or `replaysOnErrorSampleRate: 1.0` |
| No replays appearing | SDK version too old | Upgrade to `@sentry/react` ≥7.27.0 |
| No replays appearing | Running in SSR/Node context | Ensure `replayIntegration()` is only in browser-side init code |
| No replays appearing | `minReplayDuration` too high | Lower it or set to `0` for debugging |
| All text shows as `***` | `maskAllText: true` (default) | Expected. Use `unmask` or `data-sentry-unmask` to reveal safe content |
| Replay cuts off early | `mutationLimit` exceeded | Increase limit or virtualize your lists; check for DOM thrash |
| Replay shows broken layout | External CSS/fonts blocked by CORS | Add `sentry.io` to `Access-Control-Allow-Origin` on your CDN |
| Images missing in replay | External images blocked by CORS | Add `sentry.io` to CDN CORS policy for image assets |
| Network bodies always empty | URL not in `networkDetailAllowUrls` | Add your API domain to the allowlist |
| Network bodies empty (Apollo) | AbortController cancels before Replay reads | Don't abort on component unmount; use route-level cancellation |
| Network body truncated | > 150,000 characters | Expected behavior — limit is not configurable |
| Canvas not recording | Not added by default | Add `replayCanvasIntegration()` to `integrations` array |
| Canvas SecurityError | Cross-origin media taints canvas | Add `crossOrigin="anonymous"` to `` and enable CORS on CDN |
| WebGL canvas blank in replay | `preserveDrawingBuffer` not enabled | Use `enableManualSnapshot: true` on `replayCanvasIntegration()` |
| Rage/dead clicks on download buttons | SDK detects non-DOM-mutating clicks | Add selector to `slowClickIgnoreSelectors` |
| Replays triggered by `console.error` | `captureConsoleIntegration` sends events | Use `beforeErrorSampling` to return `false` when `event.logger === 'console'` |
| Worker CSP error in console | CSP missing `blob:` in `worker-src` | Add `worker-src 'self' blob:` or use `workerUrl` with self-hosted worker |
| High replay volume / storage costs | `replaysSessionSampleRate` too high | Lower it; keep `replaysOnErrorSampleRate: 1.0` for error coverage |
| Replay blocked by ad-blockers | Direct requests to Sentry ingest | Set `tunnel: "/sentry-tunnel"` and implement a server-side relay |
---
## Complete Configuration Reference
```typescript
import * as Sentry from "@sentry/react";
Sentry.init({
dsn: import.meta.env.VITE_SENTRY_DSN,
// ── SAMPLING (init-level, not in replayIntegration) ────────────
replaysSessionSampleRate: 0.1, // 10% full session recording
replaysOnErrorSampleRate: 1.0, // 100% error-triggered recording
integrations: [
Sentry.replayIntegration({
// ── SESSION ──────────────────────────────────────────────
stickySession: true, // survive page refreshes
minReplayDuration: 5000, // discard replays < 5s (max: 15000)
maxReplayDuration: 3600000, // cap at 1 hour (server limit)
// ── PRIVACY ──────────────────────────────────────────────
maskAllText: true, // mask all text (default: true)
maskAllInputs: true, // mask all inputs (default: true)
blockAllMedia: true, // block all media (default: true)
mask: ['.pii', '[data-sensitive]'],
unmask: ['.app-chrome', 'nav', '.public-label'],
block: ['#payment-form', '.ssn-widget'],
unblock: ['.company-logo', '.product-thumbnail'],
ignore: ['#otp-field'],
maskFn: (text) => '*'.repeat(text.length),
// ── NETWORK ──────────────────────────────────────────────
networkDetailAllowUrls: [window.location.origin, 'https://api.myapp.com'],
networkDetailDenyUrls: ['/api/auth', '/api/payment', /\/admin\//],
networkCaptureBodies: true,
networkRequestHeaders: ['X-Request-ID', 'Cache-Control'],
networkResponseHeaders: ['X-Request-ID', 'X-Response-Time'],
// ── DOM PROTECTION ────────────────────────────────────────
mutationLimit: 10000,
mutationBreadcrumbLimit: 750,
slowClickIgnoreSelectors: ['a[download]', '.copy-btn', '.print-btn'],
// ── ADVANCED ─────────────────────────────────────────────
workerUrl: '/assets/sentry-replay-worker.min.js', // if strict CSP
beforeAddRecordingEvent: (event) => {
if (event.data.tag === 'breadcrumb' &&
event.data.payload?.category === 'console') return null;
return event;
},
beforeErrorSampling: (event) => {
if (event.logger === 'console') return false;
return true;
},
}),
// Canvas recording (optional):
Sentry.replayCanvasIntegration({
enableManualSnapshot: false, // set true for WebGL/WebGPU
}),
],
});
```