Skip navigation links

Package software.amazon.awscdk.services.synthetics

Amazon CloudWatch Synthetics Construct Library

See: Description

Package software.amazon.awscdk.services.synthetics Description

Amazon CloudWatch Synthetics Construct Library

---

cfn-resources: Stable

All classes with the Cfn prefix in this module (CFN Resources) are always stable and safe to use.

cdk-constructs: Developer Preview

The APIs of higher level constructs in this module are in developer preview before they become stable. We will only make breaking changes to address unforeseen API issues. Therefore, these APIs are not subject to Semantic Versioning, and breaking changes will be announced in release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.

Amazon CloudWatch Synthetics allow you to monitor your application by generating synthetic traffic. The traffic is produced by a canary: a configurable script that runs on a schedule. You configure the canary script to follow the same routes and perform the same actions as a user, which allows you to continually verify your user experience even when you don't have any traffic on your applications.

Canary

To illustrate how to use a canary, assume your application defines the following endpoint: 

 % curl "https://api.example.com/user/books/topbook/"
 The Hitchhikers Guide to the Galaxy

The below code defines a canary that will hit the books/topbook endpoint every 5 minutes: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 import software.amazon.awscdk.services.synthetics.*;
 
 Canary canary = new Canary(this, "MyCanary", new CanaryProps()
         .schedule(synthetics.Schedule.rate(Duration.minutes(5)))
         .test(Test.custom(Map.of(
                 "code", synthetics.Code.fromAsset(path.join(__dirname, "canary")),
                 "handler", "index.handler")))
         .runtime(synthetics.Runtime.getSYNTHETICS_NODEJS_PUPPETEER_3_0()));

The following is an example of an index.js file which exports the handler function: 

 var synthetics = require('Synthetics');
 const log = require('SyntheticsLogger');
 
 const pageLoadBlueprint = async function () {
 
     // INSERT URL here
     const URL = "https://api.example.com/user/books/topbook/";
 
     let page = await synthetics.getPage();
     const response = await page.goto(URL, {waitUntil: 'domcontentloaded', timeout: 30000});
     //Wait for page to render.
     //Increase or decrease wait time based on endpoint being monitored.
     await page.waitFor(15000);
     // This will take a screenshot that will be included in test output artifacts
     await synthetics.takeScreenshot('loaded', 'loaded');
     let pageTitle = await page.title();
     log.info('Page title: ' + pageTitle);
     if (response.status() !== 200) {
         throw "Failed to load page!";
     }
 };
 
 exports.handler = async () => {
     return await pageLoadBlueprint();
 };

Note: The function must be called handler.

The canary will automatically produce a CloudWatch Dashboard:

UI Screenshot

The Canary code will be executed in a lambda function created by Synthetics on your behalf. The Lambda function includes a custom runtime provided by Synthetics. The provided runtime includes a variety of handy tools such as Puppeteer (for nodejs based one) and Chromium.

To learn more about Synthetics capabilities, check out the docs.

Configuring the Canary Script

To configure the script the canary executes, use the test property. The test property accepts a Test instance that can be initialized by the Test class static methods. Currently, the only implemented method is Test.custom(), which allows you to bring your own code. In the future, other methods will be added. Test.custom() accepts code and handler properties -- both are required by Synthetics to create a lambda function on your behalf.

The synthetics.Code class exposes static methods to bundle your code artifacts:

Using the Code class static initializers: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 // To supply the code inline:
 Object canary = Canary.Builder.create(this, "MyCanary")
         .test(Test.custom(Map.of(
                 "code", synthetics.Code.fromInline("/* Synthetics handler code * /"),
                 "handler", "index.handler")))
         .runtime(synthetics.Runtime.getSYNTHETICS_NODEJS_PUPPETEER_3_0())
         .build();
 
 // To supply the code from your local filesystem:
 Object canary = Canary.Builder.create(this, "MyCanary")
         .test(Test.custom(Map.of(
                 "code", synthetics.Code.fromAsset(path.join(__dirname, "canary")),
                 "handler", "index.handler")))
         .runtime(synthetics.Runtime.getSYNTHETICS_NODEJS_PUPPETEER_3_0())
         .build();
 
 // To supply the code from a S3 bucket:
 Object canary = Canary.Builder.create(this, "MyCanary")
         .test(Test.custom(Map.of(
                 "code", synthetics.Code.fromBucket(bucket, "canary.zip"),
                 "handler", "index.handler")))
         .runtime(synthetics.Runtime.getSYNTHETICS_NODEJS_PUPPETEER_3_0())
         .build();

Note: For code.fromAsset() and code.fromBucket(), the canary resource requires the following folder structure: 

 canary/
 ├── nodejs/
    ├── node_modules/
         ├── <filename>.js

See Synthetics docs.

Alarms

You can configure a CloudWatch Alarm on a canary metric. Metrics are emitted by CloudWatch automatically and can be accessed by the following APIs:

Create an alarm that tracks the canary metric: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Alarm.Builder.create(this, "CanaryAlarm")
         .metric(canary.metricSuccessPercent())
         .evaluationPeriods(2)
         .threshold(90)
         .comparisonOperator(cloudwatch.ComparisonOperator.getLESS_THAN_THRESHOLD())
         .build();

Future Work

Skip navigation links

Copyright © 2021. All rights reserved.