Session Replay Collection Principles and Data Integrity¶

Session Replay is used to restore user operations on a web page. It is not a screen recording: the browser SDK records a full snapshot of the page and subsequent changes, compresses and uploads the data in segments; during playback, the platform reconstructs the page from this data.

Understanding this helps distinguish three phenomena:

• Not collected: recording has not started, the session is not sampled, or the browser’s capabilities are insufficient.
• Gap in the collection pipeline: page changes exceed the protection budget, network failures are permanent, or the page is closed abruptly.
• Data uploaded but visually incomplete: images, fonts, or styles are not accessible during playback, or content is restricted by privacy rules and capability boundaries.

How Data Is Generated¶

Initialize and start recording
        ↓
Session sampling and recording eligibility check
        ↓
Full snapshot (page baseline)
        ↓
Incremental changes: DOM, input, scroll, mouse, styles, Canvas, etc.
        ↓
Compress and generate ordered segments
        ↓
Normal network send; on page unload, attempt beacon / XHR
        ↓
Platform processes and generates a playable file

1. Initialization and Sampling¶

After SDK init() completes, you must explicitly call:

datafluxRum.startSessionReplayRecording()

Page states and actions that occurred before this call will not be retroactively recorded. Whether recording actually starts also depends on whether the current session falls within sessionReplaySampleRate or sessionReplayOnErrorSampleRate.

Use:

datafluxRum.isRecording()

to confirm whether the current page is in a recording state.

startSessionReplayRecording({ force: true }) can force the current session to be eligible for replay. This option changes the sampling behavior and should only be used in business scenarios where forced recording is explicitly required.

2. Full Snapshot¶

When recording starts, the SDK first generates a playable page baseline, including:

• Current page URL and viewport;
• Focus state;
• DOM structure, attributes, text, and scroll position;
• Visual Viewport information when supported by the browser.

If the page DOM is still changing rapidly during full snapshot generation, the SDK discards the snapshot that mixes different time states and rebuilds it. Very large pages or pages with continuous high-frequency changes may fail multiple times; if recovery fails repeatedly, the SDK stops recording the current page to avoid generating data that cannot be played correctly.

3. Incremental Recording¶

After the full snapshot, the SDK continuously records:

• DOM node additions, deletions, text and attribute changes;
• Mouse, touch, click, and scroll events;
• Input value changes;
• Viewport size changes;
• Playback, pause, and progress states of audio/video elements;
• Style rule changes;
• Canvas recording when enabled.

These increments depend on prior full snapshots. For example, if an increment references a node ID but the corresponding baseline was not successfully uploaded, the playback side cannot correctly apply that change.

4. Segmentation and Upload¶

The SDK compresses the recorded data into ordered segments. During normal recording, segments are typically flushed every ~5 seconds, when the internal size target is approached, when a View switch occurs, or when the page lifecycle changes.

Normal network failures are queued in memory for retry. Offline, HTTP 408, 429, and 5xx responses are retried; most other 4xx responses are non-retryable errors, causing the corresponding segment to be permanently discarded.

If a segment is determined to be undeliverable, the SDK invalidates the entire baseline generation that depends on it and attempts to generate a new full snapshot. After a new snapshot succeeds, subsequent page states can continue to be played, but the operations covered by the permanently lost segment cannot be recovered.

How Error Replay Retains Pre-Error Data¶

When sessionReplayOnErrorSampleRate is configured, matching sessions first save locked replay segments in browser memory. After an error occurs, the SDK unlocks and uploads the most recent page baseline and increments, and continues recording until the session ends.

This provides up to approximately one minute of context before the error, not unlimited history:

• If no error occurs in the session, the locked data is not uploaded.
• If the page closes before the error, the in-memory data does not enter the upload pipeline.
• When the memory cache reaches its protection limit, the SDK rebuilds a playable baseline from a new full snapshot.

Therefore, error replay is suitable for investigating operations before an error, not for replacing normal replay to save all error-free sessions.

When Might DOM Data Be Missing¶

To prevent the browser SDK from occupying the main thread for too long during session replay, protection boundaries are set for serialization and caching. In the current implementation, a full snapshot processes a maximum of 200,000 nodes, with an estimated size of approximately 4 MiB; the DOM tree depth, attribute count per node, text length, style rules, and incremental queue also have boundaries.

The following scenarios may trigger truncation, discarding, or baseline re‑establishment:

• The page creates or replaces a very large DOM subtree in one operation.
• A single text node, attribute, or inline style is exceptionally large.
• High-frequency DOM updates persist too long to obtain a stable snapshot.
• Mutation increment generation rate consistently exceeds the SDK’s processing speed.
• The page simultaneously contains many Shadow Roots, style rules, and large lists.
• The browser itself experiences long blocking when reading the DOM or CSSOM.

The SDK does not send a partial structural change. If an indivisible DOM change is too large, the entire change is discarded and a new full snapshot is requested. This restores a consistent state for subsequent pages, but cannot recover every intermediate step during the gap.

The values above are the current internal protection thresholds of the SDK; they are not configurable and are not stable public APIs. When troubleshooting, always refer to the actual SDK version in use.

Expected Missing Data Due to Privacy Rules¶

The default privacy level is mask-user-input. The following data may be masked, hidden, or replaced with placeholder content:

• Password, email, phone, and hidden input fields.
• Fields related to credit card auto‑fill.
• Nodes marked by privacy attributes or privacy class names.
• Custom nodes that shouldMaskNode returns as requiring masking.
• Script content and subtrees of hidden nodes.

This type of missing content is a data security policy, not packet loss. When investigating “input is empty” or “a region has no content,” first check the privacy configuration.

Capability Boundaries of HTML and Shadow DOM¶

The current collection boundaries are as follows:

Why Canvas and WebGL May Drop Frames¶

Canvas recording is disabled by default. The following conditions must be met:

• Session Replay has hit the sample and is recording.
• replayCanvasEnabled: true.
• The target Canvas is in the collectable DOM.
• WebGL/WebGL2 scenes have additionally registered the WebGL Replay plugin.

Automatic Canvas recording uses a budget‑based scheduler and does not guarantee frame‑by‑frame capture. Visual frame gaps may occur in the following situations:

• Animation speed exceeds the capture rate.
• Page is hidden, auto‑scheduling is paused.
• Multiple Canvases are waiting for fair rotation or concurrent encoding.
• The scene is unchanged and enters a backoff state.
• Canvas size, encoding result, or a single command is too large.
• The Canvas is not yet attached to the DOM, or its DOM baseline has not been published.
• The WebGL plugin is initialized after the engine creates a context and caches drawing methods.
• The last WebGL draw occurs during a cooldown or encoding period, and no new draw triggers capture.

WebGL Replay is a draw‑driven, budget‑limited pixel snapshot, not a WebGL command‑level replay or a frame‑by‑frame video. For detailed configuration and performance boundaries, see How to Enable Canvas Recording.

Why the Tail Is Often Lost When a Page Closes¶

The encoded results and retry queue are stored only in browser memory. When a page is hidden, frozen, or unloaded, the SDK actively flushes pending records and attempts to deliver them via sendBeacon or XHR.

The exit phase still has the following limitations:

• The browser gives JavaScript very limited time.
• The exit phase has a bounded send budget; if too much data is pending, the tail is discarded.
• A successful sendBeacon() return only means the browser accepted the queued task, not that the server has persisted it.
• Force‑killing the browser, browser crash, mobile system process reclamation, power loss, or network disconnection directly clears the memory queue.
• Error replay data that has not been unlocked before the page closes will not be uploaded.

Do not rely entirely on beforeunload for reliable delivery of critical data. Starting recording early and allowing the page to have normal send time after critical operations is more effective than adding off‑page logic.

Data Uploaded, Why Is Playback Still Incomplete¶

Session Replay reconstructs the page based on the DOM and resource URLs; it does not package all images, fonts, and external styles into the replay data. Even if all replay segments are successfully uploaded, the following reasons may still cause display anomalies:

• Images, fonts, or style resources have been taken offline or their URLs have changed.
• Resources require login credentials, signatures, or intranet access.
• CORS does not allow the playback page to load resources.
• CSP blocks Workers, Blob URLs, or resource loading.
• CSSOM of cross‑origin stylesheets is not readable; the original link must be re‑requested during playback.
• Platform‑side data processing, indexing, or replay file generation has not yet completed or has failed.

Resource issues usually manifest as the DOM structure being present, but fonts, images, layout, or hover styles being incorrect.

Data Gap Classification¶

How to Troubleshoot¶

It is recommended to check in the following order:

1. Recording eligibility: Confirm sampling rate, whether startSessionReplayRecording() was called, and check isRecording().
2. Session and View: Execute getInternalContext() to confirm that the Application ID, Session ID, and View ID exist and are as expected.
3. Client requests: In the browser developer tools, filter for /v1/write/rum/replay, and record the request time, status code, response, and failure reason.
4. Worker and security policies: Check the console for Worker, Blob URL, CSP, and Canvas encoding errors.
5. Privacy and capability boundaries: Confirm whether the missing area is subject to masking, closed Shadow DOM, iframe, audio/video, or unopened Canvas.
6. Resource accessibility: From the playback environment, verify the validity, authentication, CORS, and CSP of images, fonts, and CSS URLs.
7. Platform processing status: If client requests succeed but there is still no data, record the Session ID, Application ID, occurrence time, SDK version, and request response for further investigation.

Recommendations for Reducing Data Gaps¶

• Initialize the SDK and start recording as early as possible.
• Set clear normal replay and error replay sampling rates based on business volume.
• Avoid writing extremely large DOM subtrees, text, attributes, and inline styles in one operation.
• Batch update large lists and high‑frequency page states.
• Provide stable URLs for images, fonts, and CSS, and correctly configure CORS and CSP.
• Enable Canvas only on pages that need it, and choose manual, automatic snapshot, or high‑fidelity mode according to the scenario.
• Initialize the WebGL Replay plugin before the WebGL engine starts.
• Monitor /v1/write/rum/replay for 4xx, 429, 5xx, and network failures.
• When troubleshooting, retain the Session ID, View ID, SDK version, browser version, and page lifecycle information.

Further Reading¶

• How to Enable Session Replay
• How to Enable Canvas Recording
• Session Replay Troubleshooting
• Session Replay Data Security