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

When you enable Sentry Session Replay on a frontend, you don’t have to record every single user visit. You can configure Replay so it only records when there’s an error or performance issue, which keeps costs and noise under control while still giving you the “what the user saw” context you actually need.

Quick Answer: Turn on Session Replay by adding the Replay integration to your Sentry SDK initialization in your frontend, then use Replay sampling options (like sessionSampleRate and errorSampleRate) so you only capture replays when errors or slowdowns happen.

The Quick Overview

• What It Is: Session Replay is Sentry’s visual playback of real user sessions, stitched to your errors, performance issues, logs, and traces. It lets you watch what happened right before, during, and after a failure.
• Who It Is For: Frontend and full‑stack developers, SREs, and QA teams who need to see the exact user journey behind production issues without drowning in recordings.
• Core Problem Solved: “I see the stack trace, but I still don’t know what the user did to trigger this error” and “I can’t reproduce this bug locally.”

How It Works

You instrument your frontend with the Sentry JavaScript SDK (or framework SDK like React, Next.js, Vue, etc.), then enable the Replay integration. The SDK listens for user interactions and DOM changes and, based on your sampling configuration, sends replay data to Sentry when a session qualifies (for example, when an error occurs). Sentry links that replay with related errors, transactions, logs, and profiling data into a single issue so you can debug from one place.

At a high level:

1. Instrument the frontend SDK:
   Add Sentry (with the Replay integration) to your app’s entry point and connect it to your Sentry project.

2. Configure error‑only sampling:
   Tune the replay sample rates so you don’t capture every session, just the ones with errors or performance problems.

3. Debug with linked replays:
   Use the Issue Details page (Errors or Performance) to open the corresponding replay, watch the user journey, and jump back into code with stack traces, spans, and Suspect Commits.

---

Step 1: Add Sentry Session Replay to Your Frontend

Basic JavaScript (Browser) Example

If you’re using the base @sentry/browser JS SDK, your initialization will look roughly like this:

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

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",

  integrations: [
    new Replay({
      // You’ll tune these in Step 2
      sessionSampleRate: 0.0, // 0% of normal sessions
      errorSampleRate: 1.0,   // 100% of sessions with an error
    }),
  ],

  // Optional but recommended for better context:
  tracesSampleRate: 1.0, // or a lower rate appropriate for your traffic
  environment: "production",
  release: "my-frontend-app@1.0.0",
});

The key things:

• Add Replay to your integrations.
• Configure sessionSampleRate and errorSampleRate (we’ll dive into the “errors only” setup next).
• Make sure this runs early in your app lifecycle (for SPAs, as early in the entry file as possible).

Framework Examples

The pattern is the same with framework SDKs: import Replay, add it to integrations, and set the sample rates.

React (using @sentry/react)

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

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [
    new Replay({
      sessionSampleRate: 0.0,
      errorSampleRate: 1.0,
    }),
  ],
  tracesSampleRate: 1.0,
});

Next.js (edge or Node runtime will differ, but Replay is browser‑only)

Use the client-side init (for example, in sentry.client.config.(js|ts)):

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

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [new Replay({ sessionSampleRate: 0.0, errorSampleRate: 1.0 })],
  tracesSampleRate: 1.0,
});

The important bit: make sure Replay is only configured in browser/client contexts, not server-only code.

---

Step 2: Limit Session Replay to Errors Only

Session Replay uses two primary knobs:

• sessionSampleRate: the percentage of all sessions that get a replay.
• errorSampleRate: the percentage of sessions with an error that get a replay.

To capture replays only when errors happen, you typically:

• Set sessionSampleRate to 0.0 (or very close to 0).
• Set errorSampleRate to 1.0 (or a lower percentage if you have very high error volume).

Error‑Only Configuration Example

new Replay({
  // Do not record "normal" sessions
  sessionSampleRate: 0.0,

  // Record all sessions where an error occurs
  errorSampleRate: 1.0,
});

What this does:

• A user session with no errors → no replay captured.
• A session where the SDK reports an unhandled exception or error event → replay starts (or is kept) and is attached to the error issue.

You can adjust the rates for cost control:

• Heavy traffic, high error volume: errorSampleRate: 0.3 (30% of error sessions).
• Light traffic, need more visibility: keep errorSampleRate: 1.0.

Limiting to Errors and Performance Slowdowns

If you also want replays for slow transactions (e.g., page loads over 2 seconds), pair Replay with Performance (Tracing):

1. Enable tracing:

   Sentry.init({
     // ...
     tracesSampleRate: 1.0, // Or lower, depending on volume
   });
   

2. Configure performance alerts (in Sentry UI) for slow transactions.

3. In practice, your tracing + Replay setup means:

   • Slow transaction → Sentry creates a Performance issue.
   • If that session hits your errorSampleRate rule (or you also use performance-based sampling where available), you’ll see a Replay linked on the issue.

The net effect: you get replays for “bad” sessions—crashes, errors, or slowdowns—without turning on wall‑to‑wall recording.

---

Step 3: Verify Session Replay Is Working

Once you deploy the Replay configuration:

1. Trigger a test error in your frontend:

   // Somewhere in a dev route or test button
   throw new Error("Sentry Session Replay test error");
   

2. Open Sentry → Issues (Errors):

   • Confirm the test error shows up.
   • Open the issue details and look for the Session Replay tab or replay side panel.

3. Play the replay:

   • You should see DOM changes, clicks, navigation, and console logs from the session where the error occurred.
   • Validate that environment and release metadata are correct so you can filter by them later.

If you don’t see a replay:

• Double‑check sessionSampleRate / errorSampleRate values.
• Confirm you added Replay to integrations in a browser‑executed file.
• Make sure ad blockers or privacy extensions aren’t blocking Sentry in your test.

---

Features & Benefits Breakdown

Core Feature	What It Does	Primary Benefit
Session Replay (error-only mode)	Captures visual replays only for sessions with errors or issues.	Gives you “what the user did” context without recording every session.
Error + Replay linking	Attaches replays directly to error issues and performance issues.	Reduces triage time; no more jumping between tools to correlate data.
Tracing and Replay together	Connects spans/transactions to replays and stack traces.	Lets you move from “this page is slow” to the exact code and experience.

---

Ideal Use Cases

• Best for production debugging:
  Because it captures replays only when things break, you get high‑signal sessions for real users without blowing through quotas.

• Best for targeted QA in staging:
  Because you can turn up sessionSampleRate in non‑prod and keep errorSampleRate high, your QA team can reproduce issues and you can watch exactly how they broke the app.

---

Limitations & Considerations

• Browser‑only capture:
  Replay runs in the browser, so it doesn’t show what happens purely on the backend. Pair it with traces and logs to see the full request path across services.

• Sampling vs. 100% coverage:
  With sessionSampleRate: 0.0 and errorSampleRate < 1.0, not every error session will have a replay. If a specific incident matters a lot, temporarily increase errorSampleRate or adjust project quotas.

---

Pricing & Plans

Session Replay is a quota‑based add‑on in Sentry. You control how much you use it via:

• Replay event quotas: Define how many replays you want per month.
• Sampling controls: Use sessionSampleRate and errorSampleRate to stay within budget.
• Pay-as-you-go overages: If you exceed quota and opt in, you can keep capturing at a per‑event rate.

Typical fit:

• Developer / Team plans: Best for product teams that want Replay for frontends and care about tying bugs to actual user experience.
• Business / Enterprise: Best for organizations that need wide deployment, governance (SAML/SCIM, audit logs), and dedicated support, especially when rolling Replay out across multiple apps.

For exact pricing, check the pricing page in your Sentry account or contact Sales.

---

Frequently Asked Questions

Do I have to record every user session to use Sentry Session Replay effectively?

Short Answer: No. You can record only sessions with errors (or a sample of them) using Replay’s sampling options.

Details:
Set sessionSampleRate to 0.0 (no normal sessions recorded) and errorSampleRate to something like 1.0 for full coverage of error sessions, or a lower rate if you have very high error volume. This way, Replay is effectively “errors only” and you still get rich context where it matters most—on broken sessions—without turning Sentry into a 24/7 screen recorder for your entire user base.

---

How does Sentry know when to attach a replay to an error?

Short Answer: When a replayed session sends an error event, Sentry links that replay with the error issue automatically.

Details:
The Sentry SDK records replay data for sessions covered by your sampling rules. If that same session also sends an error event (for example, an unhandled exception or logged error that the SDK captures), Sentry associates the replay with the resulting issue. In the UI, you’ll see a Replay tab or panel on the issue details page. From there, you can:

• Watch the user journey around the error.
• View console logs, network activity, and DOM changes.
• Jump into stack traces, related spans, and Suspect Commits to find and fix the problem.

---

Summary

Turning on Sentry Session Replay for your frontend and limiting it to errors only is essentially three steps: add the Replay integration to your frontend SDK, tune sessionSampleRate to 0.0 and errorSampleRate to the level of coverage you want, then verify replays show up alongside your error issues. You get just the sessions that matter—where things broke—tied directly to stack traces, spans, and commits, so you can spend less time guessing what a user did and more time fixing the code.

Next Step

Get Started