Session Replay - Sentry JavaScript SDK

Session Replay lets you watch a video-like reproduction of user sessions, helping you understand exactly what users experienced when issues occurred.

Setup

Enable Session Replay during SDK initialization:

import * as Sentry from '@sentry/browser';

Sentry.init({
  dsn: 'your-dsn',
  
  // Session Replay
  integrations: [
    Sentry.replayIntegration({
      // Capture 10% of all sessions
      sessionSampleRate: 0.1,
      // Capture 100% of sessions with errors
      errorSampleRate: 1.0,
    }),
  ],
  
  // Also enable performance monitoring for best results
  tracesSampleRate: 1.0,
});

Session Replay requires the @sentry/replay package or using a bundle that includes it (like @sentry/browser).

Sampling

Session Sample Rate

Percentage of all sessions to record:

Sentry.replayIntegration({
  sessionSampleRate: 0.1 // Record 10% of all sessions
})

Error Sample Rate

Percentage of sessions with errors to record:

Sentry.replayIntegration({
  errorSampleRate: 1.0 // Record 100% of sessions with errors
})

Combined Strategy

Sentry.init({
  dsn: 'your-dsn',
  integrations: [
    Sentry.replayIntegration({
      // Always record sessions with errors
      errorSampleRate: 1.0,
      // Sample 5% of normal sessions
      sessionSampleRate: 0.05,
    }),
  ],
});

Start with high errorSampleRate (1.0) and low sessionSampleRate (0.01-0.1) to capture issues while managing costs.

Recording Modes

Session Mode

Continuously records the entire session:

Sentry.replayIntegration({
  sessionSampleRate: 0.1,
  // Session mode: records from the start
})

Buffer Mode (Error-Only)

Only keeps the last 60 seconds in memory, saves to Sentry when an error occurs:

Sentry.replayIntegration({
  // Only record when errors occur
  sessionSampleRate: 0,
  errorSampleRate: 1.0,
})

Buffer mode is more efficient as it only uploads replay data when an error actually happens.

Configuration Options

Basic Options

Sentry.replayIntegration({
  // Sampling
  sessionSampleRate: 0.1,
  errorSampleRate: 1.0,
  
  // Mask all text content
  maskAllText: true,
  
  // Block all media elements (img, video, audio)
  blockAllMedia: true,
  
  // Network details
  networkDetailAllowUrls: ['https://api.example.com'],
  networkCaptureBodies: true,
  networkRequestHeaders: ['Authorization'],
  networkResponseHeaders: ['X-Request-ID'],
})

Privacy Options

Sentry.replayIntegration({
  // Mask all text by default
  maskAllText: true,
  
  // Mask specific selectors
  mask: ['.sensitive-data', '#credit-card'],
  
  // Block elements from recording
  block: ['.advertisement', '.third-party-widget'],
  
  // Unmask specific elements
  unmask: ['.public-info'],
  
  // Block all media
  blockAllMedia: true,
})

Privacy Controls

Masking Text

Mask sensitive text automatically:

<!-- All text inside will be masked -->
<div class="sentry-mask">
  <p>Sensitive information</p>
  <span>Credit card: 1234-5678-9012-3456</span>
</div>

Or configure via JavaScript:

Sentry.replayIntegration({
  mask: ['.payment-info', '.personal-data']
})

Blocking Elements

Completely block elements from being recorded:

<!-- Element will show as placeholder -->
<div class="sentry-block">
  <img src="sensitive-photo.jpg" />
</div>

Or configure via JavaScript:

Sentry.replayIntegration({
  block: ['.profile-photo', '.private-content']
})

Unmasking Elements

Unmask specific elements when maskAllText is enabled:

<!-- This text will NOT be masked -->
<div class="sentry-unmask">
  <p>This public text is visible in replays</p>
</div>

Carefully review what data is captured. Always err on the side of privacy when handling sensitive user information.

Network Recording

Capture Network Requests

Sentry.replayIntegration({
  networkDetailAllowUrls: [
    // Capture details for these URLs
    'https://api.example.com',
    /^https:\/\/.*\.example\.com/,
  ],
  
  // Capture request/response bodies
  networkCaptureBodies: true,
  
  // Capture request headers
  networkRequestHeaders: ['Content-Type', 'Authorization'],
  
  // Capture response headers
  networkResponseHeaders: ['Content-Type', 'X-Request-ID'],
})

Network Privacy

Sentry.replayIntegration({
  networkDetailAllowUrls: ['https://api.example.com'],
  
  // Don't capture bodies (more private)
  networkCaptureBodies: false,
  
  // Only capture safe headers
  networkRequestHeaders: ['Content-Type'],
  networkResponseHeaders: ['Content-Type'],
})

Console Logs

Include console logs in replays:

Sentry.init({
  dsn: 'your-dsn',
  integrations: [
    Sentry.replayIntegration(),
    // Capture console logs
    Sentry.captureConsoleIntegration({
      levels: ['log', 'info', 'warn', 'error', 'debug']
    }),
  ],
});

Canvas Recording

Record canvas elements (experimental):

import * as Sentry from '@sentry/browser';
import { replayCanvasIntegration } from '@sentry/replay-canvas';

Sentry.init({
  dsn: 'your-dsn',
  integrations: [
    Sentry.replayIntegration(),
    // Add canvas recording
    replayCanvasIntegration(),
  ],
});

Canvas recording is experimental and may impact performance. Use only when necessary.

Manual Control

Start/Stop Recording

import { getClient } from '@sentry/browser';

const client = getClient();
const replay = client?.getIntegrationByName('Replay');

if (replay) {
  // Start recording
  replay.start();
  
  // Stop recording
  replay.stop();
  
  // Flush current replay
  await replay.flush();
}

Conditional Recording

// Only record for authenticated users
if (user.isAuthenticated) {
  const replay = client?.getIntegrationByName('Replay');
  replay?.start();
}

Integration with Errors

Replays are automatically linked to errors:

try {
  riskyOperation();
} catch (error) {
  // Error is automatically linked to the replay
  Sentry.captureException(error);
}

Integration with Performance

Combine replays with performance monitoring:

Sentry.init({
  dsn: 'your-dsn',
  
  // Enable both
  integrations: [
    Sentry.replayIntegration({
      sessionSampleRate: 0.1,
      errorSampleRate: 1.0,
    }),
  ],
  
  tracesSampleRate: 1.0,
});

Replays show performance spans as part of the timeline.

Performance Impact

Optimization Tips

Use buffer mode: Only record when errors occur
Lower sample rates: Record fewer sessions
Block media: Reduce data capture size
Mask text: Use CSS masking instead of JS
Limit network detail: Only capture essential APIs

// Optimized configuration
Sentry.replayIntegration({
  // Only record errors
  sessionSampleRate: 0,
  errorSampleRate: 1.0,
  
  // Reduce data size
  maskAllText: true,
  blockAllMedia: true,
  
  // Minimal network capture
  networkDetailAllowUrls: [],
  networkCaptureBodies: false,
})

Example Configurations

Development

Sentry.replayIntegration({
  // Record everything in development
  sessionSampleRate: 1.0,
  errorSampleRate: 1.0,
  
  // Less privacy restrictions
  maskAllText: false,
  blockAllMedia: false,
  
  // Capture full network details
  networkDetailAllowUrls: ['*'],
  networkCaptureBodies: true,
})

Production

Sentry.replayIntegration({
  // Conservative sampling
  sessionSampleRate: 0.01, // 1% of sessions
  errorSampleRate: 1.0,     // 100% of errors
  
  // Strong privacy
  maskAllText: true,
  blockAllMedia: true,
  
  // Limited network capture
  networkDetailAllowUrls: ['https://api.example.com'],
  networkCaptureBodies: false,
})

E-commerce

Sentry.replayIntegration({
  sessionSampleRate: 0.05,
  errorSampleRate: 1.0,
  
  // Mask sensitive areas
  mask: [
    '.payment-form',
    '.credit-card-input',
    '.cvv-input',
    '[data-sensitive]'
  ],
  
  // Block sensitive elements
  block: [
    '.user-photo',
    '.signature'
  ],
  
  // Capture checkout API only
  networkDetailAllowUrls: ['https://api.example.com/checkout'],
  networkCaptureBodies: false,
})

Viewing Replays

Replays appear in the Sentry UI:

Issues: Linked to error events
Replays Tab: Browse all recorded sessions
Performance: Associated with transactions

Each replay includes:

Visual recording of the session
Console logs
Network activity
Performance data
Breadcrumbs
Custom events

Best Practices

Start conservative: Low sample rates, high privacy
Monitor costs: Replays can increase data volume significantly
Respect privacy: Mask sensitive data by default
Test thoroughly: Verify masking works as expected
Use buffer mode: More efficient for error debugging
Combine with performance: Get complete context
Review regularly: Ensure no PII is captured

Privacy Checklist:

Mask all text inputs
Block sensitive media
Don’t capture auth tokens
Exclude third-party content
Review captured network data
Comply with GDPR/privacy laws

Troubleshooting

Replays Not Recording

// Check if replay is enabled
const client = Sentry.getClient();
const replay = client?.getIntegrationByName('Replay');

if (!replay) {
  console.error('Replay integration not found');
}

// Check sampling
console.log('Session sample rate:', replay.options.sessionSampleRate);
console.log('Error sample rate:', replay.options.errorSampleRate);

High Memory Usage

// Use buffer mode instead of session mode
Sentry.replayIntegration({
  sessionSampleRate: 0,
  errorSampleRate: 1.0,
})

Next Steps

Error Monitoring

Link replays with error events

Performance

Combine replays with performance data

Breadcrumbs

Track user actions in replays

User Feedback

Collect feedback during sessions

Error Monitoring

Performance Monitoring

Advanced Features

​Setup

​Sampling

​Session Sample Rate

​Error Sample Rate

​Combined Strategy

​Recording Modes

​Session Mode

​Buffer Mode (Error-Only)

​Configuration Options

​Basic Options

​Privacy Options

​Privacy Controls

​Masking Text

​Blocking Elements

​Unmasking Elements

​Network Recording

​Capture Network Requests

​Network Privacy

​Console Logs

​Canvas Recording

​Manual Control

​Start/Stop Recording

​Conditional Recording

​Integration with Errors

​Integration with Performance

​Performance Impact

​Optimization Tips

​Example Configurations

​Development

​Production

​E-commerce

​Viewing Replays

​Best Practices

​Troubleshooting

​Replays Not Recording

​High Memory Usage

​Next Steps

Error Monitoring

Performance

Breadcrumbs

User Feedback

Build docs developers (and LLMs) love

Setup

Sampling

Session Sample Rate

Error Sample Rate

Combined Strategy

Recording Modes

Session Mode

Buffer Mode (Error-Only)

Configuration Options

Basic Options

Privacy Options

Privacy Controls

Masking Text

Blocking Elements

Unmasking Elements

Network Recording

Capture Network Requests

Network Privacy

Console Logs

Canvas Recording

Manual Control

Start/Stop Recording

Conditional Recording

Integration with Errors

Integration with Performance

Performance Impact

Optimization Tips

Example Configurations

Development

Production

E-commerce

Viewing Replays

Best Practices

Troubleshooting

Replays Not Recording

High Memory Usage

Next Steps