Write a canary script in Node.js using the synthetics library provided by CloudWatch (available in the Lambda execution environment); use the syn-nodejs-puppeteer or syn-playwright runtime for UI canaries, or the syn-nodejs-puppeteer runtime for API canaries
For an API canary, use the SyntheticsRestApiStep or write a direct HTTPS request; assert on response status code and optionally response body content using the built-in assertions
Upload the canary script as a .zip file to S3, or paste it inline for simple scripts; create the canary via the AWS Console, CLI, or CloudFormation with the schedule expression (e.g., rate(5 minutes))
Assign an IAM execution role to the canary with permissions to write CloudWatch Logs, write canary artifacts to S3, and optionally access resources inside your VPC if the canary runs inside a VPC
Create a CloudWatch Alarm on the CloudWatchSynthetics/Canary metric SuccessPercent for your canary name; set the threshold (e.g., below 100%) and connect to an SNS topic or PagerDuty integration
Review canary run artifacts (screenshots, HAR files, logs) in the S3 bucket specified during creation to debug failures
Known gotchas
CloudWatch Synthetics runtime versions are periodically deprecated; canaries running on deprecated runtimes eventually stop executing — subscribe to AWS deprecation notices and update the runtime version proactively
Canaries that run inside a VPC require a NAT gateway or VPC endpoints to reach the CloudWatch and S3 service endpoints; without outbound internet access or VPC endpoints, canary artifacts cannot be uploaded and the canary fails silently
The IAM execution role must be unique per canary if canaries need different permissions; sharing a single role across all canaries grants every canary all permissions, which violates least privilege
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp