AWS CloudWatch Real User Monitoring (RUM) Web Client

Common errors

• ReferenceError: AwsRum is not defined

  cause 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

  cause 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.

  cause 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.

Warnings

• breaking The `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.
• gotcha Incorrect 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`.
• gotcha Browser 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.
• gotcha Ad 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.

Install

• npm install aws-rum-web npm
• yarn add aws-rum-web yarn
• pnpm add aws-rum-web pnpm

Imports

• AwsRum
  wrong:

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

  correct:

  import { AwsRum } from '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
  wrong:

  import rrwebPlugin from 'aws-rum-web';

  correct:

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

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

Quickstart

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);
}