From 889031136ddde386eeb641ccb7a62e07bf93bf9d Mon Sep 17 00:00:00 2001 From: cjy3458 Date: Fri, 9 Jan 2026 18:48:45 +0900 Subject: [PATCH 1/3] docs(session-replay): Add comprehensive explanation of sampling mechanism - Explain memory buffer system - Document sampling decision flow - Add user scenario examples - Include technical implementation details --- .../explore/session-replay/how-it-works.mdx | 181 ++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 docs/product/explore/session-replay/how-it-works.mdx diff --git a/docs/product/explore/session-replay/how-it-works.mdx b/docs/product/explore/session-replay/how-it-works.mdx new file mode 100644 index 0000000000000..7b079e6900fca --- /dev/null +++ b/docs/product/explore/session-replay/how-it-works.mdx @@ -0,0 +1,181 @@ +--- +title: "How Session Replay Sampling Works" +sidebar_order: 15 +description: "Understand the internal mechanism of Session Replay sampling and memory buffering" +--- + +# How Session Replay Sampling Works + +Understanding how Sentry's Session Replay sampling mechanism works internally can help you optimize your configuration and predict what data will be captured. + +## Overview + +Session Replay uses two sampling rates that work together: + +- **`replaysSessionSampleRate`**: Percentage of users who get their entire session recorded +- **`replaysOnErrorSampleRate`**: Percentage of error-encountering users whose sessions get recorded + +The key to understanding how these work together is the **memory buffer**. + +## Memory Buffer System + +### 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: +```javascript +// Example event log entries +{ time: 1234, type: 'click', x: 100, y: 200 } +{ time: 1235, type: 'input', value: 'cat' } +{ time: 1236, type: 'scroll', x: 0, y: 500 } +``` + +These event logs are: +- **Lightweight**: Approximately 2-5MB for 60 seconds of activity +- **Structured**: JSON-like format capturing DOM mutations, user interactions, and console logs +- **Reconstructible**: Sentry's server automatically converts these logs into video-like replays + +### Buffer Duration and Size + +- **Duration**: 60 seconds of the most recent activity +- **Memory footprint**: 2-5MB typically +- **Storage location**: In-memory ring buffer (overwrites old data) +- **Network impact**: Only sent to Sentry when conditions are met + +## How Sampling Decisions Work + +### Configuration Example +```javascript +Sentry.init({ + dsn: 'YOUR_DSN', + replaysSessionSampleRate: 0.1, // 10% of users + replaysOnErrorSampleRate: 1.0, // 100% of error-encountering users +}); +``` + +### Decision Flow + +When a user visits your application: + +1. **Initial Sampling Decision** + - A random number determines if the user is selected for `replaysSessionSampleRate` + - 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 + +2. **Error Trigger** + - If an error occurs and `replaysOnErrorSampleRate` condition is met: + - The buffered 60 seconds *before* the error is captured + - Recording continues until the session ends + - Everything is sent to Sentry + +## User Scenarios + +### 👮 Scenario A: Full Session Recording (No Error) + +**User type**: Selected for `replaysSessionSampleRate` (10% probability) +``` +1. User visits site +2. Random selection → Selected (10% chance) +3. Recording starts → Sent to Sentry in real-time +4. User browses for 5 minutes +5. Session ends normally +6. ✅ Full 5-minute replay available in Sentry +``` + +**Result**: Complete session visible in Sentry dashboard + +--- + +### 🥷 Scenario B: Not Selected, No Error + +**User type**: Not selected for `replaysSessionSampleRate` (90% probability) +``` +1. User visits site +2. Random selection → Not selected (90% chance) +3. Recording starts → Stored in 60-second memory buffer only +4. User browses normally (no errors) +5. Session ends +6. Memory buffer discarded +7. ❌ No replay in Sentry +``` + +**Result**: No session data sent to Sentry (saves quota) + +--- + +### 👰 Scenario C: Not Selected Initially, But Error Occurs + +**User type**: Not selected initially, but encounters error +``` +1. User visits site +2. Random selection → Not selected (90% chance) +3. Recording starts → Stored in 60-second memory buffer only +4. User browses for 2 minutes +5. 🚨 Error occurs! +6. Check replaysOnErrorSampleRate (1.0 = 100%) +7. Memory buffer (last 60 seconds) → Sent to Sentry +8. Continue recording until session ends +9. ✅ Replay available showing 60s before error + everything after +``` + +**Result**: Error replay with valuable context before the error occurred + +--- + +## Key Technical Points + +### Why Event Logs Instead of Video? + +1. **Privacy**: Text can be masked, images can be blocked +2. **Size**: Event logs are much smaller than video +3. **Flexibility**: Can redact sensitive data before sending +4. **Performance**: Minimal impact on browser performance + +### When Data Is Sent to Sentry + +| Scenario | When Data Leaves Browser | +|----------|-------------------------| +| Selected for session sampling | Immediately, in real-time chunks | +| Not selected, no error | Never (discarded) | +| Not selected, error occurs | After error + buffer is sent | + +### Memory Management + +The 60-second buffer is managed as a **ring buffer**: +- Old events are automatically overwritten +- No memory leak concerns +- Stops recording after 60 minutes (hard limit) +- Pauses when internet connection is lost + +## Best Practices + +### 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, +}); +``` + +This configuration: +- ✅ Monitors general user behavior (10% sample) +- ✅ Captures critical error scenarios (100% of errors) +- ✅ Manages quota efficiently +- ✅ Provides valuable debugging context + +### Adjusting for Your Needs + +- **High-traffic site**: Lower `replaysSessionSampleRate` to 0.01 (1%) +- **Development**: Set both to 1.0 for comprehensive testing +- **Privacy-sensitive**: Keep both low, rely more on error capture +- **Budget-conscious**: Start with errors only (`replaysSessionSampleRate: 0`) + +## Further Reading + +- [Session Replay Setup Guide](/platforms/javascript/session-replay/) +- [Privacy Configuration](/platforms/javascript/session-replay/privacy/) +- [Performance Overhead](/product/explore/session-replay/web/#performance-overhead) \ No newline at end of file From c7161954c91688b74d68cb01ad7712e55a5581fa Mon Sep 17 00:00:00 2001 From: cjy3458 Date: Fri, 9 Jan 2026 18:59:30 +0900 Subject: [PATCH 2/3] docs: remove incorrect claim about connection loss behavior The pause-on-connection-loss feature is specific to mobile SDKs, not web SDKs. Removed to avoid confusion. --- docs/product/explore/session-replay/how-it-works.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/product/explore/session-replay/how-it-works.mdx b/docs/product/explore/session-replay/how-it-works.mdx index 7b079e6900fca..0041aebbb5ea5 100644 --- a/docs/product/explore/session-replay/how-it-works.mdx +++ b/docs/product/explore/session-replay/how-it-works.mdx @@ -144,7 +144,7 @@ The 60-second buffer is managed as a **ring buffer**: - Old events are automatically overwritten - No memory leak concerns - Stops recording after 60 minutes (hard limit) -- Pauses when internet connection is lost +- **Web SDK**: Continues buffering even when offline (data sent when connection restored) ## Best Practices From 28bc903ea3b4395905e924112b22fcc8cacaeca5 Mon Sep 17 00:00:00 2001 From: cjy3458 Date: Fri, 16 Jan 2026 00:18:31 +0900 Subject: [PATCH 3/3] git commit -m "docs(session-replay): Move to Web-specific docs and address review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 (#1, #6) - Change buffer duration to configurable with platform notes (#2) - Replace config examples with PlatformLink references (#3) - Remove hardcoded percentages from decision flow (#4) - Add '(or as configured)' qualifiers (#5) - Remove duplicate 'Recommended Configuration' section (#7) The document now focuses on Web's internal mechanism (rrweb, DOM events, ring buffer) while deferring configuration to official setup docs." --- .../session-replay/understanding-sampling.mdx | 190 ++++++++++++++++++ .../explore/session-replay/how-it-works.mdx | 181 ----------------- 2 files changed, 190 insertions(+), 181 deletions(-) create mode 100644 docs/platforms/javascript/common/session-replay/understanding-sampling.mdx delete mode 100644 docs/product/explore/session-replay/how-it-works.mdx diff --git a/docs/platforms/javascript/common/session-replay/understanding-sampling.mdx b/docs/platforms/javascript/common/session-replay/understanding-sampling.mdx new file mode 100644 index 0000000000000..328ee5dba35a2 --- /dev/null +++ b/docs/platforms/javascript/common/session-replay/understanding-sampling.mdx @@ -0,0 +1,190 @@ +--- +title: "How Session Replay Sampling Works (Web)" +sidebar_order: 15 +description: "Understand the internal mechanism of Web Session Replay sampling and memory buffering" +--- + + + This guide is specific to **Web Session Replay** using rrweb. Mobile platforms + (iOS/Android) use fundamentally different approaches with screenshot-based + capture and on-device video synthesis. For mobile documentation, see [iOS + Session Replay](/platforms/apple/guides/ios/session-replay/) and [Android + Session Replay](/platforms/android/session-replay/). + + +# How Session Replay Sampling Works (Web) + +Understanding how Sentry's Web Session Replay sampling mechanism works internally can help you optimize your configuration and predict what data will be captured. + +## Overview + +Session Replay uses two sampling rates that work together: + +- **`replaysSessionSampleRate`**: Percentage of users who get their entire session recorded +- **`replaysOnErrorSampleRate`**: Percentage of error-encountering users whose sessions get recorded + +The key to understanding how these work together is the **memory buffer**. + +## Memory Buffer System + +### What Gets Stored (Web) + +Web Session Replay doesn't store actual video files in memory. Instead, it stores **event logs** in a structured format using the rrweb library: + +```javascript +// Example event log entries (Web only) +{ time: 1234, type: 'click', x: 100, y: 200 } +{ time: 1235, type: 'input', value: 'cat' } +{ time: 1236, type: 'scroll', x: 0, y: 500 } +``` + +These event logs are: + +- **Lightweight**: Approximately 2-5MB for a typical buffer period +- **Structured**: JSON-like format capturing DOM mutations, user interactions, and console logs +- **Reconstructible**: Sentry's server automatically converts these logs into video-like replays + + + **Mobile platforms work differently:** iOS and Android use screenshot-based + capture with on-device masking and video synthesis, rather than DOM event + logs. + + +### Buffer Duration and Size + +- **Duration**: Configurable buffer period (commonly 60 seconds by default for Web) +- **Memory footprint**: 2-5MB typically +- **Storage location**: In-memory ring buffer (overwrites old data) +- **Network impact**: Only sent to Sentry when conditions are met + + + **Note:** Buffer durations vary by platform. For example, iOS uses a 30-second + buffer by default. + + +## How Sampling Decisions Work + +For detailed configuration options and current recommendations, see Session Replay Setup Guide. + +### Decision Flow + +When a user visits your application: + +1. **Initial Sampling Decision** + - A random number determines if the user is selected for `replaysSessionSampleRate` + - 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 period (or as configured) _before_ the error is captured + - Recording continues until the session ends + - Everything is sent to Sentry + +## User Scenarios + +### 👮 Scenario A: Full Session Recording (No Error) + +**User type**: Selected for `replaysSessionSampleRate` + +``` +1. User visits site +2. Random selection → Selected +3. Recording starts → Sent to Sentry in real-time +4. User browses for 5 minutes +5. Session ends normally +6. ✅ Full 5-minute replay available in Sentry +``` + +**Result**: Complete session visible in Sentry dashboard + +--- + +### 🥷 Scenario B: Not Selected, No Error + +**User type**: Not selected for `replaysSessionSampleRate` + +``` +1. User visits site +2. Random selection → Not selected +3. Recording starts → Stored in memory buffer only +4. User browses normally (no errors) +5. Session ends +6. Memory buffer discarded +7. ❌ No replay in Sentry +``` + +**Result**: No session data sent to Sentry (saves quota) + +--- + +### 👰 Scenario C: Not Selected Initially, But Error Occurs + +**User type**: Not selected initially, but encounters error + +``` +1. User visits site +2. Random selection → Not selected +3. Recording starts → Stored in memory buffer only +4. User browses for 2 minutes +5. 🚨 Error occurs! +6. Check replaysOnErrorSampleRate condition +7. Memory buffer (buffered period) → Sent to Sentry +8. Continue recording until session ends +9. ✅ Replay available showing buffered period before error + everything after +``` + +**Result**: Error replay with valuable context before the error occurred + +--- + +## Key Technical Points + +### Why Event Logs Instead of Video? (Web) + +Web Session Replay uses DOM event logs rather than video recording: + +1. **Privacy**: Text can be masked, images can be blocked +2. **Size**: Event logs are much smaller than video +3. **Flexibility**: Can redact sensitive data before sending +4. **Performance**: Minimal impact on browser performance + +### When Data Is Sent to Sentry + +| Scenario | When Data Leaves Browser | +| ----------------------------- | -------------------------------- | +| Selected for session sampling | Immediately, in real-time chunks | +| Not selected, no error | Never (discarded) | +| Not selected, error occurs | After error + buffer is sent | + +### Memory Management (Web) + +Web Session Replay manages the buffer as a **ring buffer**: + +- Old events are automatically overwritten +- No memory leak concerns +- Stops recording after 60 minutes (hard limit) + + + **Mobile platforms:** Use screenshot-based capture that is masked and combined + into videos on-device, rather than a ring buffer of DOM events. + + +## Configuration Guidance + +For current recommended sampling rates and detailed configuration options, see: + +- Session Replay Setup Guide +- + Privacy Configuration + + +This document focuses on explaining the internal mechanism rather than specific configuration values, which may change over time and vary by use case. + +## Further Reading + +- Session Replay Setup Guide +- + Privacy Configuration + +- [Performance Overhead](/product/explore/session-replay/web/#performance-overhead) diff --git a/docs/product/explore/session-replay/how-it-works.mdx b/docs/product/explore/session-replay/how-it-works.mdx deleted file mode 100644 index 0041aebbb5ea5..0000000000000 --- a/docs/product/explore/session-replay/how-it-works.mdx +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: "How Session Replay Sampling Works" -sidebar_order: 15 -description: "Understand the internal mechanism of Session Replay sampling and memory buffering" ---- - -# How Session Replay Sampling Works - -Understanding how Sentry's Session Replay sampling mechanism works internally can help you optimize your configuration and predict what data will be captured. - -## Overview - -Session Replay uses two sampling rates that work together: - -- **`replaysSessionSampleRate`**: Percentage of users who get their entire session recorded -- **`replaysOnErrorSampleRate`**: Percentage of error-encountering users whose sessions get recorded - -The key to understanding how these work together is the **memory buffer**. - -## Memory Buffer System - -### 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: -```javascript -// Example event log entries -{ time: 1234, type: 'click', x: 100, y: 200 } -{ time: 1235, type: 'input', value: 'cat' } -{ time: 1236, type: 'scroll', x: 0, y: 500 } -``` - -These event logs are: -- **Lightweight**: Approximately 2-5MB for 60 seconds of activity -- **Structured**: JSON-like format capturing DOM mutations, user interactions, and console logs -- **Reconstructible**: Sentry's server automatically converts these logs into video-like replays - -### Buffer Duration and Size - -- **Duration**: 60 seconds of the most recent activity -- **Memory footprint**: 2-5MB typically -- **Storage location**: In-memory ring buffer (overwrites old data) -- **Network impact**: Only sent to Sentry when conditions are met - -## How Sampling Decisions Work - -### Configuration Example -```javascript -Sentry.init({ - dsn: 'YOUR_DSN', - replaysSessionSampleRate: 0.1, // 10% of users - replaysOnErrorSampleRate: 1.0, // 100% of error-encountering users -}); -``` - -### Decision Flow - -When a user visits your application: - -1. **Initial Sampling Decision** - - A random number determines if the user is selected for `replaysSessionSampleRate` - - 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 - -2. **Error Trigger** - - If an error occurs and `replaysOnErrorSampleRate` condition is met: - - The buffered 60 seconds *before* the error is captured - - Recording continues until the session ends - - Everything is sent to Sentry - -## User Scenarios - -### 👮 Scenario A: Full Session Recording (No Error) - -**User type**: Selected for `replaysSessionSampleRate` (10% probability) -``` -1. User visits site -2. Random selection → Selected (10% chance) -3. Recording starts → Sent to Sentry in real-time -4. User browses for 5 minutes -5. Session ends normally -6. ✅ Full 5-minute replay available in Sentry -``` - -**Result**: Complete session visible in Sentry dashboard - ---- - -### 🥷 Scenario B: Not Selected, No Error - -**User type**: Not selected for `replaysSessionSampleRate` (90% probability) -``` -1. User visits site -2. Random selection → Not selected (90% chance) -3. Recording starts → Stored in 60-second memory buffer only -4. User browses normally (no errors) -5. Session ends -6. Memory buffer discarded -7. ❌ No replay in Sentry -``` - -**Result**: No session data sent to Sentry (saves quota) - ---- - -### 👰 Scenario C: Not Selected Initially, But Error Occurs - -**User type**: Not selected initially, but encounters error -``` -1. User visits site -2. Random selection → Not selected (90% chance) -3. Recording starts → Stored in 60-second memory buffer only -4. User browses for 2 minutes -5. 🚨 Error occurs! -6. Check replaysOnErrorSampleRate (1.0 = 100%) -7. Memory buffer (last 60 seconds) → Sent to Sentry -8. Continue recording until session ends -9. ✅ Replay available showing 60s before error + everything after -``` - -**Result**: Error replay with valuable context before the error occurred - ---- - -## Key Technical Points - -### Why Event Logs Instead of Video? - -1. **Privacy**: Text can be masked, images can be blocked -2. **Size**: Event logs are much smaller than video -3. **Flexibility**: Can redact sensitive data before sending -4. **Performance**: Minimal impact on browser performance - -### When Data Is Sent to Sentry - -| Scenario | When Data Leaves Browser | -|----------|-------------------------| -| Selected for session sampling | Immediately, in real-time chunks | -| Not selected, no error | Never (discarded) | -| Not selected, error occurs | After error + buffer is sent | - -### Memory Management - -The 60-second buffer is managed as a **ring buffer**: -- Old events are automatically overwritten -- No memory leak concerns -- Stops recording after 60 minutes (hard limit) -- **Web SDK**: Continues buffering even when offline (data sent when connection restored) - -## Best Practices - -### 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, -}); -``` - -This configuration: -- ✅ Monitors general user behavior (10% sample) -- ✅ Captures critical error scenarios (100% of errors) -- ✅ Manages quota efficiently -- ✅ Provides valuable debugging context - -### Adjusting for Your Needs - -- **High-traffic site**: Lower `replaysSessionSampleRate` to 0.01 (1%) -- **Development**: Set both to 1.0 for comprehensive testing -- **Privacy-sensitive**: Keep both low, rely more on error capture -- **Budget-conscious**: Start with errors only (`replaysSessionSampleRate: 0`) - -## Further Reading - -- [Session Replay Setup Guide](/platforms/javascript/session-replay/) -- [Privacy Configuration](/platforms/javascript/session-replay/privacy/) -- [Performance Overhead](/product/explore/session-replay/web/#performance-overhead) \ No newline at end of file