Package: aws-cdk.aws-synthetics-alpha
Amazon CloudWatch Synthetics Construct Library---This API may emit warnings. Backward compatibility is not guaranteed.All constructs moved to aws-cdk-lib/aws-synthetics.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_4_0,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().Deleting underlying resources on canary deletionWhen you delete a lambda, the following underlying resources are isolated in your AWS account:Lambda Function that runs your canary scriptS3 Bucket for artifact storageIAM roles and policiesLog Groups in CloudWatch Logs.To learn more about these underlying resources, seeSynthetics Canaries Deletion.In the CDK, you can configure your canary to delete the underlying lambda function when the canary is deleted.
This can be provisioned by settingcleanup: Cleanup.LAMBDA. Note that this
will create a custom resource under the hood that takes care of the lambda deletion for you.canary=synthetics.Canary(self,"Canary",test=synthetics.Test.custom(handler="index.handler",code=synthetics.Code.from_inline("/* Synthetics handler code")),cleanup=synthetics.Cleanup.LAMBDA,runtime=synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_4_0)Note: To properly clean up your canary on deletion, you still have to manually delete other resources
like S3 buckets and CloudWatch logs.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_4_0)# 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_4_0)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_4_0)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_4_0,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)ArtifactsYou can pass an S3 bucket to store artifacts from canary runs. If you do not,
one will be auto-generated when the canary is created. You may addlifecycle rulesto the auto-generated bucket.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_4_0,artifacts_bucket_lifecycle_rules=[LifecycleRule(expiration=Duration.days(30))])