Tendrl

Docs / Strand / connectors/aws-cloudwatch

AWS CloudWatch Connector

Direction: Read / Write | Type: aws.cloudwatch

Publish custom metrics, retrieve metric data, and write log events to Amazon CloudWatch from your Strand workflows.

Prerequisites#

You need AWS credentials with CloudWatch and CloudWatch Logs permissions. Here's how to set them up:

  1. Sign in to the AWS Management Console and navigate to IAM
  2. Create a new IAM user or use an existing one
  3. Attach a policy with the permissions listed in Required Permissions below
  4. Under Security credentials, create an Access key
  5. Copy the Access Key ID and Secret Access Key

Required Permissions#

The IAM user or role must have the following permissions:

Operation Required IAM Permissions
Put Metric Data cloudwatch:PutMetricData
Get Metric Data cloudwatch:GetMetricStatistics
Put Log Events logs:PutLogEvents, logs:CreateLogGroup, logs:CreateLogStream
Tip: If you only need metrics or only need logs, scope the IAM policy accordingly to follow the principle of least privilege.

Connector Setup#

Create an AWS CloudWatch connector from the Connectors page.

Configuration Fields#

Field Required Description
Name Yes Friendly name (e.g., "Production CloudWatch")
Authentication Type No Uses explicit AWS access-key credentials (the fields below).
Region Yes AWS region for CloudWatch (e.g., us-east-1)
Endpoint URL No Custom endpoint for a self-managed target or an AWS VPC endpoint. Leave empty for AWS.
Access Key ID Conditional IAM user access key ID (encrypted at rest). Required when Authentication Type is api_key
Secret Access Key Conditional IAM user secret access key (encrypted at rest). Required when Authentication Type is api_key
Timeout No API request timeout in seconds (default: 30)
Description No Optional description for reference

Operations#

Put Metric Data#

Publish a custom metric data point to CloudWatch.

Field Required Description
Namespace Yes CloudWatch namespace for the metric (e.g., MyApp/Orders)
Metric Name Yes Name of the metric (e.g., OrderCount)
Value Yes Numeric value for the data point (e.g., {{ payload.count }})
Unit No Unit of the metric: Count, Seconds, Milliseconds, Bytes, Percent, None (default: None)

Example: Publish an order count metric

Get Metric Data#

Retrieve metric statistics from CloudWatch over a specified time period.

Field Required Description
Namespace Yes CloudWatch namespace of the metric
Metric Name Yes Name of the metric to retrieve
Lookback (minutes) No How far back to look for data (default: 60). Ignored if Start Time is set.
Start Time No ISO 8601 start time. Overrides Lookback.
End Time No ISO 8601 end time (default: now)
Period No Granularity of data points in seconds (default: 300)
Statistic No Statistic to retrieve: Average, Sum, Minimum, Maximum, SampleCount (default: Average)

Example: Get average CPU utilization

Put Log Events#

Write log messages to a CloudWatch Logs stream.

Field Required Description
Log Group Name Yes Name of the log group (e.g., /myapp/production). Created automatically if it doesn't exist.
Log Stream Name Yes Name of the log stream within the group (e.g., workflow-events). Created automatically if it doesn't exist.
Message Yes Log message text

Example: Log a workflow event

code

[{{ payload.severity }}] Order {{ payload.order_id }} processed - status: {{ payload.status }}, duration: {{ payload.duration_ms }}ms

Output#

Put Metric Data Output#

json

{
  "success": true,
  "status": "sent",
  "data": {
    "namespace": "MyApp/Orders",
    "metric_name": "OrdersProcessed",
    "value": 42,
    "unit": "Count"
  },
  "service": "aws.cloudwatch",
  "operation": "put_metric_data"
}

Get Metric Data Output#

json

{
  "success": true,
  "status": "completed",
  "data": {
    "metric_name": "CPUUtilization",
    "namespace": "AWS/EC2",
    "datapoints": [
      {
        "timestamp": "2026-02-18T14:00:00Z",
        "value": 34.5,
        "unit": "Percent"
      },
      {
        "timestamp": "2026-02-18T14:05:00Z",
        "value": 28.2,
        "unit": "Percent"
      }
    ],
    "count": 2,
    "statistic": "Average",
    "period": 300
  },
  "service": "aws.cloudwatch",
  "operation": "get_metric_data"
}

Key fields for subsequent nodes:

Put Log Events Output#

json

{
  "success": true,
  "status": "sent",
  "data": {
    "log_group": "/strand/workflows",
    "log_stream": "order-processing"
  },
  "service": "aws.cloudwatch",
  "operation": "put_log_events"
}

Errors#

Error Meaning
AWS access_key_id is required Access key ID not configured in connector.
AWS secret_access_key is required Secret access key not configured in connector.
Namespace is required No namespace specified for metric operations.
Metric name is required No metric name specified.
Value is required No numeric value provided for Put Metric Data.
Log group name is required No log group specified for Put Log Events.
Log stream name is required No log stream specified for Put Log Events.
ResourceNotFoundException The specified log group or log stream does not exist.
InvalidParameterException A parameter value is invalid (e.g., unsupported unit or stat).
LimitExceededException API rate limit exceeded. Retry with backoff.
AccessDeniedException The IAM user lacks the required CloudWatch or Logs permissions.
UnrecognizedClientException Invalid AWS access key ID.
SignatureDoesNotMatch Secret access key is incorrect.

Example Workflow#

  1. Create Connector with your AWS credentials and region us-east-1
  2. Put metric data to track workflow executions:
  1. Put log events to record the workflow result:
  1. Get metric data to check recent execution trends:

Limitations#

← Back to Strand docs