How do I turn on Sentry Session Replay for my frontend and limit it to errors only?

Most teams want the context of what a user did before an error—but not a full replay of every single session. The good news: you can turn on Sentry Session Replay for your frontend and configure it so replays are only captured when there’s an error, keeping both noise and cost under control.

Quick Answer: Install the Sentry SDK with Session Replay enabled on your frontend, then configure the replaysOnErrorSampleRate option (and set replaysSessionSampleRate to 0). This tells Sentry to only record replays when an error event is captured from that session.

The Quick Overview

What It Is: Sentry Session Replay is a feature that captures a pixel-perfect recording of a user’s browser session—DOM changes, clicks, page transitions—tied directly to Sentry error and performance data.
Who It Is For: Frontend and full‑stack teams who want to see exactly what users did before an error or crash, without collecting unnecessary replay data.
Core Problem Solved: “We see an error stack trace, but we don’t know what the user did to trigger it.” Session Replay fills this gap with visual, time‑ordered context.

How It Works

At a high level, you:

Install and configure the Sentry SDK on your frontend app.
Enable the Replay integration with sampling options that restrict recording to error-triggered sessions.
Deploy and verify that new errors in production now show a “Replay” panel, letting you jump from stack trace to user behavior in one click.

Under the hood:

The Sentry SDK captures browser events (DOM changes, clicks, navigation).
You control how often sessions are sampled via replaysSessionSampleRate and replaysOnErrorSampleRate.
When an error (or other configured event) occurs in a sampled session, Sentry finalizes the replay and associates it with the corresponding issue.

Let’s walk through how to wire this up for a typical frontend setup.

Step 1: Install Sentry with Session Replay on Your Frontend

The exact package and setup depends on your stack, but the pattern is similar: initialize Sentry in your main entry file and add the Replay integration.

Example: React / Browser SDK

If you’re using the standard browser SDK:

npm install @sentry/browser @sentry/replay
# or
yarn add @sentry/browser @sentry/replay

Initialize Sentry (for example, in index.tsx or main.ts):

import * as Sentry from "@sentry/browser";
import { Replay } from "@sentry/replay";

Sentry.init({
  dsn: "https://YOUR_DSN_HERE.ingest.sentry.io/PROJECT_ID",

  integrations: [
    new Replay({
      // You can keep Replay-specific advanced options here if needed
    }),
  ],

  // Other recommended options
  tracesSampleRate: 0.1, // example for Performance
  environment: "production",
  release: "my-frontend@1.0.0",
});

For frameworks like Next.js, Remix, SvelteKit, Vue, and Angular, the Replay integration is similar—just follow the framework‑specific docs to know where to call Sentry.init, then add the Replay integration object and sampling options as shown below.

Step 2: Limit Session Replay to Errors Only

The key to “errors only” is the sampling configuration. There are two knobs:

replaysSessionSampleRate: baseline sampling of all sessions.
replaysOnErrorSampleRate: sampling for sessions where an error occurs.

To capture replays only when an error is present:

Set replaysSessionSampleRate to 0 (no generic session replays).
Set replaysOnErrorSampleRate to a non‑zero value (e.g., 1.0 for “capture every error session”).

Recommended “Errors Only” Config

import * as Sentry from "@sentry/browser";
import { Replay } from "@sentry/replay";

Sentry.init({
  dsn: "https://YOUR_DSN_HERE.ingest.sentry.io/PROJECT_ID",

  integrations: [new Replay()],

  // Do NOT record random sessions
  replaysSessionSampleRate: 0.0,

  // Record sessions when they experience an error
  // 1.0 = 100% of error sessions, 0.5 = 50%, etc.
  replaysOnErrorSampleRate: 1.0,

  // Optional: Performance if you want traces linked as well
  tracesSampleRate: 0.1,
});

What this does in practice:

User sessions that never hit an error are not recorded as replays.
When a session reports an error, Sentry records a replay (respecting your configured sampling rate), and that replay is linked to the error issue.
You can click into “Replay” from the Sentry issue to see exactly what led up to the error.

If your volume is high and cost is a concern, start with 0.2–0.5 for replaysOnErrorSampleRate and adjust once you have real event counts.

Step 3: Verify Replays in Sentry

Once deployed:

Trigger a test error in your app
- For example, add a temporary button that calls throw new Error("Test Session Replay error") in a production-like environment (staging with the same Sentry project is fine for proving the setup).
Confirm the error in Sentry
- Go to your Sentry project → Issues.
- Open the new error and scroll the sidebar or navigation for the Replay tab.
Check the replay
- You should see a timeline of DOM events, user interactions, and console logs.
- The error timestamp should line up with the moment the UI broke in the replay.

If you see the error but no replay:

Double‑check that:
- Replay is present in integrations.
- replaysOnErrorSampleRate is > 0.
- You’re testing in an environment that matches your environment filters in Sentry.
- Ad blockers or strict Content Security Policy aren’t blocking Sentry requests.

Features & Benefits Breakdown

Core Feature	What It Does	Primary Benefit
Error‑linked Session Replay	Captures user sessions only when errors occur, based on sampling options.	Focuses on the most critical scenarios without recording every single session.
Code‑level Issue Context	Ties replay to errors, stack traces, tags, and spans (tracing).	Lets you move from “what the user saw” to “which line and release broke” fast.
Privacy & Sampling Controls	Configure sampling, blocklists, and PII scrubbing in the SDK and project.	Gives you control over data volume and user privacy while still getting context.

Ideal Use Cases

Best for production debugging: Because it shows how real users hit real errors without developers needing to reproduce complex click paths locally.
Best for high‑traffic apps with cost control needs: Because you can set replaysSessionSampleRate to 0 and only pay for replays when they’re tied to actual errors.

Limitations & Considerations

Sampling is probabilistic: Even with replaysOnErrorSampleRate > 0, replays are sampled. If you absolutely need a replay for every single error, keep replaysOnErrorSampleRate at 1.0 and monitor volume.
Frontend‑only visibility: Session Replay runs in the browser. It shows what the user did in the UI, but backend‑only failures still need Performance (traces/spans), logs, or profiling for full context.

Pricing & Plans

Replay usage is metered separately from errors, transactions, and other event types. You can:

Reserve a baseline volume for discounts.
Add pay‑as‑you‑go budget for when you need more replays (for example, after a big launch).

Plan context (high level):

Developer / Team: Best for small teams or single apps needing replay tied to errors and basic quotas they can tune per project.
Business+ / Enterprise: Best for organizations that need higher volumes, SAML + SCIM, governance controls, and help from a technical account manager to right‑size replay quotas across many teams.

Check current pricing on Sentry’s site; Replay volumes and overage budgets are spelled out there so you can pick sample rates that fit your budget.

Frequently Asked Questions

Do I need to enable Session Replay for every environment?

Short Answer: No. You usually enable it only for production (and sometimes staging).

Details:
You can control environments in two places:

In the SDK via the environment option (for example, environment: "production").
In Sentry’s project settings with environment filters.

A common pattern: enable Replay in production to capture real‑user behavior, and optionally in staging when you want to debug a tricky bug with “live” repro steps. For local development, replays usually don’t add much value and can clutter your project.

Can I further limit what Session Replay captures for privacy or performance?

Short Answer: Yes. You can scrub data, mask elements, and tune sampling rates.

Details:
Replay supports:

Element masking: Mark sensitive components (for example, password fields, payment forms) to be masked or excluded.
PII scrubbing: Use Sentry’s data scrubbing settings to filter out sensitive values before they’re stored.
Lower sampling rates: Use replaysOnErrorSampleRate < 1.0 if your app has high error volume or you need tighter cost control.

This gives you practical control: you get the debugging context you need while respecting user privacy and your budget.

Summary

To turn on Sentry Session Replay for your frontend and limit it to errors only, add the Replay integration to your Sentry SDK initialization and set:

replaysSessionSampleRate: 0.0,
replaysOnErrorSampleRate: 1.0, // or a lower fraction if needed

That configuration tells Sentry: “Only record replays when something actually breaks.” You keep your debugging context high—stack trace + replay of what the user did—while keeping both noise and replay volume low.

Next Step

Get Started