sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ RUM/ MetricsDestination.ts

import * as rum from "@distilled.cloud/aws/rum";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";

/**
 * One extended or custom metric a RUM app monitor derives from its telemetry
 * events and sends to the destination.
 */
export interface MetricDefinition {
  /**
   * Name of the metric. For extended metrics this must be one of the valid
   * extended metric names (e.g. `SessionCount`, `JsErrorCount`); for custom
   * metrics (CloudWatch destinations with a `namespace`) any name is
   * allowed.
   */
  name: string;
  /**
   * Field within the event to use as the metric value. Omit to count
   * matching events (value 1 per event).
   */
  valueKey?: string;
  /**
   * CloudWatch metric unit label (e.g. `Count`, `Milliseconds`).
   */
  unitLabel?: string;
  /**
   * Extra dimensions derived from event fields — maps the event field path
   * (e.g. `metadata.browserName`) to the dimension name (e.g.
   * `BrowserName`).
   */
  dimensionKeys?: Record<string, string>;
  /**
   * JSON event-pattern filter — only events matching the pattern contribute
   * to the metric. Required for extended metrics, where it must match the
   * metric's event type (e.g.
   * `{"event_type":["com.amazon.rum.session_start_event"]}` for
   * `SessionCount`).
   */
  eventPattern?: string;
  /**
   * Custom-metric namespace (CloudWatch destinations only). RUM prepends
   * `RUM/CustomMetrics/`; it must not start with `AWS/`. Omit for extended
   * metrics.
   */
  namespace?: string;
}

export interface MetricsDestinationProps {
  /**
   * Name of the CloudWatch RUM app monitor that sends metrics to this
   * destination. Changing it replaces the destination.
   */
  appMonitorName: string;
  /**
   * Where the extended/custom metrics are sent. Changing it replaces the
   * destination.
   */
  destination: "CloudWatch" | "Evidently";
  /**
   * ARN of the CloudWatch Evidently experiment receiving the metrics.
   * Required when `destination` is `"Evidently"`; changing it replaces the
   * destination.
   */
  destinationArn?: string;
  /**
   * ARN of the IAM role RUM assumes to write to the Evidently experiment.
   * Required when `destination` is `"Evidently"`.
   */
  iamRoleArn?: string;
  /**
   * The extended/custom metric definitions the app monitor sends to this
   * destination. Synced in place: added, updated, and removed definitions
   * converge to this list.
   */
  metricDefinitions?: MetricDefinition[];
}

export interface MetricsDestination extends Resource<
  "AWS.RUM.MetricsDestination",
  MetricsDestinationProps,
  {
    /**
     * Name of the app monitor sending metrics.
     */
    appMonitorName: string;
    /**
     * The destination kind (`CloudWatch` or `Evidently`).
     */
    destination: "CloudWatch" | "Evidently";
    /**
     * ARN of the Evidently experiment, when `destination` is `Evidently`.
     */
    destinationArn: string | undefined;
    /**
     * IAM role RUM assumes to write to the destination, when set.
     */
    iamRoleArn: string | undefined;
  },
  never,
  Providers
> {}

/**
 * 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.
 *
 * ### Creating a Metrics Destination
 * **Example:** Send Extended Metrics to CloudWatch
 * ```typescript
 * 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"],
 *       }),
 *     },
 *   ],
 * });
 * ```
 *
 * ### Custom Metrics
 * **Example:** Derive a Custom Metric from Events
 * ```typescript
 * 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"],
 *       }),
 *     },
 *   ],
 * });
 * ```
 *
 * @resource
 */
export const MetricsDestination = Resource<MetricsDestination>("AWS.RUM.MetricsDestination");

/**
 * Raised when a `BatchCreateRumMetricDefinitions` /
 * `BatchDeleteRumMetricDefinitions` call reports per-definition errors.
 */
export class RumMetricDefinitionsError extends Data.TaggedError("RumMetricDefinitionsError")<{
  message: string;
}> {}

const toWireDefinition = (def: MetricDefinition): rum.MetricDefinitionRequest => ({
  Name: def.name,
  ValueKey: def.valueKey,
  UnitLabel: def.unitLabel,
  DimensionKeys: def.dimensionKeys,
  EventPattern: def.eventPattern,
  Namespace: def.namespace,
});

const sameRecord = (
  a: Record<string, string | undefined> | undefined,
  b: Record<string, string | undefined> | undefined,
) => {
  const left = Object.entries(a ?? {}).filter(([, v]) => v !== undefined);
  const right = Object.entries(b ?? {}).filter(([, v]) => v !== undefined);
  return left.length === right.length && left.every(([k, v]) => (b ?? {})[k] === v);
};

const definitionInSync = (observed: rum.MetricDefinition, desired: MetricDefinition) =>
  observed.ValueKey === desired.valueKey &&
  observed.UnitLabel === desired.unitLabel &&
  observed.EventPattern === desired.eventPattern &&
  observed.Namespace === desired.namespace &&
  sameRecord(observed.DimensionKeys, desired.dimensionKeys);

export const MetricsDestinationProvider = () =>
  Provider.effect(
    MetricsDestination,
    Effect.gen(function* () {
      /**
       * Observe the live destination on the monitor; typed not-found (the
       * monitor itself is gone) → undefined.
       */
      const observeDestination = Effect.fn(function* (
        props: Pick<MetricsDestinationProps, "appMonitorName" | "destination" | "destinationArn">,
      ) {
        const destinations = yield* rum.listRumMetricsDestinations
          .items({ AppMonitorName: props.appMonitorName })
          .pipe(
            Stream.runCollect,
            Effect.catchTag("ResourceNotFoundException", () =>
              Effect.succeed([] as rum.MetricDestinationSummary[]),
            ),
          );
        return Array.from(destinations).find(
          (d) =>
            d.Destination === props.destination &&
            (props.destination !== "Evidently" || d.DestinationArn === props.destinationArn),
        );
      });

      const toAttrs = (
        props: MetricsDestinationProps,
        observed: rum.MetricDestinationSummary | undefined,
      ) => ({
        appMonitorName: props.appMonitorName,
        destination: props.destination,
        destinationArn: props.destinationArn,
        iamRoleArn: observed?.IamRoleArn ?? props.iamRoleArn,
      });

      return {
        stables: ["appMonitorName", "destination", "destinationArn"],

        diff: Effect.fn(function* ({ olds, news }) {
          if (!isResolved(news)) return undefined;
          if (
            olds?.appMonitorName !== news.appMonitorName ||
            olds?.destination !== news.destination ||
            olds?.destinationArn !== news.destinationArn
          ) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ olds, output }) {
          const identity = output ?? olds;
          if (!identity) return undefined;
          const observed = yield* observeDestination(identity);
          if (observed === undefined) return undefined;
          // Metrics destinations are not taggable — ownership is implied by
          // the owned parent app monitor.
          return {
            appMonitorName: identity.appMonitorName,
            destination: identity.destination,
            destinationArn: identity.destinationArn,
            iamRoleArn: observed.IamRoleArn,
          };
        }),

        reconcile: Effect.fn(function* ({ news, session }) {
          const props = news!;
          const key = {
            AppMonitorName: props.appMonitorName,
            Destination: props.destination,
            ...(props.destination === "Evidently" ? { DestinationArn: props.destinationArn } : {}),
          };

          // 1. OBSERVE — the live destination list is authoritative.
          const observed = yield* observeDestination(props);

          // 2. ENSURE + SYNC destination — `putRumMetricsDestination` is a
          //    true upsert; call it when missing or when the role drifts. A
          //    concurrent put surfaces as the typed ConflictException — a
          //    race, not a failure.
          if (
            observed === undefined ||
            (props.iamRoleArn !== undefined && observed.IamRoleArn !== props.iamRoleArn)
          ) {
            yield* rum
              .putRumMetricsDestination({
                ...key,
                IamRoleArn: props.iamRoleArn,
              })
              .pipe(
                Effect.asVoid,
                Effect.catchTag("ConflictException", () => Effect.void),
              );
          }

          // 3. SYNC metric definitions — diff the OBSERVED definitions
          //    (keyed by name) against the desired list and apply only the
          //    delta: batch-create missing, update drifted, batch-delete
          //    extraneous.
          const live = yield* rum.batchGetRumMetricDefinitions.items(key).pipe(
            Stream.runCollect,
            Effect.map((c) => Array.from(c)),
          );
          const desired = props.metricDefinitions ?? [];
          const liveByName = new Map(live.map((d) => [d.Name, d]));
          const desiredNames = new Set(desired.map((d) => d.name));

          const toCreate = desired.filter((d) => !liveByName.has(d.name));
          if (toCreate.length > 0) {
            const { Errors } = yield* rum.batchCreateRumMetricDefinitions({
              ...key,
              MetricDefinitions: toCreate.map(toWireDefinition),
            });
            if (Errors.length > 0) {
              return yield* new RumMetricDefinitionsError({
                message: `failed to create ${Errors.length} metric definition(s): ${Errors.map(
                  (e) => `${e.MetricDefinition.Name}: ${e.ErrorMessage}`,
                ).join("; ")}`,
              });
            }
          }

          yield* Effect.forEach(
            desired.flatMap((d) => {
              const current = liveByName.get(d.name);
              return current !== undefined && !definitionInSync(current, d)
                ? [{ id: current.MetricDefinitionId, definition: d }]
                : [];
            }),
            ({ id, definition }) =>
              rum.updateRumMetricDefinition({
                ...key,
                MetricDefinitionId: id,
                MetricDefinition: toWireDefinition(definition),
              }),
          );

          const toDelete = live.filter((d) => !desiredNames.has(d.Name));
          if (toDelete.length > 0) {
            const { Errors } = yield* rum.batchDeleteRumMetricDefinitions({
              ...key,
              MetricDefinitionIds: toDelete.map((d) => d.MetricDefinitionId),
            });
            if (Errors.length > 0) {
              return yield* new RumMetricDefinitionsError({
                message: `failed to delete ${Errors.length} metric definition(s): ${Errors.map(
                  (e) => `${e.MetricDefinitionId}: ${e.ErrorMessage}`,
                ).join("; ")}`,
              });
            }
          }

          yield* session.note(`${props.appMonitorName}/${props.destination}`);
          const final = yield* observeDestination(props);
          return toAttrs(props, final);
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* rum
            .deleteRumMetricsDestination({
              AppMonitorName: output.appMonitorName,
              Destination: output.destination,
              ...(output.destination === "Evidently"
                ? { DestinationArn: output.destinationArn }
                : {}),
            })
            .pipe(
              // idempotent — the destination (or its whole monitor) may be gone
              Effect.catchTag("ResourceNotFoundException", () => Effect.void),
              Effect.retry({
                while: (e) => e._tag === "ConflictException",
                schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(8)]),
              }),
            );
        }),

        // Sub-resource keyed by its parent app monitor — enumerating it
        // would require listing every monitor's destinations.
        list: () => Effect.succeed([]),
      };
    }),
  );