/aws-observability

CloudWatch Synthetics

Runtime constraints, blueprint compatibility, and common pitfalls for CloudWatch Synthetics canaries.

Contents

• Runtime and blueprint compatibility
• VPC canaries
• Common failures
• Limits

Runtime and blueprint compatibility

Playwright cannot use 4 of 7 blueprints. Java has no browser — API-only.

Run aws synthetics describe-runtime-versions for the latest runtime versions.

Deprecated runtimes continue running but you cannot update code or config without upgrading first.

Key flags

CDK:

const canary = new synthetics.Canary(this, 'ApiCanary', {
  // ... standard props ...
  activeTracing: true,              // X-Ray — adds 2.5-7% to run time
  provisionedResourceCleanup: true, // delete Lambda on canary delete
  artifactsBucketLifecycleRules: [{ expiration: Duration.days(30) }], // prevent S3 accumulation
});

// BREACHING — canary not running IS the problem
canary.metricSuccessPercent().createAlarm(this, 'CanaryAlarm', {
  threshold: 90,
  evaluationPeriods: 3,
  datapointsToAlarm: 2,
  comparisonOperator: ComparisonOperator.LESS_THAN_THRESHOLD,
  treatMissingData: TreatMissingData.BREACHING,
});

maxRetries (via Schedule.RetryConfig) and dryRunAndUpdate are not exposed in the CDK L2 construct — use CfnCanary escape hatch or CLI.

CLI — alarm on canary success rate:

aws cloudwatch put-metric-alarm \
  --alarm-name my-api-canary-success \
  --namespace CloudWatchSynthetics \
  --metric-name SuccessPercent \
  --dimensions Name=CanaryName,Value=my-api-canary \
  --statistic Average --period 300 \
  --evaluation-periods 3 --datapoints-to-alarm 2 \
  --threshold 90 --comparison-operator LessThanThreshold \
  --treat-missing-data breaching

CLI — safe update via dry run:

aws synthetics start-canary-dry-run --name my-api-canary --runtime-version syn-nodejs-puppeteer-15.0
aws synthetics get-canary --name my-api-canary --dry-run-id $DRY_RUN_ID
aws synthetics update-canary --name my-api-canary --dry-run-id $DRY_RUN_ID

Key CDK/CloudFormation constraints:

• ExecutionRoleArn is required — CloudFormation does not auto-create roles (unlike the console)
• Changing Name triggers replacement (delete + create), causing monitoring gaps
• Without provisionedResourceCleanup: true, deleting the stack orphans Lambda functions and layers
• Editing any canary property resets the schedule — next run happens immediately

VPC canaries

Canaries in VPCs must run in private subnets (Lambda ENIs don't get public IPs, even in public subnets).

Internet access (required for uploading metrics to CloudWatch and artifacts to S3):

• Option A: NAT Gateway in a public subnet + route from private subnet
• Option B: VPC endpoints — Interface endpoint for monitoring, Gateway endpoint for s3

VPC endpoint policy constraint: The S3 gateway endpoint policy must include s3:ListAllMyBuckets, s3:GetBucketLocation, and s3:PutObject — separate from the IAM role policy.

DNS: Both DNS Resolution and DNS Hostnames must be enabled on the VPC.

Silent failure mode: If the VPC has no internet access and no VPC endpoints, the canary runs but cannot upload metrics or artifacts — it appears as if it never ran.

Common failures

Limits