Package: aws-cdk.aws-synthetics
Amazon CloudWatch Synthetics Construct Library---AWS CDK v1 has reached End-of-Support on 2023-06-01.
This package is no longer being updated, and users should migrate to AWS CDK v2.For more information on how to migrate, see theMigrating to AWS CDK v2guide.Amazon CloudWatch Synthetics allow you to monitor your application by generatingsynthetictraffic. The traffic is produced by acanary: 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.CanaryTo 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 GalaxyThe below code defines a canary that will hit thebooks/topbookendpoint every 5 minutes:canary=synthetics.Canary(self,"MyCanary",schedule=synthetics.Schedule.rate(Duration.minutes(5)),test=synthetics.Test.custom(code=synthetics.Code.from_asset(path.join(__dirname,"canary")),handler="index.handler"),runtime=synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_1,environment_variables={"stage":"prod"})The following is an example of anindex.jsfile which exports thehandlerfunction:constsynthetics=require('Synthetics');constlog=require('SyntheticsLogger');constpageLoadBlueprint=asyncfunction(){// Configure the stage of the API using environment variablesconsturl=`https://api.example.com/${process.env.stage}/user/books/topbook/`;constpage=awaitsynthetics.getPage();constresponse=awaitpage.goto(url,{waitUntil:'domcontentloaded',timeout:30000});// Wait for page to render. Increase or decrease wait time based on endpoint being monitored.awaitpage.waitFor(15000);// This will take a screenshot that will be included in test output artifacts.awaitsynthetics.takeScreenshot('loaded','loaded');constpageTitle=awaitpage.title();log.info('Page title: '+pageTitle);if(response.status()!==200){throw'Failed to load page!';}};exports.handler=async()=>{returnawaitpageLoadBlueprint();};Note:The functionmustbe calledhandler.The canary will automatically produce a CloudWatch Dashboard:The Canary code will be executed in a lambda function created by Synthetics on your behalf. The Lambda function includes a customruntimeprovided by Synthetics. The provided runtime includes a variety of handy tools such asPuppeteer(for nodejs based one) and Chromium.To learn more about Synthetics capabilities, check out thedocs.Canary ScheduleYou can specify the schedule on which a canary runs by providing aScheduleobject to thescheduleproperty.Configure a run rate of up to 60 minutes withSchedule.rate:schedule=synthetics.Schedule.rate(Duration.minutes(5))You can also specify acron expressionwithSchedule.cron:schedule=synthetics.Schedule.cron(hour="0,8,16")If you want the canary to run just once upon deployment, you can useSchedule.once().Configuring the Canary ScriptTo configure the script the canary executes, use thetestproperty. Thetestproperty accepts aTestinstance that can be initialized by theTestclass static methods. Currently, the only implemented method isTest.custom(), which allows you to bring your own code. In the future, other methods will be added.Test.custom()acceptscodeandhandlerproperties -- both are required by Synthetics to create a lambda function on your behalf.Thesynthetics.Codeclass exposes static methods to bundle your code artifacts:code.fromInline(code)- specify an inline script.code.fromAsset(path)- specify a .zip file or a directory in the local filesystem which will be zipped and uploaded to S3 on deployment. See the above Note for directory structure.code.fromBucket(bucket, key[, objectVersion])- specify an S3 object that contains the .zip file of your runtime code. See the above Note for directory structure.Using theCodeclass static initializers:# To supply the code from a S3 bucket:importaws_cdk.aws_s3ass3# To supply the code inline:synthetics.Canary(self,"Inline Canary",test=synthetics.Test.custom(code=synthetics.Code.from_inline("/* Synthetics handler code */"),handler="index.handler"),runtime=synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_4)# To supply the code from your local filesystem:synthetics.Canary(self,"Asset Canary",test=synthetics.Test.custom(code=synthetics.Code.from_asset(path.join(__dirname,"canary")),handler="index.handler"),runtime=synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_4)bucket=s3.Bucket(self,"Code Bucket")synthetics.Canary(self,"Bucket Canary",test=synthetics.Test.custom(code=synthetics.Code.from_bucket(bucket,"canary.zip"),handler="index.handler"),runtime=synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_4)Note:Synthetics have a specified folder structure for canaries. For Node scripts supplied viacode.fromAsset()orcode.fromBucket(), the canary resource requires the following folder structure:canary/
├── nodejs/
   ├── node_modules/
        ├── <filename>.jsFor Python scripts supplied viacode.fromAsset()orcode.fromBucket(), the canary resource requires the following folder structure:canary/
├── python/
    ├── <filename>.pySee Syntheticsdocs.Running a canary on a VPCYou can specify whatVPC a canary executes in.
This can allow for monitoring services that may be internal to a specific VPC. To place a canary within a VPC, you can specify thevpcproperty with the desiredVPCto place then canary in.
This will automatically attach the appropriate IAM permissions to attach to the VPC. This will also create a Security Group and attach to the default subnets for the VPC unless specified viavpcSubnetsandsecurityGroups.importaws_cdk.aws_ec2asec2# vpc: ec2.IVpcsynthetics.Canary(self,"Vpc Canary",test=synthetics.Test.custom(code=synthetics.Code.from_asset(path.join(__dirname,"canary")),handler="index.handler"),runtime=synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_4,vpc=vpc)Note:By default, the Synthetics runtime needs access to the S3 and CloudWatch APIs, which will fail in a private subnet without internet access enabled (e.g. an isolated subnnet).Ensure that the Canary is placed in a VPC either with internet connectivity or with VPC Endpoints for S3 and CloudWatch enabled and configured.SeeSynthetics VPC docs.AlarmsYou can configure a CloudWatch Alarm on a canary metric. Metrics are emitted by CloudWatch automatically and can be accessed by the following APIs:canary.metricSuccessPercent()- percentage of successful canary runs over a given timecanary.metricDuration()- how much time each canary run takes, in seconds.canary.metricFailed()- number of failed canary runs over a given timeCreate an alarm that tracks the canary metric:importaws_cdk.aws_cloudwatchascloudwatch# canary: synthetics.Canarycloudwatch.Alarm(self,"CanaryAlarm",metric=canary.metric_success_percent(),evaluation_periods=2,threshold=90,comparison_operator=cloudwatch.ComparisonOperator.LESS_THAN_THRESHOLD)