AWS CloudWatch ExecModule

Overview

AwsCloudWatchModule brings bounded Amazon CloudWatch metric and alarm operations into ValkyrAI workflows. It discovers metrics, retrieves recent time series and statistics, inspects alarms and alarm history, publishes reviewed custom metric batches, and governs exact alarm creation, deletion, action enablement, and manual state changes.

The module uses ValkyrAI's native map ABI, annotation-backed Workflow Studio discovery, and a verified IntegrationAccount. Workflow input never accepts AWS access keys, secret keys, session tokens, authorization headers, endpoint overrides, arbitrary CloudWatch requests, metric math expressions, or alarm rule documents.

The connector is designed for deployment gates, SRE and incident workflows, operational scorecards, telemetry-backed agent decisions, and alarm lifecycle automation. Every provider mutation requires an operation-specific confirmation and is sent once. Read operations may retry transient failures with bounded backoff.

Usage

1. Create or select a least-privilege AWS identity for the required CloudWatch actions.
2. Store its access-key pair in an AWS IntegrationAccount.
3. Verify the account and ensure its status is READY.
4. Add AwsCloudWatchModule and bind that account through ExecModuleConfig.authConfig.integrationAccount.
5. Choose an operation, AWS region, and bounded metric or alarm scope.
6. For writes, reconcile the current metric or alarm state and set only the matching confirmation field to true.

Never place credentials in module input. Credential-shaped fields are rejected before any AWS request.

Inputs

Common inputs

Input	Type	Required	Default	Purpose
operation	string	Yes	—	One supported CloudWatch operation.
region	string	Yes	—	AWS region such as us-west-2.
nextToken	string	No	—	Opaque provider continuation token.
limit	integer	For list operations	100	Total item bound from 1 to 1,000.
returnAll	boolean	For list operations	false	Follow provider pages until limit or a provider boundary.

Metric identity and time range

Input	Type	Rules
namespace	string	Up to 255 characters. Required for statistics, publication, and alarm writes. Custom publication namespaces cannot begin with AWS/.
metricName	string	Exact metric name, up to 255 characters.
dimensions	object array	Up to 30 unique {name, value} objects. list_metrics may omit a filter value; other metric operations require it.
startTime	ISO-8601 string	Inclusive query start.
endTime	ISO-8601 string	Exclusive query end. Must be after startTime.
period	integer	Aggregation period from 1 to 86,400 seconds.
unit	string	Optional CloudWatch standard unit. CloudWatch does not convert units.

Metric query windows are capped at 31 days to bound data exposure and execution cost. CloudWatch retention and period rules still determine which historical datapoints are available.

get_metric_statistics

Provide at least one of:

• statistics: unique values from SampleCount, Average, Sum, Minimum, and Maximum.
• extendedStatistics: up to ten percentile values such as p50, p95, or p99.9.

The operation returns provider datapoints sorted by timestamp. It does not infer a unit, change period alignment, or fill missing intervals.

get_metric_data

metricQueries contains 1–10 metric-stat queries. Each object supports:

Field	Required	Notes
id	Yes	Unique identifier beginning with a lowercase letter.
label	No	Customer-safe result label.
namespace	Yes	Exact metric namespace.
metricName	Yes	Exact metric name.
dimensions	No	Up to 30 exact dimensions.
period	No	Defaults to 300 seconds.
stat	Yes	One standard statistic.
unit	No	Optional standard unit.
returnData	No	Defaults to true.

maxDatapoints is bounded from 1 to 10,000, and scanBy accepts TimestampAscending or TimestampDescending. Metric Insights and metric-math expressions are intentionally not accepted in this release, which keeps query behavior reviewable and resource scope explicit.

put_metric_data

metricData contains 1–20 custom datum objects:

[
  {
    "metricName": "WorkflowCompleted",
    "value": 1,
    "timestamp": "2026-10-23T07:00:00Z",
    "unit": "Count",
    "storageResolution": 60,
    "dimensions": [
      {"name": "Workflow", "value": "checkout"}
    ]
  }
]

• Values must be finite numbers; NaN and infinity are rejected.
• storageResolution must be 1 or 60 seconds.
• Namespace, metric names, dimensions, timestamps, units, and the whole batch are bounded before AWS access.
• confirmMetricPublish: true is mandatory.

Alarm inputs

describe_alarms accepts exact alarmNames, or one alarmNamePrefix, plus optional stateValue and actionPrefix. Prefix and exact-name filters are mutually exclusive.

put_metric_alarm requires:

• alarmName, namespace, metricName, period, evaluationPeriods, threshold, and comparisonOperator;
• exactly one of statistic or extendedStatistic;
• optional datapointsToAlarm, unit, treatMissingData, and exact metric dimensions;
• up to five exact ARNs in each of alarmActions, okActions, and insufficientDataActions;
• confirmAlarmWrite: true.

Creating or updating an alarm is a complete overwrite of its provider configuration. Read the current alarm first and send the full reviewed configuration.

Other confirmations:

Mutation	Confirmation
delete_alarms	confirmDelete: true
enable_alarm_actions / disable_alarm_actions	confirmActionChange: true
set_alarm_state	confirmSetState: true plus stateReason

Outputs

Successful output uses a stable envelope:

Output	Meaning
status	success or error.
operation	Normalized operation name.
attempts	Provider calls, including pages and read retries.
resultType	Metric, datapoint, alarm, history, or control family.
items / count	Bounded normalized metrics, time series, datapoints, alarms, or history items.
pages	Provider pages consumed by list operations.
hasMore / nextToken	Whether and where provider pagination may continue.
data	Exact resource summary or mutation receipt.
requestId	Safe AWS request reference when available.
error	Safe error code, message, HTTP status, and retryability.

Normalized output excludes credentials, authorization material, raw provider exception text, CloudWatch history payload blobs, and unbounded provider objects.

IntegrationAccount Requirements

The bound account must be verified, have status READY, and supply its AWS access-key ID through apiKey plus its secret access key through password. The module never serializes those fields into output or logs.

Grant only the actions used by the workflow:

cloudwatch:ListMetrics
cloudwatch:GetMetricData
cloudwatch:GetMetricStatistics
cloudwatch:PutMetricData
cloudwatch:DescribeAlarms
cloudwatch:DescribeAlarmHistory
cloudwatch:PutMetricAlarm
cloudwatch:DeleteAlarms
cloudwatch:EnableAlarmActions
cloudwatch:DisableAlarmActions
cloudwatch:SetAlarmState

Scope custom metric publication with IAM conditions where available. AWS requires cloudwatch:DescribeAlarms on * to return composite alarms; this module currently normalizes metric alarms only. Alarm actions may require additional permissions or service-linked roles for the target AWS service.

Configuration

The module uses ExecModuleConfig for the IntegrationAccount binding, retry ceiling, and workflow policy. It does not accept endpoint overrides, custom signing hosts, inline IAM policies, raw SDK requests, alarm rule documents, metric math expressions, or cross-account role material.

Reads use at most five attempts, bounded by configured maxAttempts. AWS SDK retries are disabled so the module owns the visible attempt count. Mutations always use one provider call, even when AWS returns a transient error.

Operations

Operation	Behavior	Side effect
list_metrics	Lists bounded metric identities with optional namespace, name, and dimension filters.	None
get_metric_data	Runs up to ten bounded metric-stat queries.	None; billed read
get_metric_statistics	Retrieves standard and percentile statistics for one exact metric.	None
put_metric_data	Publishes one confirmed bounded custom-metric batch.	Writes telemetry
describe_alarms	Lists bounded metric alarms with exact or prefix filters.	None
get_alarm	Reads one exact alarm.	None
describe_alarm_history	Reads bounded summary history for an alarm and time range.	None
put_metric_alarm	Creates or completely overwrites one confirmed metric alarm.	Changes monitoring behavior
delete_alarms	Deletes up to 100 exact confirmed alarms.	Destructive
enable_alarm_actions	Enables actions on exact confirmed alarms.	Changes automated response
disable_alarm_actions	Disables actions on exact confirmed alarms.	Changes automated response
set_alarm_state	Sets one exact manual state with a human-readable reason.	Changes alarm state

Errors and Failure Modes

Code	Meaning	Retry guidance
VALIDATION_ERROR	Input, time range, metric shape, alarm shape, bound, or confirmation failed locally.	Correct input; no AWS call occurred.
INTEGRATION_ACCOUNT_ERROR	The account is missing, unverified, not READY, or incomplete.	Repair the account binding.
AWS_CLOUDWATCH_HTTP_400	AWS rejected the metric, alarm, timestamp, state, quota, or configuration.	Usually no; inspect exact state first.
AWS_CLOUDWATCH_HTTP_403	IAM denied the action or resource.	Add only the missing least-privilege permission.
AWS_CLOUDWATCH_HTTP_429 / 500 / 502 / 503 / 504	Throttling or transient provider pressure.	Reads retry; writes report ambiguity.
NETWORK_ERROR	AWS could not be reached.	Reads may retry; reconcile an attempted write before replay.
EXECUTION_ERROR	An unexpected local failure was safely normalized.	Use logs and request references; secrets remain redacted.

AWS may accept a write before the client observes a timeout. A retryable status is never permission to blindly republish metrics, overwrite or delete alarms, toggle actions, or set state. Read the exact provider state first.

Example

This example reads recent Lambda error totals for a release gate:

{
  "operation": "get_metric_statistics",
  "region": "us-west-2",
  "namespace": "AWS/Lambda",
  "metricName": "Errors",
  "dimensions": [
    {"name": "FunctionName", "value": "checkout"}
  ],
  "startTime": "2026-10-23T06:00:00Z",
  "endTime": "2026-10-23T07:00:00Z",
  "period": 300,
  "statistics": ["Sum"]
}

Expected normalized result:

{
  "status": "success",
  "operation": "get_metric_statistics",
  "attempts": 1,
  "resultType": "datapoints",
  "count": 2,
  "items": [
    {"timestamp": "2026-10-23T06:50:00Z", "sum": 0, "unit": "Count"},
    {"timestamp": "2026-10-23T06:55:00Z", "sum": 2, "unit": "Count"}
  ],
  "data": {"label": "Errors", "datapointCount": 2},
  "requestId": "example-request-id"
}

The workflow can compare the bounded provider result with a reviewed threshold, pause a rollout, open an incident, or request human approval. The response is a point-in-time read, not a continuous monitor.

Notes

• Pagination: list_metrics, describe_alarms, and describe_alarm_history expose nextToken; returnAll: true follows at most 100 pages and never returns more than limit items. get_metric_data returns its provider token for an explicit follow-up request.
• Rate limits and cost: CloudWatch quotas and pricing vary by API, region, and account. Bound queries, avoid tight polling loops, and treat GetMetricData as a billed read according to the AWS pricing model.
• Data freshness: New metrics can take time to appear in ListMetrics. Older or backdated custom datapoints can also take longer to become queryable.
• Retention: Available resolution changes with metric age. Align periods and query windows with CloudWatch retention rules.
• Units: CloudWatch does not convert units. Supplying a unit that does not match stored data can produce an empty result.
• Idempotency: Reads are repeatable. Metric publication and alarm mutations are never automatically retried.
• Destructive behavior: Alarm deletion is destructive. Disabling actions can suppress automated response even though alarm evaluation continues.
• Manual state: set_alarm_state is intended for reviewed testing or recovery. CloudWatch can replace the manual state on the next evaluation.
• Alarm overwrite: put_metric_alarm replaces the previous alarm configuration. Always read and review the current alarm first.
• Deferred capabilities: Composite-alarm writes, Metrics Insights, metric math expressions, anomaly detectors, dashboards, tagging, Contributor Insights, Internet Monitor, Application Signals, and CloudWatch Logs APIs are intentionally deferred.
• Credential boundary: Live AWS behavior is unverified until an authorized least-privilege non-production account and reviewed resources are supplied.
• Functional reference: n8n's AWS integrations establish a familiar AWS IAM credential, region, resource, operation, and pagination model. ValkyrAI applies that interaction model to CloudWatch while adding strict IntegrationAccount binding, bounded typed inputs, explicit write confirmations, normalized outputs, and mutation replay safety.
• Runtime boundary: Merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsCloudWatchModule through /v1/modules/metadata.

Related documentation

• Amazon CloudWatch API Reference
• CloudWatch metric data retention
• AWS Elastic Load Balancing ExecModule