Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using dependencies with CloudWatch Synthetics canaries

This section explains how to use Dependencies in CloudWatch Synthetics canaries. The Dependencies field allows you to specify dependencies for your canaries, enabling you to include additional libraries or custom code that your canary scripts can use.

Overview

CloudWatch Synthetics canaries support specifying Lambda layers as dependencies. This feature allows you to:

Supported APIs

The Dependencies field is supported in the following APIs:

Syntax

The Dependencies field is part of the code structure in the request syntax:

"Code": { 
  "Handler": "string",
  "S3Bucket": "string",
  "S3Key": "string",
  "S3Version": "string",
  "ZipFile": blob,
  "Dependencies": [
    {
      "Type": "LambdaLayer",
      "Reference": "string"
    }
  ]
}

Using dependencies

Here are some examples and instructions for using the Dependencies field in different scenarios.

Creating a Canary with dependencies

When creating a canary, you can specify a Lambda layer as a dependency:

{
  "Name": "my-canary",
  "Code": {
    "Handler": "pageLoadBlueprint.handler",
    "S3Bucket": "my-bucket",
    "S3Key": "my-canary-script.zip",
    "Dependencies": [
      {
        "Type": "LambdaLayer",
        "Reference": "arn:aws:lambda:us-west-2:123456789012:layer:my-custom-layer:1"
      }
    ]
  },
  "ArtifactS3Location": "s3://my-bucket/artifacts/",
  "ExecutionRoleArn": "arn:aws:iam::123456789012:role/my-canary-role",
  "Schedule": {
    "Expression": "rate(5 minutes)"
  },
  "RuntimeVersion": "syn-nodejs-puppeteer-3.9"
}

Updating a Canary's dependencies

You can update a canary's dependencies using the UpdateCanary API:

{
  "Name": "my-canary",
  "Code": {
    "Dependencies": [
      {
        "Type": "LambdaLayer",
        "Reference": "arn:aws:lambda:us-west-2:123456789012:layer:my-updated-layer:2"
      }
    ]
  }
}

Removing dependencies

To remove dependencies from a canary, provide an empty array for the Dependencies field:

{
  "Name": "my-canary",
  "Code": {
    "Dependencies": []
  }
}

Testing dependencies with StartCanaryDryRun

Before updating a canary with new dependencies, you can test them using the StartCanaryDryRun API:

{
  "Name": "my-canary",
  "Code": {
    "Dependencies": [
      {
        "Type": "LambdaLayer",
        "Reference": "arn:aws:lambda:us-west-2:123456789012:layer:my-test-layer:3"
      }
    ]
  }
}

Limitations and considerations

Creating compatible Lambda layers

For information on how to create and package layers, see Managing Lambda dependencies with layers and to understand the packaging structure of a canary check based on the canary packing structure, see Writing a canary script.