{"id":15528,"library":"aws-rum-web","title":"AWS CloudWatch Real User Monitoring (RUM) Web Client","description":"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.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/aws-observability/aws-rum-web","tags":["javascript","typescript"],"install":[{"cmd":"npm install aws-rum-web","lang":"bash","label":"npm"},{"cmd":"yarn add aws-rum-web","lang":"bash","label":"yarn"},{"cmd":"pnpm add aws-rum-web","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Main client class for initializing the RUM monitor. ESM import is standard for module usage.","wrong":"const AwsRum = require('aws-rum-web');","symbol":"AwsRum","correct":"import { AwsRum } from 'aws-rum-web';"},{"note":"TypeScript type definition for the RUM client configuration object.","symbol":"AwsRumConfig","correct":"import { AwsRum, AwsRumConfig } from 'aws-rum-web';"},{"note":"Named export for the rrweb plugin, introduced in v2.1.0, for session replay capabilities.","wrong":"import rrwebPlugin from 'aws-rum-web';","symbol":"rrwebPlugin","correct":"import { rrwebPlugin } from 'aws-rum-web';"}],"quickstart":{"code":"import { AwsRum, AwsRumConfig } from 'aws-rum-web';\n\n// Configure your AWS RUM application details. Replace placeholders.\n// Ensure your Identity Pool allows unauthenticated access to the RUM endpoint.\nconst rumConfig: AwsRumConfig = {\n  applicationId: process.env.AWS_RUM_APP_ID ?? 'YOUR_APP_ID',\n  applicationVersion: '1.0.0',\n  id: process.env.AWS_RUM_MONITOR_ID ?? 'YOUR_MONITOR_ID',\n  region: process.env.AWS_RUM_REGION ?? 'us-east-1',\n  sessionSampleRate: 0.1, // Sample 10% of sessions for monitoring\n  guestRoleArn: process.env.AWS_RUM_GUEST_ROLE_ARN ?? 'arn:aws:iam::123456789012:role/RUM_Guest_Role',\n  endpoint: process.env.AWS_RUM_ENDPOINT ?? 'https://dataplane.rum.us-east-1.amazonaws.com',\n  // Optional: add a plugin for session replay\n  // plugins: [rrwebPlugin()],\n  allowCookies: true,\n  enableXRay: true\n};\n\ntry {\n  const rum = new AwsRum(rumConfig);\n  // The RUM client automatically collects performance data, errors, and web vitals.\n  // You can also manually record events or metrics:\n  // rum.recordPageView({ name: '/my-custom-page' });\n  // rum.recordEvent('UserLogin', { success: true, method: 'email' });\n  console.log('AWS RUM client initialized successfully.');\n} catch (error) {\n  console.error('Failed to initialize AWS RUM client:', error);\n}","lang":"typescript","description":"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."},"warnings":[{"fix":"If `VirtualPageLoadTimer` functionality is required, you must explicitly enable it in your `AwsRumConfig` object during client initialization.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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).","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"ReferenceError: AwsRum is not defined"},{"fix":"Populate the `applicationId` field in your `AwsRumConfig` with the correct value from your AWS CloudWatch RUM application monitor setup.","cause":"The `applicationId` property was not provided or was empty in the `AwsRumConfig` object passed to the `AwsRum` constructor.","error":"Failed to initialize AWS RUM client: Missing required configuration parameter: applicationId"},{"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.","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.","error":"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."}],"ecosystem":"npm"}