AWS.RUM reference

AppMonitor

Source: src/AWS/RUM/AppMonitor.ts

An Amazon CloudWatch RUM app monitor that collects client-side telemetry (page load times, JavaScript errors, user behavior) from your web application.

AppMonitor: Creating App Monitors

Monitor a single domain

import * as RUM from "alchemy/AWS/RUM";

const monitor = yield* RUM.AppMonitor("SiteMonitor", {
  domain: "example.com",
});

Sample all sessions and collect every telemetry type

const monitor = yield* RUM.AppMonitor("SiteMonitor", {
  domain: "*.example.com",
  appMonitorConfiguration: {
    sessionSampleRate: 1,
    telemetries: ["errors", "performance", "http"],
    allowCookies: true,
  },
});

AppMonitor: Log Retention and Custom Events

const monitor = yield* RUM.AppMonitor("SiteMonitor", {
  domainList: ["example.com", "app.example.com"],
  cwLogEnabled: true,
  customEvents: "ENABLED",
});

GetAppMonitorData

Source: src/AWS/RUM/GetAppMonitorData.ts

Runtime binding for rum:GetAppMonitorData — retrieve the raw performance and error events that CloudWatch RUM collected from the bound AppMonitor for your own processing or analysis; the monitor name is injected automatically.

Provide RUM.GetAppMonitorDataHttp on the hosting Lambda Function to satisfy the requirement.

GetAppMonitorData: Reading RUM Telemetry

// init — grants rum:GetAppMonitorData on the monitor
const getAppMonitorData = yield* AWS.RUM.GetAppMonitorData(monitor);

// runtime — each event is a JSON string
const now = Date.now();
const { Events } = yield* getAppMonitorData({
  TimeRange: { After: now - 3_600_000, Before: now },
});

MetricsDestination

Source: src/AWS/RUM/MetricsDestination.ts

A destination for CloudWatch RUM extended and custom metrics — sends metrics that a RUM app monitor derives from its telemetry events to CloudWatch or to a CloudWatch Evidently experiment, including the metric definitions themselves.

MetricsDestination: Creating a Metrics Destination

const monitor = yield* RUM.AppMonitor("SiteMonitor", {
  domain: "example.com",
});
const metrics = yield* RUM.MetricsDestination("SiteMetrics", {
  appMonitorName: monitor.appMonitorName,
  destination: "CloudWatch",
  // extended metrics require the event pattern matching the metric
  metricDefinitions: [
    {
      name: "SessionCount",
      eventPattern: JSON.stringify({
        event_type: ["com.amazon.rum.session_start_event"],
      }),
    },
  ],
});

MetricsDestination: Custom Metrics

const metrics = yield* RUM.MetricsDestination("CustomMetrics", {
  appMonitorName: monitor.appMonitorName,
  destination: "CloudWatch",
  metricDefinitions: [
    {
      name: "Checkouts",
      namespace: "MyApp",
      unitLabel: "Count",
      eventPattern: JSON.stringify({
        event_type: ["com.example.checkout"],
      }),
    },
  ],
});

PutRumEvents

Source: src/AWS/RUM/PutRumEvents.ts

Runtime binding for rum:PutRumEvents — send a batch of telemetry events from one user session to the bound AppMonitor’s data plane (the same operation the RUM web client uses); the monitor id and details are injected automatically.

Provide RUM.PutRumEventsHttp on the hosting Lambda Function to satisfy the requirement.

PutRumEvents: Sending RUM Events

// init — grants rum:PutRumEvents on the monitor
const putRumEvents = yield* AWS.RUM.PutRumEvents(monitor);

// runtime
yield* putRumEvents({
  BatchId: crypto.randomUUID(),
  UserDetails: { userId, sessionId },
  RumEvents: [
    {
      id: crypto.randomUUID(),
      timestamp: new Date(),
      type: "com.amazon.rum.session_start_event",
      details: "{}",
    },
  ],
});

ResourcePolicy

Source: src/AWS/RUM/ResourcePolicy.ts

The resource-based policy of a CloudWatch RUM app monitor — controls which principals may send events to (rum:PutRumEvents) or read data from the app monitor. An app monitor has at most one.

ResourcePolicy: Creating a Resource Policy

const monitor = yield* RUM.AppMonitor("SiteMonitor", {
  domain: "example.com",
});
const policy = yield* RUM.ResourcePolicy("SitePolicy", {
  appMonitorName: monitor.appMonitorName,
  policyDocument: monitor.appMonitorArn.map((arn) =>
    JSON.stringify({
      Version: "2012-10-17",
      Statement: [
        {
          Effect: "Allow",
          Principal: { AWS: "arn:aws:iam::123456789012:root" },
          Action: ["rum:PutRumEvents"],
          Resource: arn,
        },
      ],
    }),
  ),
});