CloudWatch Synthetics: Setting Up Canary Monitoring Step by Step (2026 Guide)

CloudWatch Synthetics lets you monitor endpoints and user flows before customers hit failures. A canary runs scripted tests against your application every 1 to 60 minutes, detecting broken APIs, slow page loads, or unavailable endpoints. Without synthetic monitoring, you only discover issues after users report them. With canaries, you catch problems in staging or production before they compound.

This guide walks through creating a CloudWatch Synthetics canary from scratch: choosing a blueprint or custom script, configuring runtime and schedule, setting up VPC access for private endpoints, and connecting alarms to Slack or PagerDuty. You will also learn how to troubleshoot failed canaries and optimize canary costs as your monitoring scales.

Prerequisites

Before creating a CloudWatch Synthetics canary, ensure you have:

• An AWS account with active access to the CloudWatch console
• IAM permissions for synthetics:CreateCanary, s3:PutObject, lambda:CreateFunction, and iam:PassRole
• An S3 bucket in the same region as your canary for storing artifacts (or let CloudWatch create one automatically)
• The target endpoint URL you want to monitor (must include protocol like https://)
• VPC details (VPC ID, subnet IDs, security group IDs) if monitoring a private endpoint inside your VPC
• A Lambda execution role with permissions to execute canaries and write logs to CloudWatch (or let CloudWatch create one automatically)

If you monitor endpoints outside AWS or simulate user journeys across multiple regions, consider how synthetic monitoring tools compare on multi location testing, frequency limits, and pricing models.

Step 1: Choose Between Blueprint and Custom Script

Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/ and navigate to Application Signals > Synthetics Canaries. Click Create Canary.

You have two script options:

Use a blueprint for pre-built common patterns:

• Heartbeat monitoring: sends a GET request to a single endpoint every interval to verify availability
• API Canary: tests a REST API with configurable request method, headers, and expected status codes
• Broken Link Checker: crawls a webpage and reports broken internal or external links
• Visual Monitoring: captures screenshots and diffs them against a baseline to detect UI changes
• GUI Workflow: records and replays browser interactions like login, form submission, or checkout

Upload a custom script if you need multi-step workflows, complex authentication, or conditional logic. Custom scripts use Node.js with Synthetics runtime libraries. You can drag your .js file into the Script area or choose Import from S3 to load a script already stored in S3. When importing from S3, you must have s3:GetObject and s3:GetObjectVersion permissions, and the bucket must be in the same region where you create the canary.

For most teams starting with CloudWatch Synthetics, blueprints cover 80% of use cases. Custom scripts become necessary when testing requires session handling, multi-page flows, or conditional branching based on API responses.

Step 2: Configure Canary Name, URL, and Runtime

Under Name, enter a descriptive name for the canary. This name appears on dashboards, in alarms, and in CloudWatch Logs, so use a format that identifies both the endpoint and the test type (e.g., prod-api-login-heartbeat or staging-checkout-workflow).

Under Application or endpoint URL, enter the full URL you want to test. Include the protocol (https://api.example.com/health not api.example.com/health). If the endpoint is behind a VPC and not publicly accessible, you must configure VPC settings later in this process.

Under Script editor, Runtime version, select a synthetics runtime version. As of early 2026, syn-nodejs-puppeteer-10.2 is the latest stable runtime. Older runtimes (like syn-nodejs-puppeteer-3.x) are deprecated and should not be used for new canaries. The runtime determines which Node.js version and Puppeteer version your script executes with.

If you selected a GUI Workflow blueprint, you can optionally configure browser settings like screen resolution, user agent string, and viewport size. These settings affect how the canary interacts with the application under test.

If your script requires environment variables (API keys, tokens, feature flags), choose Environment variables and define key value pairs. These are accessible in your script via process.env.VARIABLE_NAME and are useful for keeping secrets out of your script code.

Step 3: Set Schedule and Frequency

Under Schedule, choose how often the canary runs:

• Run once: executes the test immediately, useful for ad hoc verification or testing a new canary script
• Continuously: runs at a fixed rate defined by a rate expression (every 1 minute, every 5 minutes, every 1 hour)
• Cron expression: runs at specific times using cron syntax (e.g., cron(0 12 * * ? *) runs daily at 12:00 PM UTC)

Most production monitoring uses continuous scheduling between every 1 minute and every 15 minutes. High frequency canaries (every 1 minute) detect issues faster but cost more in Lambda invocations and S3 storage. Low frequency canaries (every 30 or 60 minutes) cost less but introduce longer detection windows.

For cron expressions, CloudWatch Synthetics uses standard six-field cron format: cron(minutes hours day-of-month month day-of-week year). Use ? for day of month or day of week when the other is specified. Example: cron(0 */6 * * ? *) runs every 6 hours starting at midnight UTC.

Set a timeout value under Additional configuration. The timeout defines how long the canary can run before Lambda kills the execution. For simple API canaries, 15 to 30 seconds is sufficient. For browser workflows with multiple page loads, set 60 to 120 seconds. Never set a timeout shorter than 15 seconds to allow for Lambda cold starts and the canary instrumentation bootstrap time.

Step 4: Configure Data Storage and Retention

Under Data retention, specify how long CloudWatch Synthetics retains canary run data. The range is 1 to 455 days. This setting controls how far back you can query canary run results via GetCanaryRuns API calls and how much historical data appears in the Synthetics console.

Data retention does not affect logs in CloudWatch Logs, metrics in CloudWatch Metrics, or artifacts stored in S3. Those are governed by their respective retention policies. If you delete a canary, its S3 artifacts remain unless you manually delete the S3 prefix.

Under Data Storage, select the S3 bucket where canary artifacts (screenshots, HAR files, logs) are stored. If you leave this blank, CloudWatch creates a default bucket named cw-syn-results-{account-id}-{region}. The bucket name cannot contain a period (.).

By default, canary artifacts are encrypted at rest using an AWS managed KMS key (aws/s3). To use a customer managed KMS key, choose Additional configuration in the Data Storage section and select your key. You must grant the canary’s Lambda execution role kms:Decrypt and kms:GenerateDataKey permissions on that key.

Step 5: Set Up IAM Role and Permissions

Under Access permissions, choose whether to create a new IAM role or use an existing one.

If you choose Create a new role, CloudWatch Synthetics automatically creates a role with the minimum necessary permissions:

• lambda:InvokeFunction to execute the canary
• s3:PutObject to write artifacts to S3
• logs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEvents to send logs to CloudWatch
• cloudwatch:PutMetricData to publish canary metrics

This auto-created role is specific to one canary and cannot be reused for other canaries. If you manage multiple canaries, you may prefer to create a shared role manually and select Use an existing role here.

To use an existing role, you must have iam:PassRole permission to pass that role to Synthetics and Lambda, and iam:GetRole permission to retrieve role details. The role must trust both lambda.amazonaws.com and synthetics.amazonaws.com as service principals.

If your canary monitors an endpoint inside a VPC, the IAM role must also have ec2:CreateNetworkInterface, ec2:DescribeNetworkInterfaces, and ec2:DeleteNetworkInterface permissions to attach the Lambda function to your VPC subnets.

Step 6: Configure VPC Settings (Optional)

If the endpoint you are monitoring is inside a VPC and not publicly accessible, you must configure VPC settings so the canary’s Lambda function can reach it.

Choose VPC settings and configure:

• VPC: select the VPC that hosts the private endpoint
• Subnets: select one or more private subnets (you must select private subnets because Lambda functions running in VPCs cannot be assigned public IP addresses during execution)
• Security groups: select one or more security groups that allow outbound traffic to the target endpoint

If your endpoint is IPv6 only or dual stack, select Allow IPv6 Traffic for dual stack subnets. This enables the canary to monitor IPv6 endpoints over IPv6.

To give your canary internet access from a private subnet, configure a NAT gateway in the subnet’s route table. Without a NAT gateway or VPC endpoint for CloudWatch and S3, the canary cannot publish metrics or upload artifacts.

For more on VPC configuration, see the AWS documentation on Running a canary on a VPC: https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_VPC.html

If you selected replica regions under Locations (multi location canaries), you can configure separate VPC settings for each replica region. VPC settings are not inherited from the primary canary.

Step 7: Enable Alarms and Notifications

Under Alarms, choose whether to create default CloudWatch alarms for this canary. If you enable alarms, CloudWatch creates alarms with the naming convention Synthetics-Alarm-canaryName-index, where index starts at 1 and increments for each alarm created.

The default alarms monitor:

• SuccessPercent: triggers if the canary success rate drops below 90% over the evaluation period
• Duration: triggers if the canary duration exceeds a threshold (useful for detecting slow API responses or slow page loads)

These alarms are useful for basic monitoring but most teams need custom alarm thresholds. You can edit the alarms after creation or create new alarms manually targeting the canary’s CloudWatch metrics.

To send alarm notifications to Slack, PagerDuty, or email, create an SNS topic and subscribe your notification endpoints to it. Then edit the canary alarms to publish to that SNS topic. CloudWatch Synthetics does not natively integrate with alerting tools, you must use SNS as the bridge.

For teams using infrastructure monitoring tools that support CloudWatch metrics ingestion, you can forward canary metrics to your observability platform and create alerts there instead of in CloudWatch.

Step 8: Add Tags and Create Canary

Under Tags, add key value pairs to organize canaries by environment, team, or application. Tags propagate to the canary’s Lambda function, S3 artifacts, and CloudWatch Logs, making it easier to filter costs and access in AWS Cost Explorer and IAM policies.

Common tag examples:

• Environment: production
• Team: platform-engineering
• Application: checkout-api
• CostCenter: engineering-ops

Review all settings and click Create canary. CloudWatch Synthetics creates:

• A Lambda function in your account to execute the canary script
• A CloudWatch Logs log group at /aws/lambda/cwsyn-canaryName-{id}
• An S3 prefix in your selected bucket at canaryName/{canary-id}/
• A CloudWatch metric namespace CloudWatchSynthetics with metrics for the canary

The canary runs immediately (if scheduled) or waits for the next scheduled interval. The first run may take 15 to 30 seconds longer than subsequent runs due to Lambda cold start.

Troubleshooting Common Issues

Canary Fails with “Execution role does not have permissions”

Cause: The IAM role assigned to the canary lacks required permissions to invoke Lambda, write to S3, or publish metrics.

Fix: Attach the AWS managed policy CloudWatchSyntheticsFullAccess to the role, or manually add missing permissions. Check the Lambda execution role’s trust policy includes lambda.amazonaws.com and synthetics.amazonaws.com as trusted service principals.

Canary Fails with “Cannot resolve hostname” or “ENOTFOUND”

Cause: The canary cannot reach the target URL due to DNS resolution failure or network connectivity issues.

Fix: If monitoring a private endpoint inside a VPC, verify the canary’s VPC configuration includes private subnets, correct security groups, and a NAT gateway for internet access. If the endpoint is public, verify the URL is correct and accessible from AWS Lambda’s execution environment. Test the URL with curl from an EC2 instance in the same region.

Canary Timeout or “Task timed out after X seconds”

Cause: The canary script takes longer to execute than the configured timeout.

Fix: Increase the timeout value under Additional configuration. For browser workflows with multiple page loads, set timeout to 90 or 120 seconds. Optimize your script by reducing wait times, disabling unnecessary resource loads, or simplifying navigation steps.

Canary Fails with “Access Denied” writing to S3

Cause: The S3 bucket policy or IAM role does not grant s3:PutObject permission to the canary’s execution role.

Fix: Add s3:PutObject permission to the IAM role for the S3 bucket prefix where canary artifacts are stored. If the bucket is encrypted with a customer managed KMS key, also grant kms:Decrypt and kms:GenerateDataKey permissions.

Canary Screenshots or HAR Files Missing from S3

Cause: The canary completed but artifacts were not uploaded due to S3 permissions, bucket policy, or script configuration.

Fix: Verify the IAM role has s3:PutObject permission. Check the canary script includes artifact capture (for custom scripts, use synthetics.takeScreenshot() or synthetics.getHAR() functions). Verify the S3 bucket exists in the same region as the canary.

Canary Metrics Not Appearing in CloudWatch

Cause: The canary execution role lacks cloudwatch:PutMetricData permission, or the canary has not completed its first successful run.

Fix: Add cloudwatch:PutMetricData permission to the IAM role. Wait for the canary to complete at least one run. Check the CloudWatch metric namespace CloudWatchSynthetics and dimension CanaryName.

Frequently Asked Questions

Disclaimer: The information in this article reflects the latest details available at the time of publication and may change as technologies and products evolve. Features, pricing, and plan limits can change over time. Always verify the latest information directly with the vendor before making purchasing or deployment decisions.