docs(session-replay): Add comprehensive explanation of sampling mechanism#15941
docs(session-replay): Add comprehensive explanation of sampling mechanism#15941cjy3458 wants to merge 3 commits intogetsentry:masterfrom
Conversation
…nism - Explain memory buffer system - Document sampling decision flow - Add user scenario examples - Include technical implementation details
|
@cjy3458 is attempting to deploy a commit to the Sentry Team on Vercel. A member of the Team first needs to authorize it. |
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
| - Old events are automatically overwritten | ||
| - No memory leak concerns | ||
| - Stops recording after 60 minutes (hard limit) | ||
| - Pauses when internet connection is lost |
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
The pause-on-connection-loss feature is specific to mobile SDKs, not web SDKs. Removed to avoid confusion.
|
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
left a comment
philprime
left a comment
There was a problem hiding this comment.
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.
|
|
||
| ### 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: |
There was a problem hiding this comment.
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.
|
|
||
| ### Buffer Duration and Size | ||
|
|
||
| - **Duration**: 60 seconds of the most recent activity |
There was a problem hiding this comment.
h: This can easily be outdated and can be different per platform (it's 30 seconds for iOS apps)
| ### Configuration Example | ||
| ```javascript | ||
| Sentry.init({ | ||
| dsn: 'YOUR_DSN', | ||
| replaysSessionSampleRate: 0.1, // 10% of users | ||
| replaysOnErrorSampleRate: 1.0, // 100% of error-encountering users | ||
| }); | ||
| ``` |
There was a problem hiding this comment.
h: This can become outdated, let's reference the actual product page per platform instead using PlatformLink
| - 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 |
There was a problem hiding this comment.
m: Let's not add percentages here, as they are configurable:
| - 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 |
|
|
||
| 2. **Error Trigger** | ||
| - If an error occurs and `replaysOnErrorSampleRate` condition is met: | ||
| - The buffered 60 seconds *before* the error is captured |
There was a problem hiding this comment.
| - 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**: |
There was a problem hiding this comment.
h: This is also different per platform. On mobile we take screenshots, mask them, then combine them into videos on-device after X seconds
| ### 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, | ||
| }); | ||
| ``` |
There was a problem hiding this comment.
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."
|
All 7 review comments addressed! 🙏 Main changes: ✅ Structural:
✅ Content:
Result: Document now focuses on Web's internal mechanism while linking to official docs for configuration. Ready for re-review! 🚀 |
bruno-garcia
requested review from
jas-kas
and removed request for
bruno-garcia
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
## DESCRIBE YOUR PR Condenses #15941 - updates session replay docs for more clarity about how it works with sampling. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. - [ ] Urgent deadline (GA date, etc.): <!-- ENTER DATE HERE --> - [ ] Other deadline: <!-- ENTER DATE HERE --> - [x] None: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it. Thanks in advance for your help! ## PRE-MERGE CHECKLIST *Make sure you've checked the following before merging your changes:* - [ ] Checked Vercel preview for correctness, including links - [ ] 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](https://github.com/orgs/getsentry/teams/docs) --------- Co-authored-by: Shannon Anahata <shannonanahata@gmail.com> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
3 participants
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
replaysSessionSampleRateandreplaysOnErrorSampleRatework together, especially regarding the memory buffer system and when data is actually sent to Sentry.Solution: Added detailed technical documentation that explains:
This documentation will help developers better understand the internal mechanisms and optimize their Session Replay configuration.
IS YOUR CHANGE URGENT?
SLA
PRE-MERGE CHECKLIST
(External contributor - waiting for team authorization)
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.