docs(session-replay): Add comprehensive explanation of sampling mechanism #15941

cjy3458 · 2026-01-09T09:52:37Z

DESCRIBE YOUR PR

This PR adds comprehensive documentation explaining how Sentry's Session Replay sampling mechanism works internally.

Problem: Many developers find it confusing how replaysSessionSampleRate and replaysOnErrorSampleRate work together, especially regarding the memory buffer system and when data is actually sent to Sentry.

Solution: Added detailed technical documentation that explains:

How the 60-second memory buffer (ring buffer) works
The sampling decision flow with clear user scenarios
What data format is stored (event logs, not video)
When and how data is transmitted to Sentry
Best practices for configuration

This documentation will help developers better understand the internal mechanisms and optimize their Session Replay configuration.

IS YOUR CHANGE URGENT?

Urgent deadline (GA date, etc.):
Other deadline:
None: Not urgent, can wait up to 1 week+

SLA

Requesting review from @getsentry/docs team
Happy to wait up to 1 week for review

PRE-MERGE CHECKLIST

Checked Vercel preview for correctness, including links
(External contributor - waiting for team authorization)
PR was reviewed and approved by any necessary SMEs (subject matter experts)
PR was reviewed and approved by a member of the Sentry docs team

NOTE FOR REVIEWERS

As an external contributor, I'm unable to access the Vercel preview until authorized. I've tested the markdown formatting and links locally using yarn dev. Please let me know if you spot any issues in the preview!

LEGAL BOILERPLATE

I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms.

…nism - Explain memory buffer system - Document sampling decision flow - Add user scenario examples - Include technical implementation details

vercel · 2026-01-09T09:52:42Z

@cjy3458 is attempting to deploy a commit to the Sentry Team on Vercel.

A member of the Team first needs to authorize it.

cjy3458 · 2026-01-09T10:00:41Z

docs/product/explore/session-replay/how-it-works.mdx

+- Old events are automatically overwritten
+- No memory leak concerns
+- Stops recording after 60 minutes (hard limit)
+- Pauses when internet connection is lost


Thanks @sentry bot for catching this! You're absolutely right - the pause-on-connection-loss feature is mobile-specific. I've removed that line to avoid confusion.

Fixed in 8890311

The pause-on-connection-loss feature is specific to mobile SDKs, not web SDKs. Removed to avoid confusion.

cjy3458 · 2026-01-15T08:50:48Z

Hi team! 👋

Friendly ping - all CI checks passed and this is ready for review whenever the team has time!

Let me know if you need any clarifications. Thanks! 🙏

philprime

Thanks for opening up this PR. We appreciate everyone contributing to Sentry. I left a couple of high-priority comments we need to address. Overall I currently do not see the clear benefit of this page, as it mentions a lot of information we already have on our platform-specific session-replay related documentation for Web, Android and iOS (I am one of the iOS maintainers).

I'll leave it to the @getsentry/product-owners-docs to decide on how to proceed with this contribution, but I do not believe we can merge it as it is right now.

philprime · 2026-01-15T11:51:36Z

docs/product/explore/session-replay/how-it-works.mdx

+
+### What Gets Stored
+
+Contrary to what you might expect, Session Replay doesn't store actual video files in memory. Instead, it stores **event logs** in a structured format:


h: This applies to web, not to mobile. As this is a product page for a feature spanning all platforms we must either not mention this or make it clear that it's different and explain both applications.

philprime · 2026-01-15T11:53:14Z

docs/product/explore/session-replay/how-it-works.mdx

+
+### Buffer Duration and Size
+
+- **Duration**: 60 seconds of the most recent activity


h: This can easily be outdated and can be different per platform (it's 30 seconds for iOS apps)

https://github.com/getsentry/sentry-cocoa/blob/21cd5ba3b2bde72d691860aa30fecc430a205051/Sources/Swift/Integrations/SessionReplay/SentryReplayOptions.swift#L29

philprime · 2026-01-15T11:53:55Z

docs/product/explore/session-replay/how-it-works.mdx

+### Configuration Example
+```javascript
+Sentry.init({
+  dsn: 'YOUR_DSN',
+  replaysSessionSampleRate: 0.1,  // 10% of users
+  replaysOnErrorSampleRate: 1.0,  // 100% of error-encountering users
+});
+```


h: This can become outdated, let's reference the actual product page per platform instead using PlatformLink

philprime · 2026-01-15T11:54:43Z

docs/product/explore/session-replay/how-it-works.mdx

+   - If selected (10% chance): Full session recording starts immediately → sent to Sentry in real-time
+   - If not selected (90% chance): Recording starts but stays in memory buffer only


m: Let's not add percentages here, as they are configurable:

Suggested change

- If selected (10% chance): Full session recording starts immediately → sent to Sentry in real-time

- If not selected (90% chance): Recording starts but stays in memory buffer only

- If selected: Full session recording starts immediately → sent to Sentry in real-time

- If not selected: Recording starts but stays in memory buffer only

philprime · 2026-01-15T11:55:04Z

docs/product/explore/session-replay/how-it-works.mdx

+
+2. **Error Trigger**
+   - If an error occurs and `replaysOnErrorSampleRate` condition is met:
+     - The buffered 60 seconds *before* the error is captured


Suggested change

- The buffered 60 seconds *before* the error is captured

- The buffered 60 seconds (or as configured) *before* the error is captured

philprime · 2026-01-15T11:56:09Z

docs/product/explore/session-replay/how-it-works.mdx

+
+### Memory Management
+
+The 60-second buffer is managed as a **ring buffer**:


h: This is also different per platform. On mobile we take screenshots, mask them, then combine them into videos on-device after X seconds

philprime · 2026-01-15T11:57:09Z

docs/product/explore/session-replay/how-it-works.mdx

+### Recommended Configuration
+```javascript
+Sentry.init({
+  dsn: 'YOUR_DSN',
+
+  // Capture 10% of sessions for general monitoring
+  replaysSessionSampleRate: 0.1,
+
+  // Capture 100% of sessions where errors occur
+  replaysOnErrorSampleRate: 1.0,
+});
+```


m: This does not match the recommendation we already have in place: https://docs.sentry.io/platforms/javascript/session-replay/#recommended-production-sample-rates

…dress review feedback - Relocate from product-level to Web-specific location (docs/product/explore/session-replay/ → docs/platforms/javascript/common/session-replay/) - Address all 7 review comments from @philiprime Changes: - Add Web-specific disclaimer and platform callouts (getsentry#1, getsentry#6) - Change buffer duration to configurable with platform notes (getsentry#2) - Replace config examples with PlatformLink references (getsentry#3) - Remove hardcoded percentages from decision flow (getsentry#4) - Add '(or as configured)' qualifiers (getsentry#5) - Remove duplicate 'Recommended Configuration' section (getsentry#7) The document now focuses on Web's internal mechanism (rrweb, DOM events, ring buffer) while deferring configuration to official setup docs."

cjy3458 · 2026-01-15T15:23:00Z

@philprime

All 7 review comments addressed! 🙏

Main changes:

✅ Structural:

Moved to docs/platforms/javascript/common/session-replay/understanding-sampling.mdx
Added Web-specific disclaimers and platform difference callouts

✅ Content:

Made all technical sections Web-specific with mobile notes (event logs, ring buffer)
Changed hardcoded durations to "configurable" with platform notes
Replaced config examples with PlatformLink references
Removed hardcoded percentages from flow descriptions
Removed duplicate "Recommended Configuration" section entirely

Result: Document now focuses on Web's internal mechanism while linking to official docs for configuration.

Ready for re-review! 🚀

vercel · 2026-01-30T00:03:58Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sentry-docs	Ready	Preview, Comment	Jan 30, 2026 0:15am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ignored	Preview	Jan 30, 2026 0:15am

docs(session-replay): Add comprehensive explanation of sampling mecha…

8890311

…nism - Explain memory buffer system - Document sampling decision flow - Add user scenario examples - Include technical implementation details

sentry bot reviewed Jan 9, 2026

View reviewed changes

docs: remove incorrect claim about connection loss behavior

c716195

The pause-on-connection-loss feature is specific to mobile SDKs, not web SDKs. Removed to avoid confusion.

aldy505 requested a review from bruno-garcia January 13, 2026 09:15

rodolfoBee requested a review from a team January 13, 2026 12:07

cjy3458 marked this pull request as draft January 15, 2026 08:20

cjy3458 marked this pull request as ready for review January 15, 2026 08:23

philprime reviewed Jan 15, 2026

View reviewed changes

cjy3458 requested a review from philprime January 15, 2026 15:26

bruno-garcia requested review from jas-kas and removed request for bruno-garcia January 19, 2026 14:25

vercel bot deployed to Preview – sentry-docs January 30, 2026 00:15 View deployment


		### What Gets Stored

		Contrary to what you might expect, Session Replay doesn't store actual video files in memory. Instead, it stores event logs in a structured format:


		### Buffer Duration and Size

		- Duration: 60 seconds of the most recent activity

		- If selected (10% chance): Full session recording starts immediately → sent to Sentry in real-time
		- If not selected (90% chance): Recording starts but stays in memory buffer only

	- The buffered 60 seconds before the error is captured
	- The buffered 60 seconds (or as configured) before the error is captured


		### Memory Management

		The 60-second buffer is managed as a ring buffer:

Uh oh!

docs(session-replay): Add comprehensive explanation of sampling mechanism #15941

Are you sure you want to change the base?

docs(session-replay): Add comprehensive explanation of sampling mechanism #15941

Uh oh!

Conversation

cjy3458 commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

DESCRIBE YOUR PR

IS YOUR CHANGE URGENT?

SLA

PRE-MERGE CHECKLIST

NOTE FOR REVIEWERS

LEGAL BOILERPLATE

Uh oh!

vercel bot commented Jan 9, 2026

Uh oh!

This comment was marked as outdated.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cjy3458 commented Jan 15, 2026

Uh oh!

philprime left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cjy3458 commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cjy3458 commented Jan 9, 2026 •

edited

Loading

cjy3458 commented Jan 15, 2026 •

edited

Loading

vercel bot commented Jan 30, 2026 •

edited

Loading