# Amazon CloudWatch Synthetics Construct Library
<!--BEGIN STABILITY BANNER-->---
> 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 the [*Migrating to AWS CDK v2* guide](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html).
---
<!--END STABILITY BANNER-->
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:
```console
% 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:
```python
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 an `index.js` file which exports the `handler` function:
```js
const synthetics = require('Synthetics');
const log = require('SyntheticsLogger');
const pageLoadBlueprint = async function () {
// Configure the stage of the API using environment variables
const url = `https://api.example.com/${process.env.stage}/user/books/topbook/`;
const 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');
const 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:
The Canary code will be executed in a lambda function created by Synthetics on your behalf. The Lambda function includes a custom [runtime](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library.html) provided by Synthetics. The provided runtime includes a variety of handy tools such as [Puppeteer](https://www.npmjs.com/package/puppeteer-core) (for nodejs based one) and Chromium.
To learn more about Synthetics capabilities, check out the [docs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries.html).
### Canary Schedule
You can specify the schedule on which a canary runs by providing a
[`Schedule`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-synthetics.Schedule.html)
object to the `schedule` property.
Configure a run rate of up to 60 minutes with `Schedule.rate`:
```python
schedule = synthetics.Schedule.rate(Duration.minutes(5))
```
You can also specify a [cron expression](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_cron.html) with `Schedule.cron`:
```python
schedule = synthetics.Schedule.cron(
hour="0,8,16"
)
```
If you want the canary to run just once upon deployment, you can use `Schedule.once()`.
### 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:
* `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 the `Code` class static initializers:
```python
# To supply the code from a S3 bucket:
import aws_cdk.aws_s3 as s3
# 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 via `code.fromAsset()` or `code.fromBucket()`, the canary resource requires the following folder structure:
>
> ```plaintext
> canary/
> ├── nodejs/
> ├── node_modules/
> ├── <filename>.js
> ```
>
> For Python scripts supplied via `code.fromAsset()` or `code.fromBucket()`, the canary resource requires the following folder structure:
>
> ```plaintext
> canary/
> ├── python/
> ├── <filename>.py
> ```
>
> See Synthetics [docs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_WritingCanary.html).
### Running a canary on a VPC
You can specify what [VPC a canary executes in](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_VPC.html).
This can allow for monitoring services that may be internal to a specific VPC. To place a canary within a VPC, you can specify the `vpc` property with the desired `VPC` to 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 via `vpcSubnets` and `securityGroups`.
```python
import aws_cdk.aws_ec2 as ec2
# vpc: ec2.IVpc
synthetics.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.
>
> See [Synthetics VPC docs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_VPC.html).
### 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:
* `canary.metricSuccessPercent()` - percentage of successful canary runs over a given time
* `canary.metricDuration()` - how much time each canary run takes, in seconds.
* `canary.metricFailed()` - number of failed canary runs over a given time
Create an alarm that tracks the canary metric:
```python
import aws_cdk.aws_cloudwatch as cloudwatch
# canary: synthetics.Canary
cloudwatch.Alarm(self, "CanaryAlarm",
metric=canary.metric_success_percent(),
evaluation_periods=2,
threshold=90,
comparison_operator=cloudwatch.ComparisonOperator.LESS_THAN_THRESHOLD
)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/aws-cdk",
"name": "aws-cdk.aws-synthetics",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Amazon Web Services",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/08/1a/8f98dccf1a48b95f420d56c78407b716729ef445aad99c0d6424a5be8811/aws-cdk.aws-synthetics-1.204.0.tar.gz",
"platform": null,
"description": "# Amazon CloudWatch Synthetics Construct Library\n\n<!--BEGIN STABILITY BANNER-->---\n\n\n\n\n> AWS CDK v1 has reached End-of-Support on 2023-06-01.\n> This package is no longer being updated, and users should migrate to AWS CDK v2.\n>\n> For more information on how to migrate, see the [*Migrating to AWS CDK v2* guide](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html).\n\n---\n<!--END STABILITY BANNER-->\n\nAmazon 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.\n\n## Canary\n\nTo illustrate how to use a canary, assume your application defines the following endpoint:\n\n```console\n% curl \"https://api.example.com/user/books/topbook/\"\nThe Hitchhikers Guide to the Galaxy\n\n```\n\nThe below code defines a canary that will hit the `books/topbook` endpoint every 5 minutes:\n\n```python\ncanary = synthetics.Canary(self, \"MyCanary\",\n schedule=synthetics.Schedule.rate(Duration.minutes(5)),\n test=synthetics.Test.custom(\n code=synthetics.Code.from_asset(path.join(__dirname, \"canary\")),\n handler=\"index.handler\"\n ),\n runtime=synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_1,\n environment_variables={\n \"stage\": \"prod\"\n }\n)\n```\n\nThe following is an example of an `index.js` file which exports the `handler` function:\n\n```js\nconst synthetics = require('Synthetics');\nconst log = require('SyntheticsLogger');\n\nconst pageLoadBlueprint = async function () {\n // Configure the stage of the API using environment variables\n const url = `https://api.example.com/${process.env.stage}/user/books/topbook/`;\n\n const page = await synthetics.getPage();\n const response = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });\n // Wait for page to render. Increase or decrease wait time based on endpoint being monitored.\n await page.waitFor(15000);\n // This will take a screenshot that will be included in test output artifacts.\n await synthetics.takeScreenshot('loaded', 'loaded');\n const pageTitle = await page.title();\n log.info('Page title: ' + pageTitle);\n if (response.status() !== 200) {\n throw 'Failed to load page!';\n }\n};\n\nexports.handler = async () => {\n return await pageLoadBlueprint();\n};\n```\n\n> **Note:** The function **must** be called `handler`.\n\nThe canary will automatically produce a CloudWatch Dashboard:\n\n\n\nThe Canary code will be executed in a lambda function created by Synthetics on your behalf. The Lambda function includes a custom [runtime](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library.html) provided by Synthetics. The provided runtime includes a variety of handy tools such as [Puppeteer](https://www.npmjs.com/package/puppeteer-core) (for nodejs based one) and Chromium.\n\nTo learn more about Synthetics capabilities, check out the [docs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries.html).\n\n### Canary Schedule\n\nYou can specify the schedule on which a canary runs by providing a\n[`Schedule`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-synthetics.Schedule.html)\nobject to the `schedule` property.\n\nConfigure a run rate of up to 60 minutes with `Schedule.rate`:\n\n```python\nschedule = synthetics.Schedule.rate(Duration.minutes(5))\n```\n\nYou can also specify a [cron expression](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_cron.html) with `Schedule.cron`:\n\n```python\nschedule = synthetics.Schedule.cron(\n hour=\"0,8,16\"\n)\n```\n\nIf you want the canary to run just once upon deployment, you can use `Schedule.once()`.\n\n### Configuring the Canary Script\n\nTo 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.\n\nThe `synthetics.Code` class exposes static methods to bundle your code artifacts:\n\n* `code.fromInline(code)` - specify an inline script.\n* `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.\n* `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.\n\nUsing the `Code` class static initializers:\n\n```python\n# To supply the code from a S3 bucket:\nimport aws_cdk.aws_s3 as s3\n# To supply the code inline:\nsynthetics.Canary(self, \"Inline Canary\",\n test=synthetics.Test.custom(\n code=synthetics.Code.from_inline(\"/* Synthetics handler code */\"),\n handler=\"index.handler\"\n ),\n runtime=synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_4\n)\n\n# To supply the code from your local filesystem:\nsynthetics.Canary(self, \"Asset Canary\",\n test=synthetics.Test.custom(\n code=synthetics.Code.from_asset(path.join(__dirname, \"canary\")),\n handler=\"index.handler\"\n ),\n runtime=synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_4\n)\nbucket = s3.Bucket(self, \"Code Bucket\")\nsynthetics.Canary(self, \"Bucket Canary\",\n test=synthetics.Test.custom(\n code=synthetics.Code.from_bucket(bucket, \"canary.zip\"),\n handler=\"index.handler\"\n ),\n runtime=synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_4\n)\n```\n\n> **Note:** Synthetics have a specified folder structure for canaries. For Node scripts supplied via `code.fromAsset()` or `code.fromBucket()`, the canary resource requires the following folder structure:\n>\n> ```plaintext\n> canary/\n> \u251c\u2500\u2500 nodejs/\n> \u251c\u2500\u2500 node_modules/\n> \u251c\u2500\u2500 <filename>.js\n> ```\n>\n> For Python scripts supplied via `code.fromAsset()` or `code.fromBucket()`, the canary resource requires the following folder structure:\n>\n> ```plaintext\n> canary/\n> \u251c\u2500\u2500 python/\n> \u251c\u2500\u2500 <filename>.py\n> ```\n>\n> See Synthetics [docs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_WritingCanary.html).\n\n### Running a canary on a VPC\n\nYou can specify what [VPC a canary executes in](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_VPC.html).\nThis can allow for monitoring services that may be internal to a specific VPC. To place a canary within a VPC, you can specify the `vpc` property with the desired `VPC` to place then canary in.\nThis 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 via `vpcSubnets` and `securityGroups`.\n\n```python\nimport aws_cdk.aws_ec2 as ec2\n\n# vpc: ec2.IVpc\n\nsynthetics.Canary(self, \"Vpc Canary\",\n test=synthetics.Test.custom(\n code=synthetics.Code.from_asset(path.join(__dirname, \"canary\")),\n handler=\"index.handler\"\n ),\n runtime=synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_4,\n vpc=vpc\n)\n```\n\n> **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).\n>\n> Ensure that the Canary is placed in a VPC either with internet connectivity or with VPC Endpoints for S3 and CloudWatch enabled and configured.\n>\n> See [Synthetics VPC docs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_VPC.html).\n\n### Alarms\n\nYou can configure a CloudWatch Alarm on a canary metric. Metrics are emitted by CloudWatch automatically and can be accessed by the following APIs:\n\n* `canary.metricSuccessPercent()` - percentage of successful canary runs over a given time\n* `canary.metricDuration()` - how much time each canary run takes, in seconds.\n* `canary.metricFailed()` - number of failed canary runs over a given time\n\nCreate an alarm that tracks the canary metric:\n\n```python\nimport aws_cdk.aws_cloudwatch as cloudwatch\n\n# canary: synthetics.Canary\n\ncloudwatch.Alarm(self, \"CanaryAlarm\",\n metric=canary.metric_success_percent(),\n evaluation_periods=2,\n threshold=90,\n comparison_operator=cloudwatch.ComparisonOperator.LESS_THAN_THRESHOLD\n)\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "The CDK Construct Library for AWS::Synthetics",
"version": "1.204.0",
"project_urls": {
"Homepage": "https://github.com/aws/aws-cdk",
"Source": "https://github.com/aws/aws-cdk.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0304dd31480ed6c1446361b2764999cdb2882963f85a3b2aca36f9505d679e23",
"md5": "d5b13530246eef7cfa2b32e8599fd802",
"sha256": "177bd9d624f1b91dabfbc85c0e79ebc8b428552c4c0aa591cf27619654a1d3c1"
},
"downloads": -1,
"filename": "aws_cdk.aws_synthetics-1.204.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d5b13530246eef7cfa2b32e8599fd802",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.7",
"size": 205982,
"upload_time": "2023-06-19T21:01:46",
"upload_time_iso_8601": "2023-06-19T21:01:46.598963Z",
"url": "https://files.pythonhosted.org/packages/03/04/dd31480ed6c1446361b2764999cdb2882963f85a3b2aca36f9505d679e23/aws_cdk.aws_synthetics-1.204.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "081a8f98dccf1a48b95f420d56c78407b716729ef445aad99c0d6424a5be8811",
"md5": "b8ef8fb41b0fc17b574d3d9b38de7ce7",
"sha256": "9f6aea4a5d600178e5bc0e7d636bb1d5eb41ba0f7996109a6cb9e3e21442e288"
},
"downloads": -1,
"filename": "aws-cdk.aws-synthetics-1.204.0.tar.gz",
"has_sig": false,
"md5_digest": "b8ef8fb41b0fc17b574d3d9b38de7ce7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.7",
"size": 207300,
"upload_time": "2023-06-19T21:07:52",
"upload_time_iso_8601": "2023-06-19T21:07:52.886120Z",
"url": "https://files.pythonhosted.org/packages/08/1a/8f98dccf1a48b95f420d56c78407b716729ef445aad99c0d6424a5be8811/aws-cdk.aws-synthetics-1.204.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-19 21:07:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws",
"github_project": "aws-cdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aws-cdk.aws-synthetics"
}
JSON
