How do I troubleshoot common issues in Amazon CloudWatch Synthetics canary?

Short description

Common issues that you might encounter in CloudWatch Synthetics canary are:

• Roles and permissions issues
• Amazon Simple Storage Service (Amazon S3) issues
• AWS Lambda issues
• Amazon Virtual Private Cloud (Amazon VPC) issues

Best practices for troubleshooting issues in CloudWatch Synthetics canary are:

• Check the Availability tab to identify an issue for a specific failed or passed run.
• Check the error message on the Details page to see why a canary is failing.
• Check the screenshots to verify the latest canary invocations.
• Check the log file to identify permission issues or throttling exceptions.
• Check the Monitoring tab for Canary metrics and Lambda metrics.
• Check the CloudWatch Logs log groups with the name /aws/lambda/cwsyn-MyCanaryName-randomId for recent canary operation logs.
• Check the Amazon S3 bucket with the name cw-syn-results-accountID-region for artifact uploads such as screenshots or HAR files.
• Check the CloudWatch metrics published by canaries.

Resolution

To troubleshoot common issues in CloudWatch Synthetics canary, take the following actions:

Roles and permissions issues

If you create and manage canaries, then you must have specific permissions. Also, the canaries that are created must have specific permissions. For more information, see Required roles and permissions for users who manage CloudWatch canaries and Required roles and permissions for canaries. If you want to limit a user's permissions, see Limiting a user to viewing specific canaries.

Amazon S3 bucket issues

Common errors that you might encounter in CloudWatch Synthetics canary that are related to Amazon S3 bucket issues are:

• The specified bucket does not exist.
• Unable to upload artifacts to S3, Exception: Unable to fetch S3 bucket location: Access Denied.
• This Canary is currently in the error state. Error message: 1 validation error detected: Value 'XXXXX' at 'content.s3Bucket' failed to satisfy constraint: Member must satisfy regular expression pattern: ^[0-9A-Za-z\.\-_]*(?<!\.)$

The specified bucket does not exist

This error indicates that the Amazon S3 bucket is deleted and CloudWatch Synthetics canary can't find it. To prevent this error in the future, create a lifecycle on the Amazon S3 bucket to store your CloudWatch Synthetics canary artifacts. For more information, see Managing your storage lifecycle.

Unable to upload artifacts to S3, Exception: Unable to fetch S3 bucket location: Access Denied

To troubleshoot this error, check the following:

• Check that the canary's AWS Identity and Access Management (IAM) role has the correct Amazon S3 bucket permissions. Make sure that your organization doesn't limit any permissions related to the Amazon S3 bucket. For more information, see Service control policies (SCPs).
• Check that the canary uses a standard AWS managed key and not an AWS Key Management Service (AWS KMS) customer managed key for encryption. If the canary uses an AWS KMS customer managed key, then the canary's IAM role might not have the permission to encrypt or decrypt. For more information, see Encrypting canary artifacts.
• Check that your canary and bucket policy encryption mode are the same. If they aren't the same, then your bucket policy doesn't allow the encryption mechanism that the canary uses.
• Check if the canary performs visual monitoring. For more information, see Updating artifact location and encryption when using visual monitoring.

This Canary is currently in the error state. Error message: 1 validation error detected: Value 'XXXXX' at 'content.s3Bucket' failed to satisfy constraint: Member must satisfy regular expression pattern: ^[0-9A-Za-z\.\-_]*(?<!\.)$

To resolve this error, check if your canary script is located in Amazon S3. If the script is located in Amazon S3, then specify the bucket name in your script code. Make sure that you don't include s3:// at the start of the bucket name.

AWS Lambda issues

Common errors that you might encounter in CloudWatch Synthetics canary that are related to AWS Lambda are:

• The canary can't detect the latest Lambda layer.
• The IAM role attached to the canary doesn't have a trust relationship for the Lambda service.

The canary can't detect the latest Lambda layer

The canary might detect the latest Lambda layer if manual changes are made or if the Lambda function is deleted. To resolve this issue, create a new canary.

The IAM role attached to the canary doesn't have a trust relationship for the Lambda service

If your canary IAM role doesn't have a trust relationship for the Lambda service, then make sure the IAM role contains the following statement:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "lambda.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Amazon VPC issues

To troubleshoot Amazon VPC issues, see How can I resolve the errors that I received for the failing CloudWatch canary I created in my VPC?

Related information

Why did my CloudWatch canary stop running?

How do I monitor the performance of my website using CloudWatch Synthetics?