feat: add rrweb plugin by williazz · Pull Request #762 · aws-observability/aws-rum-web

williazz · 2026-02-09T22:09:41Z

Summary

Add RRWebPlugin to main branch in pre-release mode. This does not get bundled into the CDN release, and is not exposed to top level configuration. RUM users may manually import this module if they would like to try it out, but there is no native support at this time.

Implementation

Add RRWebPlugin, which collects RRWeb events in batches and converts them into RUM SessionReplayEvent batches. On visibilitychange event, we will also flush these events before preparing the final batch before exiting the page.

SessionReplayEvents are not compressed separately via the native packer method. Instead, it is recommended to compress at payload level via #759

Schema

{
    "$id": "com.amazon.rum.session_replay_event",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "SessionReplayEvent",
    "type": "object",
    "properties": {
        "version": {
            "const": "1.0.0",
            "type": "string",
            "description": "Schema version."
        },
        "events": {
            "type": "array",
            "description": "Batch of rrweb recording events.",
            "items": {
                "type": "object",
                "properties": {
                    "type": {
                        "type": "number",
                        "description": "rrweb event type."
                    },
                    "timestamp": {
                        "type": "number",
                        "description": "Unix timestamp in milliseconds."
                    },
                    "data": {
                        "description": "rrweb event payload."
                    }
                },
                "required": ["type", "timestamp", "data"]
            }
        },
        "eventCount": {
            "type": "number",
            "description": "Number of events in this batch."
        }
    },
    "additionalProperties": false,
    "required": ["version", "events", "eventCount"]
}

Default settings

Significant cost savings because each SessionReplayEvent can hold up to 50 RRWebEvents by default
Maximum privacy settings enabled by default. All text is blocked by default

export const RRWEB_CONFIG_PROD: RRWebPluginConfig = {
    additionalSampleRate: 1.0,
    batchSize: 50,
    flushInterval: 5000,
    recordOptions: {
        // Performance — keep payload size manageable
        slimDOMOptions: 'all',
        inlineStylesheet: true,
        inlineImages: false,
        collectFonts: true,
        recordCrossOriginIframes: false,
        // Privacy — mask all text and inputs by default
        // NOTE: blockSelector crashes rrweb 2.0.0-alpha.4 (node.matches bug on text nodes)
        maskAllInputs: true,
        maskTextSelector: '*'
    }
};

Future

blockSelector has known issues in rrweb 2.0.0-alpha.4, which may be needed for deeper privacy masking for images and other non-text elements - [Bug]: use blockSelector to mask img record will throw error: e.matches is not a function rrweb-io/rrweb#1486
[Bug]: SendBeacon 65 KB limit #761
We are unlikely to release until [Feature Request]: Slim Build #507 and other backend requirements are resolved
Compression enablement by default is also required for release
Smoke tests to follow

Bundle Size

156 KB parsed

Testing

Added unit and integration tests. See spa-react-demo for manual testing with compression enabled.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

ishajos · 2026-02-10T23:39:14Z

Examples/spa-react-demo/src/rum.ts

        ],
        allowCookies: true,
-        enableXRay: true,
+        enableXRay: false,


why are we disabling this?

just for demo purposes. it was polluting the logs

ishajos · 2026-02-10T23:47:43Z

src/plugins/utils/constant.ts

 export const TIME_TO_INTERACTIVE_EVENT_TYPE = `${RUM_AMZ_PREFIX}.time_to_interactive_event`;
+
+// RRWeb session recording event
+export const RRWEB_EVENT_TYPE = `${RUM_AMZ_PREFIX}.rrweb`;


is it conventional to name this event rrweb as opposed to something like session_replay_event?

i found this to be the best practice in case we want to migrate from rrweb someday

I am a bit confused. The RUM event schema seems to say session_replay_event but we are planning to make the event type com.amazon.rum.rrweb?

should be rrweb. fixed

ps863 · 2026-02-11T01:22:10Z

src/event-schemas/session-replay-event.json

+                        "type": "number",
+                        "description": "rrweb event type."
+                    },
+                    "timestamp": {


question: Would events get recorded into a batch here in chronology? Or would backend need to use the timestamp to figure out the ordering

it's insertion order, which should also be chronological. backend will use rum event timestamp for pagination

ps863 · 2026-02-11T01:25:35Z

src/plugins/event-plugins/RRWebPlugin.ts

+
+/** Configuration options for {@link RRWebPlugin}. */
+export type RRWebPluginConfig = {
+    /** Probability (0–1) of recording replay for a session, applied on top of sessionSampleRate. */


nit: Add docs how this + sessionSample would work together

updated the jsdoc. i'm not updating public docs at this time because this is still in pre-release state.

ps863 · 2026-02-11T01:28:25Z

src/plugins/event-plugins/RRWebPlugin.ts

+};
+
+/** Development defaults — privacy masking disabled for easier debugging. */
+export const RRWEB_CONFIG_DEV: RRWebPluginConfig = {


comment: I think we should be careful about enabling privacy masking even in the dev config.
Users should have to explicitly enable that and we should not hide it under dev. Additionally storage concerns that exist in prod might be applicable here as well

this is disabling privacy masking, not enabling. but sure i can just remove dev config

ps863 · 2026-02-11T01:35:00Z

src/plugins/utils/constant.ts

 export const TIME_TO_INTERACTIVE_EVENT_TYPE = `${RUM_AMZ_PREFIX}.time_to_interactive_event`;
+
+// RRWeb session recording event
+export const RRWEB_EVENT_TYPE = `${RUM_AMZ_PREFIX}.rrweb`;


I am a bit confused. The RUM event schema seems to say session_replay_event but we are planning to make the event type com.amazon.rum.rrweb?

williazz added 2 commits February 9, 2026 13:17

feat: add rrweb plugin

23a1849

feat: add flush hook

d12c6b5

williazz changed the title ~~feat: add rrweb plugin to library~~ feat: add rrweb plugin Feb 9, 2026

williazz requested review from ishajos and ps863 February 9, 2026 22:13

doc: session replay design doc

faf2210

ishajos approved these changes Feb 10, 2026

View reviewed changes

ps863 reviewed Feb 11, 2026

View reviewed changes

rev2

8c4ade8

ps863 approved these changes Feb 12, 2026

View reviewed changes

williazz merged commit 7af852d into aws-observability:main Feb 12, 2026
10 of 11 checks passed

Conversation

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

Uh oh!

Summary

Implementation

Schema

Default settings

Future

Bundle Size

Testing

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!

williazz Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

williazz commented Feb 9, 2026 •

edited

Loading

williazz Feb 12, 2026 •

edited

Loading