aws-rum-web

v3.2.1

Published

8 days ago

The Amazon CloudWatch RUM web client.

0High
0Medium
0Low

amzn-oss

aws-rum-web-bot

Amazon CloudWatch RUM Web Client

The CloudWatch RUM web client is a JavaScript library that performs real user monitoring (RUM) on web applications. It captures page load timing, web vitals (LCP, FID, CLS, INP), JavaScript errors, HTTP requests, session replays, and custom events, then ships them to Amazon CloudWatch RUM.

Quick start

1. Create an app monitor. Follow Set up an app monitor in the CloudWatch RUM user guide. You will receive an application ID, a region, and (optionally) a Cognito identity pool ID.

2. Install and initialize.

NPM:

npm install aws-rum-web

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

try {
    const config: AwsRumConfig = {
        sessionSampleRate: 1,
        identityPoolId: 'us-west-2:00000000-0000-0000-0000-000000000000',
        endpoint: 'https://dataplane.rum.us-west-2.amazonaws.com',
        telemetries: ['performance', 'errors', 'http'],
        allowCookies: true,
        enableXRay: false
    };

    const APPLICATION_ID = '00000000-0000-0000-0000-000000000000';
    const APPLICATION_VERSION = '1.0.0';
    const APPLICATION_REGION = 'us-west-2';

    const awsRum: AwsRum = new AwsRum(
        APPLICATION_ID,
        APPLICATION_VERSION,
        APPLICATION_REGION,
        config
    );
} catch (error) {
    // Ignore errors thrown during CloudWatch RUM web client initialization
}

CDN (embedded script): paste the snippet from the RUM console into your <head>. The snippet loads the bundle from the AWS-hosted CDN — see Choose a package below for CDN bundle URLs, or CDN installation for the full snippet reference.

3. Verify it works. Open your app, trigger a page view or throw a test error, then open the CloudWatch RUM console. Events appear within ~1 minute. If nothing shows up, enable debug: true in the config and check the browser console — every dispatch is logged.

// Throw a test error to verify errors telemetry
setTimeout(() => {
    throw new Error('rum-verify');
}, 0);

Choose a package

Two distributions, same AwsRum class. Pick full unless bundle size is load-bearing.

| Package | Minified | Gzipped | Included out of the box | | --- | --- | --- | --- | | aws-rum-web (full) | ~162 KB | ~50 KB | Cognito auth, SigV4 signing, default telemetries (errors, performance, http, replay), remote config | | @aws-rum/web-slim | ~32 KB | ~10 KB | Page views and sessions only out of the box. BYO auth via setAwsCredentials, opt-in signing via setSigningConfigFactory, load plugins explicitly via eventPluginsToLoad |

Slim is ~5× smaller. The trade-off is that you wire up auth and plugins yourself — see the slim reference and the full→slim migration guide.

Both distributions are also published to an AWS-hosted CDN. The snippet generated by the RUM console already uses the recommended URL, but you can reference these directly:

| Bundle | Recommended URL (major-pinned) | | --- | --- | | cwr.js (full) | https://client.rum.us-east-1.amazonaws.com/3.x/cwr.js | | cwr-slim.js (slim) | https://client.rum.us-east-1.amazonaws.com/3.x/cwr-slim.js |

CDN version pinning

Every published version is available at three pin levels. Pick the level that matches your update tolerance:

| Pin | Example | Resolves to | | --- | --- | --- | | Major (N.x) | .../3.x/cwr.js | Latest 3.*.* release. Default. Picks up backwards-compatible fixes automatically. | | Minor (N.M.x) | .../3.0.x/cwr.js | Latest 3.0.* patch. Patches only, no new minor-version features. | | Exact (N.M.P) | .../3.0.0/cwr.js | That exact release. Frozen — you bump manually to get fixes. |

The same three levels apply to cwr-slim.js (3.x/cwr-slim.js, 3.0.x/cwr-slim.js, 3.0.0/cwr-slim.js).

:warning: *.x URLs auto-update on every matching release. 3.x and 3.0.x are floating pointers — the moment a new matching version is published, every page that loads that URL serves the new bundle on its next cache-miss. No action, no canary. Regressions reach your users automatically, and two browsers loading your page minutes apart may run different versions. If you need staged rollouts, QA sign-off per version, or byte-for-byte reproducibility, pin to an exact version (3.0.0/cwr.js) and bump it deliberately in your own pipeline. See CDN installation for the full discussion.

Documentation

Start at docs/README.md for the full index. Common entry points:

Getting help

CloudWatch RUM user guide
Amazon CloudWatch forum
AWS Support
File a bug — please search existing issues first and include the web client version and a repro case.

Contributing

PRs welcome. See CONTRIBUTING.

Build from source

Requires Node.js 20+.

npm install
npm run release

Outputs:

CDN bundle: ./build/assets/cwr.js, ./build/assets/cwr.map.js
NPM (ES + CJS): ./dist/es/index.js, ./dist/cjs/index.js and matching .d.ts files

Run tests

npm run test           # Jest unit tests
npm run integ          # Playwright integration tests
npm run smoke:headless # Playwright smoke tests

Dev server (for exploratory testing at http://localhost:9000):

npm run server

Pre-commit

npm run lint:fix
npm run prettier:fix

Security

See CONTRIBUTING.

License

Apache-2.0.