Docs / Strand / connectors/aws-cloudwatch

AWS CloudWatch Connector

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:

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

Operations

Put Metric Data

Publish a custom metric data point to CloudWatch.

Example: Publish an order count metric

• Namespace: MyApp/Orders
• Metric Name: OrdersProcessed
• Value: {{ payload.order_count }}
• Unit: Count

Get Metric Data

Retrieve metric statistics from CloudWatch over a specified time period.

Example: Get average CPU utilization

• Namespace: AWS/EC2
• Metric Name: CPUUtilization
• Period: 60
• Statistic: Average
• Lookback (minutes): 120

Put Log Events

Write log messages to a CloudWatch Logs stream.

Example: Log a workflow event

• Log Group Name: /strand/workflows
• Log Stream Name: order-processing
• Message:

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

Output

Put Metric Data Output

{
  "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

{
  "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:

• {{ steps.node_a1b2c3d4.output_payload.data.datapoints }}: Array of metric data points
• {{ steps.node_a1b2c3d4.output_payload.data.datapoints[0].value }}: Most recent data point value

Put Log Events Output

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

Errors

Example Workflow

1. Create Connector with your AWS credentials and region us-east-1 (or use auth_type: "role" to leverage the host's IAM role)
2. Put metric data to track workflow executions:

• Namespace: Strand/Workflows
• Metric Name: ExecutionCount
• Value: 1
• Unit: Count

1. Put log events to record the workflow result:

• Log Group: /strand/workflows
• Log Stream: execution-log
• Message: Workflow {{ payload.workflow_id }} completed with status {{ payload.status }}

1. Get metric data to check recent execution trends:

• Namespace: Strand/Workflows
• Metric Name: ExecutionCount
• Period: 3600
• Stat: Sum

Limitations

• Metric resolution: Standard resolution metrics have a minimum period of 60 seconds. High-resolution metrics (1-second period) are not currently supported.
• Log event size: Individual log events are limited to 256 KB by AWS.
• No metric dimensions: Put Metric Data publishes a single value per metric name; dimensions are not supported.
• Batch operations: Each Put Metric Data call publishes a single data point. For high-throughput metrics, consider aggregating values before publishing.
• Log group/stream creation: Put Log Events automatically creates the log group and log stream if they don't already exist (requires logs:CreateLogGroup and logs:CreateLogStream).
• Querying logs: CloudWatch Logs Insights queries are not currently supported. Use Get Metric Data for metric retrieval.

← Back to Strand docs