AWS.CloudWatch reference

Alarm

Source: src/AWS/CloudWatch/Alarm.ts

A CloudWatch metric alarm — watches a single metric (or metric-math expression) and transitions between OK, ALARM, and INSUFFICIENT_DATA, optionally firing actions on state change.

Alarm: Creating Alarms

Threshold Alarm

const alarm = yield* Alarm("HighErrors", {
  MetricName: "Errors",
  Namespace: "AWS/Lambda",
  Statistic: "Sum",
  Period: 60,
  EvaluationPeriods: 1,
  Threshold: 1,
  ComparisonOperator: "GreaterThanOrEqualToThreshold",
});

Alarm on a Lambda Function’s Errors

const fn = yield* MyFunction;

const alarm = yield* Alarm("FnErrors", {
  MetricName: "Errors",
  Namespace: "AWS/Lambda",
  Dimensions: [{ Name: "FunctionName", Value: fn.functionName }],
  Statistic: "Sum",
  Period: 60,
  EvaluationPeriods: 1,
  Threshold: 1,
  ComparisonOperator: "GreaterThanOrEqualToThreshold",
  TreatMissingData: "notBreaching",
});

Alarm: Reading Alarm State at Runtime

// init — bind the alarm to the function (see DescribeAlarms)
const describeAlarms = yield* AWS.CloudWatch.DescribeAlarms(alarm);

// runtime
const result = yield* describeAlarms();
const state = result.MetricAlarms?.[0]?.StateValue;

AlarmMuteRule

Source: src/AWS/CloudWatch/AlarmMuteRule.ts

A CloudWatch alarm mute rule — suppresses alarm actions on a recurring schedule (e.g. maintenance windows) instead of manually disabling and re-enabling alarm actions.

AlarmMuteRule: Creating Mute Rules

const rule = yield* AlarmMuteRule("NightlyMute", {
  Rule: {
    Schedule: {
      Expression: "0 2 * * SUN",
      Duration: "PT1H",
    },
  },
});

AlarmMuteRule: Reading Mute Rules at Runtime

// init — bind the rule to the function (see GetAlarmMuteRule)
const getAlarmMuteRule = yield* AWS.CloudWatch.GetAlarmMuteRule(rule);

// runtime
const result = yield* getAlarmMuteRule();
const schedule = result.Rule?.Schedule;

AnomalyDetector

Source: src/AWS/CloudWatch/AnomalyDetector.ts

A CloudWatch anomaly detector — trains a model on a metric’s historical data and computes an expected-value band, which alarms can use via the ANOMALY_DETECTION_BAND metric-math function.

AnomalyDetector: Creating Detectors

Single Metric Detector

const detector = yield* AnomalyDetector("ErrorsDetector", {
  Namespace: "AWS/Lambda",
  MetricName: "Errors",
  Stat: "Sum",
});

Detector on a Custom Metric

// pair with PutMetricData publishing to the same namespace/metric
const detector = yield* AnomalyDetector("PaymentsDetector", {
  Namespace: "MyApp/Payments",
  MetricName: "PaymentProcessed",
  Stat: "Sum",
});

AnomalyDetector: Reading Detectors at Runtime

// init — see DescribeAnomalyDetectors
const describeAnomalyDetectors = yield* AWS.CloudWatch.DescribeAnomalyDetectors();

// runtime
const result = yield* describeAnomalyDetectors({ Namespace: "MyApp/Payments" });

CompositeAlarm

Source: src/AWS/CloudWatch/CompositeAlarm.ts

A CloudWatch composite alarm — combines the states of other alarms with a boolean AlarmRule expression so a single alarm (and its actions) reflects overall health.

CompositeAlarm: Creating Composite Alarms

Composite Rule

const composite = yield* CompositeAlarm("HighSeverity", {
  AlarmRule: 'ALARM("HighErrors") OR ALARM("HighLatency")',
});

Compose Alarm Resources with Output.interpolate

const errors = yield* Alarm("HighErrors", {
  MetricName: "Errors",
  Namespace: "AWS/Lambda",
  Statistic: "Sum",
  Period: 60,
  EvaluationPeriods: 1,
  Threshold: 1,
  ComparisonOperator: "GreaterThanOrEqualToThreshold",
});

const composite = yield* CompositeAlarm("HighSeverity", {
  AlarmRule: Output.interpolate`ALARM("${errors.alarmName}")`,
});

Dashboard

Source: src/AWS/CloudWatch/Dashboard.ts

An Amazon CloudWatch dashboard. The DashboardBody is a structured, typed document (metric, text, alarm-status, and log widgets) that the provider serializes to the JSON string CloudWatch expects.

Dashboard: Creating Dashboards

Basic Dashboard

const dashboard = yield* Dashboard("OpsDashboard", {
  DashboardBody: {
    widgets: [],
  },
});

Dashboard with Metric and Text Widgets

const dashboard = yield* Dashboard("PaymentsDashboard", {
  DashboardBody: {
    widgets: [
      {
        type: "text",
        x: 0, y: 0, width: 6, height: 3,
        properties: { markdown: "# Payments service" },
      },
      {
        type: "metric",
        x: 0, y: 3, width: 12, height: 6,
        properties: {
          title: "Payments processed",
          metrics: [["MyApp/Payments", "PaymentProcessed"]],
          stat: "Sum",
          period: 60,
          view: "timeSeries",
        },
      },
    ],
  },
});

Dashboard: Reading Dashboards at Runtime

// init — bind the dashboard to the function (see GetDashboard)
const getDashboard = yield* AWS.CloudWatch.GetDashboard(dashboard);

// runtime
const result = yield* getDashboard();
const body = JSON.parse(result.DashboardBody ?? "{}");

DescribeAlarmContributors

Source: src/AWS/CloudWatch/DescribeAlarmContributors.ts

Runtime binding for cloudwatch:DescribeAlarmContributors — list the time-series contributors currently in ALARM for a contributor-enabled metric-math alarm. Bind it to the Alarm; the alarm name is injected automatically.

Provide CloudWatch.DescribeAlarmContributorsHttp on the hosting Lambda Function to satisfy the requirement.

DescribeAlarmContributors: Reading Alarm State

// init — grants cloudwatch:DescribeAlarmContributors on the alarm
const describeAlarmContributors =
  yield* AWS.CloudWatch.DescribeAlarmContributors(alarm);

// runtime — plain metric alarms have no contributor data; the typed
// errors let you treat that as an empty result
const contributors = yield* describeAlarmContributors().pipe(
  Effect.map((r) => r.AlarmContributors ?? []),
  Effect.catchTag(
    ["ResourceNotFoundException", "ValidationException"],
    () => Effect.succeed([]),
  ),
);

DescribeAlarmHistory

Source: src/AWS/CloudWatch/DescribeAlarmHistory.ts

Runtime binding for cloudwatch:DescribeAlarmHistory — read state transitions and configuration changes recorded for alarms in the account/region.

Provide CloudWatch.DescribeAlarmHistoryHttp on the hosting Lambda Function to satisfy the requirement.

DescribeAlarmHistory: Reading Alarm State

// init — grants cloudwatch:DescribeAlarmHistory
const describeAlarmHistory = yield* AWS.CloudWatch.DescribeAlarmHistory();

// runtime
const result = yield* describeAlarmHistory({
  AlarmName: yield* alarm.alarmName,
  MaxRecords: 10,
});
const items = result.AlarmHistoryItems ?? [];

DescribeAlarms

Source: src/AWS/CloudWatch/DescribeAlarms.ts

Runtime binding for cloudwatch:DescribeAlarms — read the current state and configuration of the bound alarms. Bind it to one or more Alarm / CompositeAlarm resources; the alarm names are injected automatically.

Provide CloudWatch.DescribeAlarmsHttp on the hosting Lambda Function to satisfy the requirement.

DescribeAlarms: Reading Alarm State

const alarm = yield* CloudWatch.Alarm("HighErrors", {
  MetricName: "Errors",
  Namespace: "AWS/Lambda",
  Statistic: "Sum",
  Period: 60,
  EvaluationPeriods: 1,
  Threshold: 1,
  ComparisonOperator: "GreaterThanOrEqualToThreshold",
});

// init — grants cloudwatch:DescribeAlarms on the alarm
const describeAlarms = yield* AWS.CloudWatch.DescribeAlarms(alarm);

// runtime
const result = yield* describeAlarms();
const state = result.MetricAlarms?.[0]?.StateValue; // "OK" | "ALARM" | ...

DescribeAlarmsForMetric

Source: src/AWS/CloudWatch/DescribeAlarmsForMetric.ts

Runtime binding for cloudwatch:DescribeAlarmsForMetric — find the alarms watching a specific metric.

Provide CloudWatch.DescribeAlarmsForMetricHttp on the hosting Lambda Function to satisfy the requirement.

DescribeAlarmsForMetric: Reading Alarm State

// init — grants cloudwatch:DescribeAlarmsForMetric
const describeAlarmsForMetric = yield* AWS.CloudWatch.DescribeAlarmsForMetric();

// runtime
const result = yield* describeAlarmsForMetric({
  Namespace: "MyApp/Payments",
  MetricName: "PaymentProcessed",
  Statistic: "Sum",
  Period: 60,
});
const alarmNames = (result.MetricAlarms ?? []).map((a) => a.AlarmName);

DescribeAnomalyDetectors

Source: src/AWS/CloudWatch/DescribeAnomalyDetectors.ts

Runtime binding for cloudwatch:DescribeAnomalyDetectors — list the anomaly detection models in the account/region, optionally filtered by namespace, metric name, or dimensions.

Provide CloudWatch.DescribeAnomalyDetectorsHttp on the hosting Lambda Function to satisfy the requirement.

DescribeAnomalyDetectors: Reading Anomaly Detectors

// init — grants cloudwatch:DescribeAnomalyDetectors
const describeAnomalyDetectors = yield* AWS.CloudWatch.DescribeAnomalyDetectors();

// runtime
const result = yield* describeAnomalyDetectors({
  Namespace: "MyApp/Payments",
});
const detectors = result.AnomalyDetectors ?? [];

DescribeInsightRules

Source: src/AWS/CloudWatch/DescribeInsightRules.ts

Runtime binding for cloudwatch:DescribeInsightRules — list the Contributor Insights rules in the account/region.

Provide CloudWatch.DescribeInsightRulesHttp on the hosting Lambda Function to satisfy the requirement.

DescribeInsightRules: Reading Insight Rules

// init — grants cloudwatch:DescribeInsightRules
const describeInsightRules = yield* AWS.CloudWatch.DescribeInsightRules();

// runtime
const result = yield* describeInsightRules();
const names = (result.InsightRules ?? []).map((rule) => rule.Name);

DisableAlarmActions

Source: src/AWS/CloudWatch/DisableAlarmActions.ts

Runtime binding for cloudwatch:DisableAlarmActions — suppress the actions of the bound alarms (e.g. during a deploy or maintenance window). Bind it to one or more Alarm / CompositeAlarm resources; the alarm names are injected automatically. Re-enable with EnableAlarmActions.

Provide CloudWatch.DisableAlarmActionsHttp on the hosting Lambda Function to satisfy the requirement.

DisableAlarmActions: Managing Alarm Actions

// init — grants cloudwatch:DisableAlarmActions on the alarm
const disableAlarmActions = yield* AWS.CloudWatch.DisableAlarmActions(alarm);

// runtime
yield* disableAlarmActions();

DisableInsightRules

Source: src/AWS/CloudWatch/DisableInsightRules.ts

Runtime binding for cloudwatch:DisableInsightRules — pause data collection for the bound Contributor Insights rules. Bind it to one or more InsightRule resources; the rule names are injected automatically.

Provide CloudWatch.DisableInsightRulesHttp on the hosting Lambda Function to satisfy the requirement.

DisableInsightRules: Managing Insight Rules

// init — grants cloudwatch:DisableInsightRules on the rule
const disableInsightRules = yield* AWS.CloudWatch.DisableInsightRules(rule);

// runtime
const result = yield* disableInsightRules();
const failures = result.Failures ?? []; // empty on success

EnableAlarmActions

Source: src/AWS/CloudWatch/EnableAlarmActions.ts

Runtime binding for cloudwatch:EnableAlarmActions — re-enable the actions of the bound alarms after they were suppressed with DisableAlarmActions. Bind it to one or more Alarm / CompositeAlarm resources; the alarm names are injected automatically.

Provide CloudWatch.EnableAlarmActionsHttp on the hosting Lambda Function to satisfy the requirement.

EnableAlarmActions: Managing Alarm Actions

// init — grants cloudwatch:EnableAlarmActions on the alarm
const enableAlarmActions = yield* AWS.CloudWatch.EnableAlarmActions(alarm);

// runtime
yield* enableAlarmActions();

EnableInsightRules

Source: src/AWS/CloudWatch/EnableInsightRules.ts

Runtime binding for cloudwatch:EnableInsightRules — resume data collection for the bound Contributor Insights rules after they were paused with DisableInsightRules. Bind it to one or more InsightRule resources; the rule names are injected automatically.

Provide CloudWatch.EnableInsightRulesHttp on the hosting Lambda Function to satisfy the requirement.

EnableInsightRules: Managing Insight Rules

// init — grants cloudwatch:EnableInsightRules on the rule
const enableInsightRules = yield* AWS.CloudWatch.EnableInsightRules(rule);

// runtime
const result = yield* enableInsightRules();
const failures = result.Failures ?? []; // empty on success

GetAlarmMuteRule

Source: src/AWS/CloudWatch/GetAlarmMuteRule.ts

Runtime binding for cloudwatch:GetAlarmMuteRule — read the configuration of the bound AlarmMuteRule; the rule name is injected automatically.

Provide CloudWatch.GetAlarmMuteRuleHttp on the hosting Lambda Function to satisfy the requirement.

GetAlarmMuteRule: Reading Mute Rules

// init — grants cloudwatch:GetAlarmMuteRule on the rule
const getAlarmMuteRule = yield* AWS.CloudWatch.GetAlarmMuteRule(muteRule);

// runtime
const result = yield* getAlarmMuteRule();
const schedule = result.Rule?.Schedule;

GetDashboard

Source: src/AWS/CloudWatch/GetDashboard.ts

Runtime binding for cloudwatch:GetDashboard — read the body and metadata of the bound Dashboard; the dashboard name is injected automatically.

Provide CloudWatch.GetDashboardHttp on the hosting Lambda Function to satisfy the requirement.

GetDashboard: Reading Dashboards

// init — grants cloudwatch:GetDashboard on the dashboard
const getDashboard = yield* AWS.CloudWatch.GetDashboard(dashboard);

// runtime
const result = yield* getDashboard();
const widgets = JSON.parse(result.DashboardBody ?? "{}").widgets;

GetInsightRuleReport

Source: src/AWS/CloudWatch/GetInsightRuleReport.ts

Runtime binding for cloudwatch:GetInsightRuleReport — fetch the top-contributor report for the bound InsightRule; the rule name is injected automatically.

Provide CloudWatch.GetInsightRuleReportHttp on the hosting Lambda Function to satisfy the requirement.

GetInsightRuleReport: Reading Insight Rules

// init — grants cloudwatch:GetInsightRuleReport on the rule
const getInsightRuleReport = yield* AWS.CloudWatch.GetInsightRuleReport(rule);

// runtime
const now = yield* Effect.sync(() => Date.now());
const result = yield* getInsightRuleReport({
  StartTime: new Date(now - 3_600_000),
  EndTime: new Date(now),
  Period: 300,
});
const contributors = result.Contributors ?? [];

GetMetricData

Source: src/AWS/CloudWatch/GetMetricData.ts

Runtime binding for cloudwatch:GetMetricData — run metric-math queries over one or more metrics in a single call.

Provide CloudWatch.GetMetricDataHttp on the hosting Lambda Function to satisfy the requirement.

GetMetricData: Querying Metrics

// init — grants cloudwatch:GetMetricData
const getMetricData = yield* AWS.CloudWatch.GetMetricData();

// runtime
const now = yield* Effect.sync(() => Date.now());
const result = yield* getMetricData({
  StartTime: new Date(now - 3_600_000),
  EndTime: new Date(now),
  MetricDataQueries: [
    {
      Id: "m1",
      MetricStat: {
        Metric: { Namespace: "MyApp/Payments", MetricName: "PaymentProcessed" },
        Period: 60,
        Stat: "Sum",
      },
    },
  ],
});
const series = result.MetricDataResults ?? [];

GetMetricStatistics

Source: src/AWS/CloudWatch/GetMetricStatistics.ts

Runtime binding for cloudwatch:GetMetricStatistics — fetch aggregated datapoints for a single metric (the older single-metric query API; prefer GetMetricData for metric math or multi-metric queries).

Provide CloudWatch.GetMetricStatisticsHttp on the hosting Lambda Function to satisfy the requirement.

GetMetricStatistics: Querying Metrics

// init — grants cloudwatch:GetMetricStatistics
const getMetricStatistics = yield* AWS.CloudWatch.GetMetricStatistics();

// runtime
const now = yield* Effect.sync(() => Date.now());
const result = yield* getMetricStatistics({
  Namespace: "MyApp/Payments",
  MetricName: "PaymentProcessed",
  StartTime: new Date(now - 3_600_000),
  EndTime: new Date(now),
  Period: 60,
  Statistics: ["Sum"],
});
const datapoints = result.Datapoints ?? [];

GetMetricStream

Source: src/AWS/CloudWatch/GetMetricStream.ts

Runtime binding for cloudwatch:GetMetricStream — read the configuration and state of the bound MetricStream; the stream name is injected automatically.

Provide CloudWatch.GetMetricStreamHttp on the hosting Lambda Function to satisfy the requirement.

GetMetricStream: Reading Metric Streams

// init — grants cloudwatch:GetMetricStream on the stream
const getMetricStream = yield* AWS.CloudWatch.GetMetricStream(metricStream);

// runtime
const result = yield* getMetricStream();
const state = result.State; // "running" | "stopped"

GetMetricWidgetImage

Source: src/AWS/CloudWatch/GetMetricWidgetImage.ts

Runtime binding for cloudwatch:GetMetricWidgetImage — render a metric graph as a PNG (useful for embedding charts in alerts or reports).

Provide CloudWatch.GetMetricWidgetImageHttp on the hosting Lambda Function to satisfy the requirement.

GetMetricWidgetImage: Rendering Metric Graphs

// init — grants cloudwatch:GetMetricWidgetImage
const getMetricWidgetImage = yield* AWS.CloudWatch.GetMetricWidgetImage();

// runtime
const result = yield* getMetricWidgetImage({
  MetricWidget: JSON.stringify({
    metrics: [["MyApp/Payments", "PaymentProcessed"]],
    width: 600,
    height: 400,
    start: "-PT3H",
  }),
});
const png = result.MetricWidgetImage; // image bytes

InsightRule

Source: src/AWS/CloudWatch/InsightRule.ts

A CloudWatch Contributor Insights rule — analyzes log group entries to surface the top-N contributors (IPs, user IDs, …) to a metric derived from structured logs.

InsightRule: Creating Insight Rules

const rule = yield* InsightRule("TopContributors", {
  RuleState: "ENABLED",
  RuleDefinition: {
    Schema: {
      Name: "CloudWatchLogRule",
      Version: 1,
    },
    LogGroupNames: ["/my-app/access-logs"],
    LogFormat: "JSON",
    Contribution: {
      Keys: ["$.ip"],
    },
    AggregateOn: "Count",
  },
});

InsightRule: Reading Reports at Runtime

// init — bind the rule to the function (see GetInsightRuleReport)
const getInsightRuleReport = yield* AWS.CloudWatch.GetInsightRuleReport(rule);

// runtime
const now = yield* Effect.sync(() => Date.now());
const report = yield* getInsightRuleReport({
  StartTime: new Date(now - 3_600_000),
  EndTime: new Date(now),
  Period: 300,
});

ListAlarmMuteRules

Source: src/AWS/CloudWatch/ListAlarmMuteRules.ts

Runtime binding for cloudwatch:ListAlarmMuteRules — list the alarm mute rules in the account/region.

Provide CloudWatch.ListAlarmMuteRulesHttp on the hosting Lambda Function to satisfy the requirement.

ListAlarmMuteRules: Reading Mute Rules

// init — grants cloudwatch:ListAlarmMuteRules
const listAlarmMuteRules = yield* AWS.CloudWatch.ListAlarmMuteRules();

// runtime
const result = yield* listAlarmMuteRules();
const summaries = result.AlarmMuteRuleSummaries ?? [];

ListDashboards

Source: src/AWS/CloudWatch/ListDashboards.ts

Runtime binding for cloudwatch:ListDashboards — list the dashboards in the account, optionally filtered by name prefix.

Provide CloudWatch.ListDashboardsHttp on the hosting Lambda Function to satisfy the requirement.

ListDashboards: Reading Dashboards

// init — grants cloudwatch:ListDashboards
const listDashboards = yield* AWS.CloudWatch.ListDashboards();

// runtime
const result = yield* listDashboards();
const names = (result.DashboardEntries ?? []).map((e) => e.DashboardName);

ListManagedInsightRules

Source: src/AWS/CloudWatch/ListManagedInsightRules.ts

Runtime binding for cloudwatch:ListManagedInsightRules — list the managed Contributor Insights rules available for a given AWS resource ARN.

Provide CloudWatch.ListManagedInsightRulesHttp on the hosting Lambda Function to satisfy the requirement.

ListManagedInsightRules: Reading Insight Rules

// init — grants cloudwatch:ListManagedInsightRules
const listManagedInsightRules = yield* AWS.CloudWatch.ListManagedInsightRules();

// runtime — only specific AWS resource types support managed rules;
// an unsupported ARN fails with the typed InvalidParameterValueException
const result = yield* listManagedInsightRules({
  ResourceARN: yield* table.tableArn,
});
const rules = result.ManagedRules ?? [];

ListMetrics

Source: src/AWS/CloudWatch/ListMetrics.ts

Runtime binding for cloudwatch:ListMetrics — enumerate the metrics visible in the account/region, optionally filtered by namespace, metric name, or dimensions.

Provide CloudWatch.ListMetricsHttp on the hosting Lambda Function to satisfy the requirement.

ListMetrics: Listing Metrics

// init — grants cloudwatch:ListMetrics
const listMetrics = yield* AWS.CloudWatch.ListMetrics();

// runtime
const result = yield* listMetrics({ Namespace: "MyApp/Payments" });
const names = (result.Metrics ?? []).map((metric) => metric.MetricName);

ListMetricStreams

Source: src/AWS/CloudWatch/ListMetricStreams.ts

Runtime binding for cloudwatch:ListMetricStreams — list the metric streams in the account/region.

Provide CloudWatch.ListMetricStreamsHttp on the hosting Lambda Function to satisfy the requirement.

ListMetricStreams: Reading Metric Streams

// init — grants cloudwatch:ListMetricStreams
const listMetricStreams = yield* AWS.CloudWatch.ListMetricStreams();

// runtime
const result = yield* listMetricStreams();
const entries = result.Entries ?? [];

ListTagsForResource

Source: src/AWS/CloudWatch/ListTagsForResource.ts

Runtime binding for cloudwatch:ListTagsForResource — read the tags on a bound CloudWatch resource (alarm, dashboard, metric stream, insight rule, or mute rule); the resource ARN is injected automatically.

Provide CloudWatch.ListTagsForResourceHttp on the hosting Lambda Function to satisfy the requirement.

ListTagsForResource: Reading Tags

// init — grants cloudwatch:ListTagsForResource on the alarm's ARN
const listTagsForResource = yield* AWS.CloudWatch.ListTagsForResource(alarm);

// runtime
const result = yield* listTagsForResource();
const tags = result.Tags ?? [];

MetricSink

Source: src/AWS/CloudWatch/MetricSink.ts

A batching sink over CloudWatch PutMetricData (1000 datums / ~1 MB per call). Each upstream chunk is greedily packed into order-preserving batches and sent sequentially.

PutMetricData is all-or-nothing: there are no per-datum partial failures, so a failed call surfaces directly on the sink’s error channel as the typed PutMetricDataError union.

Provide CloudWatch.MetricSinkHttp (which itself needs CloudWatch.PutMetricDataHttp) on the hosting Lambda Function: Effect.provide(Layer.provideMerge(AWS.CloudWatch.MetricSinkHttp, AWS.CloudWatch.PutMetricDataHttp)).

MetricSink: Streaming Metrics

// init — grants cloudwatch:PutMetricData; all datums publish under Namespace
const sink = yield* AWS.CloudWatch.MetricSink({
  Namespace: "MyApp/Payments",
});

// runtime — datums are packed into 1000-datum PutMetricData batches
yield* Stream.fromIterable(
  payments.map((payment) => ({
    MetricName: "PaymentProcessed",
    Dimensions: [{ Name: "Region", Value: payment.region }],
    Value: payment.amount,
    Unit: "Count",
  }) satisfies AWS.CloudWatch.MetricSinkDatum),
).pipe(Stream.run(sink));

MetricStream

Source: src/AWS/CloudWatch/MetricStream.ts

A CloudWatch metric stream — continuously exports CloudWatch metrics to a Kinesis Data Firehose delivery stream (and on to S3, Datadog, etc.).

MetricStream: Creating Metric Streams

Firehose Delivery Stream

const stream = yield* MetricStream("MetricsExport", {
  FirehoseArn: "arn:aws:firehose:us-east-1:123456789012:deliverystream/example",
  RoleArn: "arn:aws:iam::123456789012:role/example",
  OutputFormat: "json",
});

Stream Only Selected Namespaces

const stream = yield* MetricStream("LambdaMetricsExport", {
  FirehoseArn: firehose.deliveryStreamArn,
  RoleArn: role.roleArn,
  OutputFormat: "json",
  IncludeFilters: [{ Namespace: "AWS/Lambda" }],
});

MetricStream: Reading Metric Streams at Runtime

// init — bind the stream to the function (see GetMetricStream)
const getMetricStream = yield* AWS.CloudWatch.GetMetricStream(stream);

// runtime
const result = yield* getMetricStream();
const state = result.State; // "running" | "stopped"

PutMetricData

Source: src/AWS/CloudWatch/PutMetricData.ts

Runtime binding for cloudwatch:PutMetricData — publish custom metric datums from inside a function runtime.

Provide CloudWatch.PutMetricDataHttp on the hosting Lambda Function to satisfy the requirement. For high-volume publishing prefer the batching MetricSink, which packs datums into 1000-datum PutMetricData calls.

PutMetricData: Publishing Metrics

export default MyFunction.make(
  { main: import.meta.url, functionUrl: true },
  Effect.gen(function* () {
    // init — grants cloudwatch:PutMetricData to the function
    const putMetricData = yield* AWS.CloudWatch.PutMetricData();

    return {
      fetch: Effect.gen(function* () {
        // runtime — publish a datum on every request
        yield* putMetricData({
          Namespace: "MyApp/Payments",
          MetricData: [
            { MetricName: "PaymentProcessed", Value: 1, Unit: "Count" },
          ],
        });
        return HttpServerResponse.text("ok");
      }).pipe(Effect.orDie),
    };
  }).pipe(Effect.provide(AWS.CloudWatch.PutMetricDataHttp)),
);

SetAlarmState

Source: src/AWS/CloudWatch/SetAlarmState.ts

Runtime binding for cloudwatch:SetAlarmState — force the bound alarm into a specific state (useful for testing alarm actions or resetting a stuck alarm). Bind it to an Alarm / CompositeAlarm; the alarm name is injected automatically.

Provide CloudWatch.SetAlarmStateHttp on the hosting Lambda Function to satisfy the requirement.

SetAlarmState: Managing Alarm Actions

// init — grants cloudwatch:SetAlarmState on the alarm
const setAlarmState = yield* AWS.CloudWatch.SetAlarmState(alarm);

// runtime
yield* setAlarmState({
  StateValue: "ALARM",
  StateReason: "fire-drill: verifying the on-call page",
});

StartMetricStreams

Source: src/AWS/CloudWatch/StartMetricStreams.ts

Runtime binding for cloudwatch:StartMetricStreams — resume streaming for the bound metric streams after they were paused with StopMetricStreams. Bind it to one or more MetricStream resources; the stream names are injected automatically.

Provide CloudWatch.StartMetricStreamsHttp on the hosting Lambda Function to satisfy the requirement.

StartMetricStreams: Managing Metric Streams

// init — grants cloudwatch:StartMetricStreams on the stream
const startMetricStreams = yield* AWS.CloudWatch.StartMetricStreams(stream);

// runtime
yield* startMetricStreams();

StopMetricStreams

Source: src/AWS/CloudWatch/StopMetricStreams.ts

Runtime binding for cloudwatch:StopMetricStreams — pause streaming for the bound metric streams (e.g. to control Firehose cost during an incident). Resume with StartMetricStreams. Bind it to one or more MetricStream resources; the stream names are injected automatically.

Provide CloudWatch.StopMetricStreamsHttp on the hosting Lambda Function to satisfy the requirement.

StopMetricStreams: Managing Metric Streams

// init — grants cloudwatch:StopMetricStreams on the stream
const stopMetricStreams = yield* AWS.CloudWatch.StopMetricStreams(stream);

// runtime
yield* stopMetricStreams();