aws-rum-web

aws-rum-web is the official Amazon CloudWatch RUM (Real User Monitoring) client for web applications. It instruments the browser to capture page load timing, Core Web Vitals (LCP, FID, CLS, INP), JavaScript errors, HTTP requests, session replays, and custom events, then ships the telemetry to Amazon CloudWatch RUM for analysis.

The client installs via npm or an embedded CDN snippet and is configured with an application ID, region, and telemetry options. It handles sampling, cookies, identity via Cognito, and optional AWS X-Ray tracing, giving teams production visibility into real user experience with minimal setup.

What You Get

• Automatic collection of page load timing and Core Web Vitals (LCP, FID, CLS, INP)
• JavaScript error and unhandled rejection capture
• HTTP request telemetry with optional W3C trace and AWS X-Ray integration
• Session replay recording of real user sessions
• Custom event recording plus configurable sampling, cookies, and Cognito identity

Common Use Cases

• Monitoring real user page performance and web vitals in production
• Capturing and triaging client-side JavaScript errors
• Recording session replays to debug user-facing issues
• Correlating front-end HTTP calls with backend traces via X-Ray

Under The Hood

Architecture — The library is organized as a Lerna monorepo (packages/) with the browser client bundling telemetry plugins for performance, errors, http, and session replay behind a single AwsRum entry class. A command queue design lets the CDN snippet buffer calls made before the bundle finishes loading, and a dispatcher batches events to the CloudWatch RUM dataplane endpoint; the app/ directory holds a large matrix of HTML fixtures exercising each telemetry mode.

Tech Stack — Written in TypeScript and bundled with webpack into ESM, CJS, and CDN builds. It vendors its dependencies into the bundle so the published package has no runtime dependencies, easing drop-in browser use.

Code Quality — Testing is thorough: Jest unit tests plus Playwright and Nightwatch integration/smoke suites driven by the fixture pages, with separate tsconfig targets per build. This breadth reflects the reliability expected of a monitoring agent.

API Design — Setup is a single AwsRum constructor taking application ID, version, region, and a typed config object; telemetries are opted in by name. The command-queue snippet keeps the CDN path ergonomic, and initialization is wrapped so failures never break the host page.