# Using canary blueprints This section provides details about each of the canary blueprints and the tasks each blueprint is best suited for. Blueprints are provided for the following canary types: **Topics** + [Heartbeat monitoring](#CloudWatch_Synthetics_Canaries_Blueprints_Heartbeat) + [API canary](#CloudWatch_Synthetics_Canaries_Blueprints_API) + [Broken link checker](#CloudWatch_Synthetics_Canaries_Blueprints_Broken_Links) + [Visual monitoring blueprint](#CloudWatch_Synthetics_Canaries_Blueprints_VisualTesting) + [Canary recorder](#CloudWatch_Synthetics_Canaries_Blueprints_Recorder) + [GUI workflow builder](#CloudWatch_Synthetics_Canaries_Blueprints_GUI_Workflow) + [Multi checks blueprint](#CloudWatch_Synthetics_Canaries_Blueprints_Multichecks_Blueprint) + [Creating multi checks blueprint canary](CloudWatch_Synthetics_Canaries_MultiCheck_Blueprint.md) When you use a blueprint to create a canary, as you fill out the fields in the CloudWatch console, the **Script editor** area of the page displays the canary you are creating as a Node.js script. You can also edit your canary in this area to customize it further. ## Heartbeat monitoring Heartbeat scripts load the specified URL and store a screenshot of the page and an HTTP archive file (HAR file). They also store logs of accessed URLs. You can use the HAR files to view detailed performance data about the web pages. You can analyze the list of web requests and catch performance issues such as time to load for an item. If your canary uses the `syn-nodejs-puppeteer-3.1` or later runtime version, you can use the heartbeat monitoring blueprint to monitor multiple URLs and see the status, duration, associated screenshots, and failure reason for each URL in the step summary of the canary run report. ## API canary API canaries can test the basic Read and Write functions of a REST API. REST stands for *representational state transfer* and is a set of rules that developers follow when creating an API. One of these rules states that a link to a specific URL should return a piece of data. Canaries can work with any APIs and test all types of functionality. Each canary can make multiple API calls. In canaries that use runtime version `syn-nodejs-2.2` or later, the API canary blueprint supports multi-step canaries that monitor your APIs as HTTP steps. You can test multiple APIs in a single canary. Each step is a separate request that can access a different URL, use different headers, and use different rules for whether headers and response bodies are captured. By not capturing headers and response body, you can prevent sensitive data from being recorded. Each request in an API canary consists of the following information: + The *endpoint*, which is the URL that you request. + The *method*, which is the type of request that is sent to the server. REST APIs support GET (read), POST (write), PUT (update), PATCH (update), and DELETE (delete) operations. + The *headers*, which provide information to both the client and the server. They are used for authentication and providing information about the body content. For a list of valid headers, see [HTTP Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). + The *data* (or *body*), which contains information to be sent to the server. This is used only for POST, PUT, PATCH, or DELETE requests. **Note** API canary blueprints are not supported by Playwright runtimes. The API canary blueprint supports GET and POST methods. When you use this blueprint, you must specify headers. For example, you can specify **Authorization** as a **Key** and specify the necessary authorization data as the ** Value** for that key. If you are testing a POST request, you also specify the content to post in the ** Data** field. **Integration with API Gateway** The API blueprint is integrated with Amazon API Gateway. This enables you to select an API Gateway API and stage from the same AWS account and Region as the canary, or to upload a Swagger template from API Gateway for cross-account and cross-Region API monitoring. You can then choose the rest of the details in the console to create the canary, instead of entering them from scratch. For more information about API Gateway, see [What is Amazon API Gateway?](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) **Using a private API** You can create a canary that uses a private API in Amazon API Gateway. For more information, see [Creating a private API in Amazon API Gateway?](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html) ## Broken link checker The broken link checker collects all the links inside the URL that you are testing by using `document.getElementsByTagName('a')`. It tests only up to the number of links that you specify, and the URL itself is counted as the first link. For example, if you want to check all the links on a page that contains five links, you must specify for the canary to follow six links. Broken link checker canaries created using the `syn-nodejs-2.0-beta` runtime or later support the following additional features: + Provides a report that includes the links that were checked, status code, failure reason (if any), and source and destination page screenshots. + When viewing canary results, you can filter to see only the broken links and then fix the link based on the reason for failure. + This version captures annotated source page screenshots for each link and highlights the anchor where the link was found. Hidden components are not annotated. + You can configure this version to capture screenshots of both source and destination pages, just source pages, or just destination pages. + This version fixes an issue in the earlier version where the canary script stops after the first broken link even when more links are scraped from the first page. **Note** Broken link checker blueprints are not supported by Playwright runtimes. To update an existing canary using `syn-1.0` to use the new runtime, you must delete and re-create the canary. Updating an existing canary to the new runtime does not make these features available. A broken link checker canary detects the following types of link errors: + 404 Page Not Found + Invalid Host Name + Bad URL. For example, the URL is missing a bracket, has extra slashes, or uses the wrong protocol. + Invalid HTTP response code. + The host server returns empty responses with no content and no response code. + The HTTP requests constantly time out during the canary's run. + The host consistently drops connections because it is misconfigured or is too busy. ## Visual monitoring blueprint The visual monitoring blueprint includes code to compare screenshots taken during a canary run with screenshots taken during a baseline canary run. If the discrepancy between the two screenshots is beyond a threshold percentage, the canary fails. Visual monitoring is supported in canaries running **syn-puppeteer-node-3.2** and later. It is not currently supported in canaries running Python and Selenium, or using Playwright runtimes. The visual monitoring blueprint includes the following line of code in the default blueprint canary script, which enables visual monitoring. ``` syntheticsConfiguration.withVisualCompareWithBaseRun(true); ``` The first time that the canary runs successfully after this line is added to the script, it uses the screenshots taken during that run as the baseline for comparison. After that first canary run, you can use the CloudWatch console to edit the canary to do any of the following: + Set the next run of the canary as the new baseline. + Draw boundaries on the current baseline screenshot to designate areas of the screenshot to ignore during visual comparisons. + Remove a screenshot from being used for visual monitoring. For more information about using the CloudWatch console to edit a canary, see [Edit or delete a canary](synthetics_canaries_deletion.md). You can also change the canary run that is used as the baseline by using the ` nextrun` or `lastrun` parameters or specifing a canary run ID in the [UpdateCanary](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_UpdateCanary.html) API. When you use the visual monitoring blueprint, you enter the URL where you want the screenshot to be taken, and specify a difference threshold as a percentage. After the baseline run, future runs of the canary that detect a visual difference greater than that threshold trigger a canary failure. After the baseline run, you can also edit the canary to "draw" boundaries on the baseline screenshot that you want to ignore during the visual monitoring. The visual monitoring feature is powered by the the ImageMagick open source software toolkit. For more information, see [ ImageMagick ](https://imagemagick.org/index.php). ## Canary recorder With the canary recorder blueprint, you can use the CloudWatch Synthetics Recorder to record your click and type actions on a website and automatically generate a Node.js script that can be used to create a canary that follows the same steps. The CloudWatch Synthetics Recorder is a Google Chrome extension provided by Amazon. The canary recorder is not supported for canaries that use the Playwright runtime. **Credits**: The CloudWatch Synthetics Recorder is based on the [ Headless recorder ](https://github.com/checkly/headless-recorder). For more information, see [Using the CloudWatch Synthetics Recorder for Google Chrome](CloudWatch_Synthetics_Canaries_Recorder.md). ## GUI workflow builder The GUI Workflow Builder blueprint verifies that actions can be taken on your webpage. For example, if you have a webpage with a login form, the canary can populate the user and password fields and submit the form to verify that the webpage is working correctly. When you use a blueprint to create this type of canary, you specify the actions that you want the canary to take on the webpage. The actions that you can use are the following: + **Click**— Selects the element that you specify and simulates a user clicking or choosing the element. To specify the element in a Node.js script, use `[id=]` or ` a[class=]`. To specify the element in a Python script, use `xpath //*[@id=]` or ` //*[@class=]`. + **Verify selector**— Verifies that the specified element exists on the webpage. This test is useful for verifying that a previous action has causes the correct elements to populate the page. To specify the element to verify in a Node.js script, use `[id=]` or ` a[class=]`. To specify the element to verify in a Python script, use `xpath //*[@id=]` or `//*[class=]`. + **Verify text**— Verifies that the specified string is contained within the target element. This test is useful for verifying that a previous action has caused the correct text to be displayed. To specify the element in a Node.js script, use a format such as ` div[@id=]//h1` because this action uses the `waitForXPath` function in Puppeteer. To specify the element in a Python script, use xpath format such as ` //*[@id=] `or //\$1[@class=] because this action uses the `implicitly_wait` function in Selenium. + **Input text**— Writes the specified text in the target element. To specify the element to verify in a Node.js script, use `[id=]` or ` a[class=]`. To specify the element to verify in a Python script, use `xpath //*[@id=]` or `//*[@class=]`. + **Click with navigation**— Waits for the whole page to load after choosing the specified element. This is most useful when you need to reload the page. To specify the element in a Node.js script, use `[id=]` or ` a[class=]`. To specify the element in a Python script, use `xpath //*[@id=]` or ` //*[@class=]`. For example, the following blueprint uses Node.js. It clicks the **firstButton** on the specified URL, verifies that the expected selector with the expected text appears, inputs the name `Test_Customer` into the **Name** field, clicks the **Login** button, and then verifies that the login is successful by checking for the **Welcome** text on the next page. ![\[The create canary page in the console, with fields filled in for the GUI Workflow blueprint.\]](http://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/images/canary_create_gui_workflow.PNG) GUI workflow canaries that use the following runtimes also provide a summary of the steps executed for each canary run. You can use the screenshots and error message associated with each step to find the root cause of failure. + `syn-nodejs-2.0` or later + `syn-python-selenium-1.0` or later ## Multi checks blueprint The Multi check blueprint simplifies canary creation. It reduces costs by using a simple JSON configuration that provides out-of-the-box functionality for performing HTTP, DNS, SSL, and TCP checks. You can configure up to 10 checks. Configure each check as a numerical step that runs sequentially, allowing for clear understanding of the canary flow. Multi checks blueprints support: + Basic HTTP requests, TCP requests, validate DNS records and monitor SSL certificates + HTTP authentication methods such as Basic, API Key, OAuth, and Sigv4 integrated with Secrets Manager + Assertions for each check For more information, see [Creating a canary](CloudWatch_Synthetics_Canaries_Create.md). # Creating multi checks blueprint canary Amazon CloudWatch Synthetics multi checks blueprint helps you create a Synthetics canary by providing a simple JSON configuration. You can save costs by bundling up to 10 different types of HTTP/DNS/SSL/TCP checks in a step-based sequential manner. Each check includes assertions that provide basic verification against a check result. Multi checks canaries are designed for simple use cases that require only basic checks without a headless browser. For more complex use cases, review the other canary types that Amazon CloudWatch Synthetics provides. **Topics** + [Prerequisites](#CloudWatch_Synthetics_MultiCheck_Prerequisites) + [Limitations](#CloudWatch_Synthetics_MultiCheck_Limitations) + [Packaging structure, JSON schema, and configuration settings](#CloudWatch_Synthetics_MultiCheck_Packaging) + [Creating a multi check canary in AWS Management Console](#CloudWatch_Synthetics_MultiCheck_Console) + [Creating a multi check canary using AWS Synthetics APIs](#CloudWatch_Synthetics_MultiCheck_API) + [Creating a multi check canary in CloudFormation](#CloudWatch_Synthetics_MultiCheck_CloudFormation) + [Authentication configuration](#CloudWatch_Synthetics_MultiCheck_Authentication) + [Troubleshooting](#CloudWatch_Synthetics_MultiCheck_Troubleshooting) ## Prerequisites + Must be using syn-nodejs-3.0\$1 in order to create a multi check canary + When using Authentication and Secrets Manager configuration, you must ensure the canary [ ExecutionRoleArn](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_CreateCanary.html) allows for the permissions to access these secrets + When using Authentication for Sigv4, you must ensure the canary [ ExecutionRoleArn](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_CreateCanary.html) allows for the permissions to access the related role ## Limitations + HTTP Response sizes cannot be greater than 1 MB + Maximum of 10 defined variables. + When using the JSON RFC, the Checks JSON may have duplicate fields provided however only the last sequential field will be used + In the AWS Management Console, a multi check canary will default to showing multi check step metrics to readily identify the availability of each check. When checks are removed, this graph may still show the checks in the availability graph until the metric stops being active for at least 3 hours ## Packaging structure, JSON schema, and configuration settings The JSON Checks configuration that will be used for the canary must be named ` blueprint-config.json`. The configuration must follow the [ schema](https://github.com/aws-samples/synthetics-canary-local-debugging-sample/tree/main) and follow the instructions under [Writing a JSON configuration for Node.js multi Checks blueprint](CloudWatch_Synthetics_WritingCanary_Multichecks.md). Compress the `blueprint-config.json` into a ZIP file and provide it in one of the following creation workflows. When there is a `synthetics.json` configuration, then it is also compressed in the same ZIP file. The following is a zip file example called `multi-checks.zip`. ``` multi-checks.zip ├── blueprint-config.json └── synthetics.json ``` ## Creating a multi check canary in AWS Management Console 1. Open the Amazon CloudWatch synthetics console. 1. Choose **Create Canary**. 1. Under **Use a blueprint**, choose **multi checks** . Under **Configure Checks**, you will see two tabs, ** Checks** and **Canary configuration**. 1. Select the runtime version **syn-nodejs-3.0** or later. 1. Follow the procedure under [Writing a JSON configuration for Node.js multi Checks blueprint](CloudWatch_Synthetics_WritingCanary_Multichecks.md) to describe the check you want to perform. Alternatively, the console provides you a default JSON configuration that you can build on. 1. Choose **Create Canary**. ## Creating a multi check canary using AWS Synthetics APIs Use the `CreateCanary` API and within the `Code` parameter, provide the field/value `BlueprintTypes="multi-checks"` instead of ` Handler`. When both `BlueprintTypes` and `Handler` are specified, a `ValidationException` is displayed. The runtime version provided must be `syn-nodejs-3.0` or later. ``` aws synthetics create-canary \ --name my-multi-check-canary \ --code ZipFile="ZIP_BLOB",BlueprintTypes="multi-checks" \ --runtime-version syn-nodejs-3.0 \ ... // Or if you wanted to use S3 to provide your code. aws synthetics create-canary \ --name my-multi-check-canary \ --code S3Bucket="my-code-bucket",S3Key="my-zip-code-key",BlueprintTypes="multi-checks" \ ... ``` ## Creating a multi check canary in CloudFormation In your CloudFormation template for a multi check canary, within the `Code` parameter, provide the field/value `BlueprintTypes="multi-checks"` instead of ` Handler`. When both `BlueprintTypes` and `Handler` are specified, a `ValidationException` is displayed. The runtime version provided must be `syn-nodejs-3.0 or later`. An example template: ``` SyntheticsCanary: Type: 'AWS::Synthetics::Canary' Properties: Name: MyCanary RuntimeVersion: syn-nodejs-3.0 Schedule: {Expression: 'rate(5 minutes)', DurationInSeconds: 3600} ... Code: S3Bucket: "my-code-bucket" S3Key: "my-zip-code-key" BlueprintTypes: ["multi-checks"] ... ``` ## Authentication configuration When your canary makes HTTP requests to an authenticated endpoint, you can configure the steps of your blueprint canary to use one of four authentication types: Basic, API Key, OAuth Client Credentials, and SigV4. Rather than setting up request headers yourself, you can specify an authentication type in your blueprint definition, and Synthetics follows the specified authentication type to populate the components of your HTTP request with the authentication information provided. You specify an authentication type in your blueprint step with the Authentication section. You specify the authentication scheme you want to use, the properties required for your chosen authentication scheme, and Synthetics uses the information provided to construct an authentication header for your HTTP request. Since storing secrets (such as passwords or API keys) in plain text is a security concern, Synthetics supports integration with AWS Secrets Manager. When you want to authenticate an HTTP request in a Synthetics blueprint canary, you can refer to the secret storing your authentication information and Synthetics handles retrieving the secret and caching it in your canary. This approach provides secrets to Synthetics while keeping your secrets securely stored, without specifying them in plain text in your blueprint configuration. For more information about AWS Secrets Manager, see [What is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) ### Basic authentication Synthetics implements the Basic HTTP authentication scheme defined in RFC 7617. The process works as follows: + A username and password pair is provided from the blueprint configuration. + The user-pass is created by concatenating the username, a single colon (":") character, and the password. + The user-pass is UTF-8 encoded, then converted into a base64-encoded string. + This base64-encoded user-pass is provided in the "Authorization" header with the following format: Authorization: Basic \$1base64-encoded-user-pass\$1 For example, if the user agent wants to send the user-id "Aladdin" and password "open sesame", it uses the following header field: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== Example configuration: ``` "Authentication": { "type": "BASIC", "username": MY_USERNAME, // Required "password": MY_PASSWORD // Required } ``` ### API key authentication You can provide an API key for authenticating your HTTP requests. When you use API key authentication, your provided API key is put into the "X-API-Key" HTTP header. If you have a custom resource that looks for API key headers in a header besides this one, you can optionally specify a different header name to have Synthetics put the API key into. Example configuration: ``` "Authentication": { "type": "API_KEY", "apiKey": S0A1M2P3L4E5, // Required "header": X-Specific-Header // Optional, defaults to "X-API-Key" } ``` ### SigV4 authentication AWS SigV4 (Signature Version 4) is the AWS signing protocol for adding authentication information to AWS API requests. To make a SigV4-authenticated request, you need to specify the region and service you are making requests to, as well as an ARN (AWS Resource Name) identifying an IAM role you want the canary to assume when making this SigV4 request. Synthetics assumes the IAM role provided in the roleArn, and uses it to authenticate your AWS API request. Example configuration: ``` "Authentication": { "type": "SIGV4", "region": us-west-2, // Required "service": s3, // Required "roleArn": arn:AWS:iam:12345678912:role/SampleRole // Required } ``` #### SigV4 considerations For Synthetics to assume the role that you provided in the SigV4 authentication section, the trust policy attached to that role must be configured to allow the canary to assume the provided roleArn. The AWS principal you need to trust is the role that your canary assumed through AWS STS. It takes the format ` aws:sts::{account_running_the_canary}:assumed-role//` arn:. For example, if you have a canary running in account 0123456789012, named test-canary, and the role it assumed was named canary-assume-role, then the trust policy needs to include this statement for the canary to assume the roleArn for SigV4 authentication correctly: ``` { "Effect": "Allow", "Principal": { "AWS": "arn:AWS:sts::123456789012:assumed-role/test-canary/" }, "Action": "sts:AssumeRole" } ``` ### OAuth client credentials Synthetics implements the OAuth Client Credentials grant type as defined in RFC 6479 Section 4.4. If you want to make an HTTP request to an endpoint authenticated with a Bearer Token issued by an OAuth token endpoint, Synthetics can request and manage a bearer token on your behalf. When you use the OAuth scheme, Synthetics performs the following steps: + Uses the Basic authentication scheme with the clientId and clientSecret to authenticate a request to the tokenUrl, the endpoint that issues bearer tokens + If you provide the optional scope, audience, and resource parameters, they are included in the token request + Uses the access token returned by the tokenUrl to authenticate your HTTP request + Securely stores the refresh token returned from the tokenUrl for future token requests Example configuration: ``` "Authentication": { "type": "OAUTH_CLIENT_CREDENTIALS", "tokenUrl": ..., // Required "clientId": ..., // Required "clientSecret": ..., // Required "scope": ..., // Optional "audience": ..., // Optional "resource": ..., // Optional } ``` #### OAuth considerations Synthetics refreshes OAuth tokens when a 401 or 407 response is returned. ### AWS Secrets Manager integration To avoid storing secret values (such as passwords or API keys) in plain text, Synthetics provides an integration with AWS Secrets Manager. You can reference an entire secret value in your blueprint configuration with the format ` ${aws_SECRET:}`, or to reference a particular key ` ${aws_SECRET::}`. For example, if you have a secret named login/basic-auth-credentials, storing a username and password with the following JSON structure: ``` { "username": "Aladdin", "password": "open sesame" } ``` You can reference the username and password in your blueprint configuration as follows, and Synthetics handles retrieving the secret value and using its keys to authenticate your request: ``` "Authentication": { "type": "BASIC", "username": ${AWS_SECRET:login/basic-auth-credentials:username}, "password": ${AWS_SECRET:login/basic-auth-credentials:password} } ``` To allow Synthetics to retrieve the specified secret, the role ARN assumed by the canary needs to have secretsManager:GetSecretValue permissions. If the secret is encrypted using a customer-managed key instead of the AWS managed key AWS/secretsmanager, then you also need kms:Decrypt permissions for that key. Example permissions: ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "secretsmanager:GetSecretValue", "Resource": "arn:AWS:secretsmanager:us-east-1:123456789012:secret:secretName-AbCdEf" }, { "Effect": "Allow", "Action": "kms:Decrypt", "Resource": "arn:AWS:kms:us-east-1:123456789012:key/key-id" } ] } ``` ## Troubleshooting ### Common troubleshooting failures The underlying code for multi check blueprint is written in Typescript. See the canary troubleshooting page for common failures: [Troubleshooting a failed canary](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Troubleshoot.html). ### JSON check configuration syntax errors When there are any syntactic errors related to the canary's JSON check configuration, the AWS Management Console will provide you a failure reason when you attempt to create the canary. If you are creating a canary using an API or CloudFormation, you will see the failure when the canary is executed for the first time. It is recommended to use the safe canary updates workflow for multi check canary. For more information, see [Performing safe canary updates ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/performing-safe-canary-upgrades.html). ### Networking or timeout failures For any intermittent or consistent failures related to timeouts, network connection failures (for example, ENOTFOUND, ECONNRESET) consider turning on ` DEBUG` logs such that the following run will provide more additional details on why the Checks are failing. To do so, provide the Environment Variable CW\$1SYNTHETICS\$1LOG\$1LEVEL: "DEBUG". If there are still failures that you are unable to debug, consider reaching out to AWS Support or checking if any of the other provided Canary types from CloudWatch Synthetics more closely matches your use-case.