Registry / aws / aws-rum-web

aws-rum-web

library2.1.0jsnpmunverified

The `aws-rum-web` client is a JavaScript library designed for real user monitoring (RUM) of web applications, integrating seamlessly with Amazon CloudWatch. It provides telemetry on critical user experience metrics such as page load timings, JavaScript errors, and HTTP request performance. The current stable version is 2.1.0, and the package maintains a relatively active release cadence with frequent minor and patch updates. Key differentiators include its tight integration into the AWS observability ecosystem, enabling developers to gain deeper insights into their web application's frontend performance and user behavior directly within CloudWatch, and its comprehensive data collection capabilities for various web vitals and errors.

aws observability

npm install aws-rum-web

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AWS-RUM-WEB

aws-rum-web

awsjavascriptv2.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AwsRum

✓ import { AwsRum } from 'aws-rum-web';

✗ const AwsRum = require('aws-rum-web');

Main client class for initializing the RUM monitor. ESM import is standard for module usage.

AwsRumConfig

✓ import { AwsRum, AwsRumConfig } from 'aws-rum-web';

TypeScript type definition for the RUM client configuration object.

rrwebPlugin

✓ import { rrwebPlugin } from 'aws-rum-web';

✗ import rrwebPlugin from 'aws-rum-web';

Named export for the rrweb plugin, introduced in v2.1.0, for session replay capabilities.

Initializes the AWS CloudWatch RUM web client with a basic configuration to start collecting data. This example demonstrates how to instantiate the `AwsRum` class, providing essential parameters like application ID, version, and region, and handles potential initialization errors.

import { AwsRum, AwsRumConfig } from 'aws-rum-web'; // Configure your AWS RUM application details. Replace placeholders. // Ensure your Identity Pool allows unauthenticated access to the RUM endpoint. const rumConfig: AwsRumConfig = { applicationId: process.env.AWS_RUM_APP_ID ?? 'YOUR_APP_ID', applicationVersion: '1.0.0', id: process.env.AWS_RUM_MONITOR_ID ?? 'YOUR_MONITOR_ID', region: process.env.AWS_RUM_REGION ?? 'us-east-1', sessionSampleRate: 0.1, // Sample 10% of sessions for monitoring guestRoleArn: process.env.AWS_RUM_GUEST_ROLE_ARN ?? 'arn:aws:iam::123456789012:role/RUM_Guest_Role', endpoint: process.env.AWS_RUM_ENDPOINT ?? 'https://dataplane.rum.us-east-1.amazonaws.com', // Optional: add a plugin for session replay // plugins: [rrwebPlugin()], allowCookies: true, enableXRay: true }; try { const rum = new AwsRum(rumConfig); // The RUM client automatically collects performance data, errors, and web vitals. // You can also manually record events or metrics: // rum.recordPageView({ name: '/my-custom-page' }); // rum.recordEvent('UserLogin', { success: true, method: 'email' }); console.log('AWS RUM client initialized successfully.'); } catch (error) { console.error('Failed to initialize AWS RUM client:', error); }

Debug

Known issues

breakingThe `VirtualPageLoadTimer` is now disabled by default. This may affect how page load metrics are collected and reported if your application relied on its previous default enabled state.

fix

If `VirtualPageLoadTimer` functionality is required, you must explicitly enable it in your `AwsRumConfig` object during client initialization.

affects: >=2.0.0

gotchaIncorrect or incomplete `AwsRumConfig` parameters (e.g., `applicationId`, `id`, `region`, `guestRoleArn`, `endpoint`) will prevent the RUM client from sending data to CloudWatch, potentially failing silently or with console errors.

fix

Thoroughly review the RUM configuration documentation. Ensure all required parameters are correctly provided and correspond to your AWS RUM app monitor setup. Verify the IAM role has permissions to `rum:PutRumEvents`.

affects: >=1.0.0

gotchaBrowser Content Security Policy (CSP) rules can block the RUM client from sending data to the CloudWatch RUM data plane or from loading necessary external resources (e.g., for plugins like rrweb).

fix

Update your web application's CSP to allow connections to the RUM endpoint (`connect-src`) and potentially include `script-src` and `frame-src` directives if using plugins that load external scripts or iframes.

affects: >=1.0.0

gotchaAd blockers or browser extensions can interfere with the RUM client's ability to collect and send data, leading to incomplete or missing telemetry in CloudWatch.

fix

While this issue is client-side and largely out of application control, it's important to be aware that your collected data might not represent 100% of user interactions due to these external factors. Consider informing users or testing in various browser environments.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: AwsRum is not defined

The `AwsRum` class was not imported or the script loading the RUM client failed in a module environment, or `AWSRUM` global object is accessed prematurely in a CDN setup.

fix

For module usage, ensure `import { AwsRum } from 'aws-rum-web';` is at the top of your file. For CDN, verify the RUM script is loaded before `AWSRUM` is referenced.

Failed to initialize AWS RUM client: Missing required configuration parameter: applicationId

The `applicationId` property was not provided or was empty in the `AwsRumConfig` object passed to the `AwsRum` constructor.

fix

Populate the `applicationId` field in your `AwsRumConfig` with the correct value from your AWS CloudWatch RUM application monitor setup.

Access to XMLHttpRequest at 'https://dataplane.rum.us-east-1.amazonaws.com/...' from origin 'http://localhost:3000' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

The browser is preventing the RUM client from sending data to the RUM endpoint due to a Cross-Origin Resource Sharing (CORS) policy violation. This usually indicates a misconfiguration in the AWS RUM application monitor's domain allow-list.

fix

In your AWS RUM application monitor configuration, ensure that your application's domain (e.g., `http://localhost:3000` for development, or your production domain) is correctly added to the 'Allow additional domains' setting.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/aws-observability/aws-rum-web ↗

packagehttps://www.npmjs.com/package/aws-rum-web ↗

homepagehttps://aws.amazon.com/cloudwatch/ ↗