canaries

Creates, updates, deletes, gets or lists a canaries resource.

Overview

Name	`canaries`
Type	Resource
Id	`aws.synthetics.canaries`

Fields

The following fields are returned by SELECT queries:

get_canary
describe_canaries

Name	Datatype	Description
`artifact_config`	`object`	A structure that contains the configuration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3.
`artifact_s3_location`	`string`	The location in Amazon S3 where Synthetics stores artifacts from the runs of this canary. Artifacts include the log file, screenshots, and HAR files.
`browser_configs`	`array`	A structure that specifies the browser type to use for a canary run. CloudWatch Synthetics supports running canaries on both CHROME and FIREFOX browsers. If not specified, browserConfigs defaults to Chrome.
`code`	`object`	This structure contains information about the canary's Lambda handler and where its code is stored by CloudWatch Synthetics.
`dry_run_config`	`object`	Returns the dry run configurations for a canary.
`engine_arn`	`string`	The ARN of the Lambda function that is used as your canary's engine. For more information about Lambda ARN format, see Resources and Conditions for Lambda Actions. (pattern: <code>arn:(aws[a-zA-Z-])?:lambda:[a-z]{2,4}(-[a-z]{2,4})?-[a-z]+-\d{1}:\d{12}:function:[a-zA-Z0-9-]+(:($LATEST\|[a-zA-Z0-9-*]+))?</code>)
`engine_configs`	`array`	A list of engine configurations for the canary, one for each browser type that the canary is configured to run on. All runtime versions syn-nodejs-puppeteer-11.0 and above, and syn-nodejs-playwright-3.0 and above, use engineConfigs only. You can no longer use engineArn in these versions. Runtime versions older than syn-nodejs-puppeteer-11.0 and syn-nodejs-playwright-3.0 continue to support engineArn to ensure backward compatibility.
`execution_role_arn`	`string`	The ARN of the IAM role used to run the canary. This role must include lambda.amazonaws.com as a principal in the trust policy. (pattern: <code>arn:(aws[a-zA-Z-]*)?:iam::\d{12}:role/?[a-zA-Z_0-9+=,.@-_/]+</code>)
`failure_retention_period_in_days`	`integer`	The number of days to retain data about failed runs of this canary. This setting affects the range of information returned by GetCanaryRuns, as well as the range of information displayed in the Synthetics console.
`id`	`string`	The unique ID of this canary. (pattern: <code>^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$</code>)
`kms_key_arn`	`string`	The Amazon Resource Name (ARN) of the customer-managed AWS Key Management Service (AWS KMS) key used to encrypt the canary's AWS Lambda function environment variables at rest. If you don't specify a value, the service uses an AWS-managed key. (pattern: <code>arn:(aws[a-zA-Z-]*)?:kms:[a-z]{2,4}(-[a-z]{2,4})?-[a-z]+-\d{1}:\d{12}:key/[\w-/]+</code>)
`multi_location_config`	`object`	If this canary is part of a multi-location configuration, this structure contains information about the canary's location type, primary location, and replicas.
`name`	`string`	The name of the canary. (pattern: <code>^[0-9a-z_-]+$</code>)
`provisioned_resource_cleanup`	`string`	Specifies whether to also delete the Lambda functions and layers used by this canary when the canary is deleted. If it is AUTOMATIC, the Lambda functions and layers will be deleted when the canary is deleted. If the value of this parameter is OFF, then the value of the DeleteLambda parameter of the DeleteCanary operation determines whether the Lambda functions and layers will be deleted. (AUTOMATIC, OFF)
`run_config`	`object`	A structure that contains information about a canary run.
`runtime_version`	`string`	Specifies the runtime version to use for the canary. For more information about runtime versions, see Canary Runtime Versions.
`schedule`	`object`	A structure that contains information about how often the canary is to run, and when these runs are to stop.
`status`	`object`	A structure that contains information about the canary's status.
`success_retention_period_in_days`	`integer`	The number of days to retain data about successful runs of this canary. This setting affects the range of information returned by GetCanaryRuns, as well as the range of information displayed in the Synthetics console.
`tags`	`object`	The list of key-value pairs that are associated with the canary.
`timeline`	`object`	A structure that contains information about when the canary was created, modified, and most recently run.
`visual_reference`	`object`	If this canary performs visual monitoring by comparing screenshots, this structure contains the ID of the canary run to use as the baseline for screenshots, and the coordinates of any parts of the screen to ignore during the visual monitoring comparison.
`visual_references`	`array`	A list of visual reference configurations for the canary, one for each browser type that the canary is configured to run on. Visual references are used for visual monitoring comparisons. syn-nodejs-puppeteer-11.0 and above, and syn-nodejs-playwright-3.0 and above, only supports visualReferences. visualReference field is not supported. Versions older than syn-nodejs-puppeteer-11.0 supports both visualReference and visualReferences for backward compatibility. It is recommended to use visualReferences for consistency and future compatibility.
`vpc_config`	`object`	If this canary is to test an endpoint in a VPC, this structure contains information about the subnets and security groups of the VPC endpoint. For more information, see Running a Canary in a VPC.

Name	Datatype	Description
`canaries`	`array`	Returns an array. Each item in the array contains the full information about one canary.
`next_token`	`string`	A token that indicates that there is more data available. You can use this token in a subsequent DescribeCanaries operation to retrieve the next set of results.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get_canary`	`select`	`name`, `region`	`dryRunId`	Retrieves complete information about one canary. You must specify the name of the canary that you want. To get a list of canaries and their names, use DescribeCanaries.
`describe_canaries`	`select`	`region`		This operation returns a list of the canaries in your account, along with full details about each canary. This operation supports resource-level authorization using an IAM policy and the Names parameter. If you specify the Names parameter, the operation is successful only if you have authorization to view all the canaries that you specify in your request. If you do not have permission to view any of the canaries, the request fails with a 403 response. You are required to use the Names parameter if you are logged on to a user or role that has an IAM policy that restricts which canaries that you are allowed to view. For more information, see Limiting a user to viewing specific canaries.
`create_canary`	`insert`	`region`, `Code`, `ArtifactS3Location`, `ExecutionRoleArn`, `Schedule`, `RuntimeVersion`		Creates a canary. Canaries are scripts that monitor your endpoints and APIs from the outside-in. Canaries help you check the availability and latency of your web services and troubleshoot anomalies by investigating load time data, screenshots of the UI, logs, and metrics. You can set up a canary to run continuously or just once. Do not use CreateCanary to modify an existing canary. Use UpdateCanary instead. To create canaries, you must have the CloudWatchSyntheticsFullAccess policy. If you are creating a new IAM role for the canary, you also need the iam:CreateRole, iam:CreatePolicy and iam:AttachRolePolicy permissions. For more information, see Necessary Roles and Permissions. Do not include secrets or proprietary information in your canary names. The canary name makes up part of the Amazon Resource Name (ARN) for the canary, and the ARN is included in outbound calls over the internet. For more information, see Security Considerations for Synthetics Canaries.
`update_canary`	`update`	`name`, `region`		Updates the configuration of a canary that has already been created. For multibrowser canaries, you can add or remove browsers by updating the browserConfig list in the update call. For example: To add Firefox to a canary that currently uses Chrome, specify browserConfigs as [CHROME, FIREFOX] To remove Firefox and keep only Chrome, specify browserConfigs as [CHROME] You can't use this operation to update the tags of an existing canary. To change the tags of an existing canary, use TagResource. When you use the dryRunId field when updating a canary, the only other field you can provide is the Schedule. Adding any other field will thrown an exception.
`delete_canary`	`delete`	`name`, `region`	`deleteLambda`	Permanently deletes the specified canary. If the canary's ProvisionedResourceCleanup field is set to AUTOMATIC or you specify DeleteLambda in this operation as true, CloudWatch Synthetics also deletes the Lambda functions and layers that are used by the canary. Other resources used and created by the canary are not automatically deleted. After you delete a canary, you should also delete the following: The CloudWatch alarms created for this canary. These alarms have a name of Synthetics-Alarm-first-198-characters-of-canary-name-canaryId-alarm number Amazon S3 objects and buckets, such as the canary's artifact location. IAM roles created for the canary. If they were created in the console, these roles have the name role/service-role/CloudWatchSyntheticsRole-First-21-Characters-of-CanaryName CloudWatch Logs log groups created for the canary. These logs groups have the name /aws/lambda/cwsyn-First-21-Characters-of-CanaryName Before you delete a canary, you might want to use GetCanary to display the information about this canary. Make note of the information returned by this operation so that you can delete these resources after you delete the canary.
`start_canary_dry_run`	`exec`	`name`, `region`		Use this operation to start a dry run for a canary that has already been created

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`name`	`string`	The name of the canary that you want to dry run. To find canary names, use DescribeCanaries.
`region`	`string`	AWS region (default: us-east-1)
`deleteLambda`	`boolean`	Specifies whether to also delete the Lambda functions and layers used by this canary. The default is false. Your setting for this parameter is used only if the canary doesn't have AUTOMATIC for its ProvisionedResourceCleanup field. If that field is set to AUTOMATIC, then the Lambda functions and layers will be deleted when this canary is deleted. Type: Boolean
`dryRunId`	`string`	The DryRunId associated with an existing canary’s dry run. You can use this DryRunId to retrieve information about the dry run.

`SELECT` examples

get_canary
describe_canaries

Retrieves complete information about one canary. You must specify the name of the canary that you want. To get a list of canaries and their names, use DescribeCanaries.

SELECT
artifact_config,
artifact_s3_location,
browser_configs,
code,
dry_run_config,
engine_arn,
engine_configs,
execution_role_arn,
failure_retention_period_in_days,
id,
kms_key_arn,
multi_location_config,
name,
provisioned_resource_cleanup,
run_config,
runtime_version,
schedule,
status,
success_retention_period_in_days,
tags,
timeline,
visual_reference,
visual_references,
vpc_config
FROM aws.synthetics.canaries
WHERE name = '{{ name }}' -- required
AND region = '{{ region }}' -- required
AND dryRunId = '{{ dryRunId }}'
;

This operation returns a list of the canaries in your account, along with full details about each canary. This operation supports resource-level authorization using an IAM policy and the Names parameter. If you specify the Names parameter, the operation is successful only if you have authorization to view all the canaries that you specify in your request. If you do not have permission to view any of the canaries, the request fails with a 403 response. You are required to use the Names parameter if you are logged on to a user or role that has an IAM policy that restricts which canaries that you are allowed to view. For more information, see Limiting a user to viewing specific canaries.

SELECT
canaries,
next_token
FROM aws.synthetics.canaries
WHERE region = '{{ region }}' -- required
;

`INSERT` examples

create_canary
Manifest

Creates a canary. Canaries are scripts that monitor your endpoints and APIs from the outside-in. Canaries help you check the availability and latency of your web services and troubleshoot anomalies by investigating load time data, screenshots of the UI, logs, and metrics. You can set up a canary to run continuously or just once. Do not use CreateCanary to modify an existing canary. Use UpdateCanary instead. To create canaries, you must have the CloudWatchSyntheticsFullAccess policy. If you are creating a new IAM role for the canary, you also need the iam:CreateRole, iam:CreatePolicy and iam:AttachRolePolicy permissions. For more information, see Necessary Roles and Permissions. Do not include secrets or proprietary information in your canary names. The canary name makes up part of the Amazon Resource Name (ARN) for the canary, and the ARN is included in outbound calls over the internet. For more information, see Security Considerations for Synthetics Canaries.

INSERT INTO aws.synthetics.canaries (
Name,
Code,
ArtifactS3Location,
ExecutionRoleArn,
Schedule,
RunConfig,
SuccessRetentionPeriodInDays,
FailureRetentionPeriodInDays,
RuntimeVersion,
VpcConfig,
ResourcesToReplicateTags,
ProvisionedResourceCleanup,
BrowserConfigs,
AddReplicaLocations,
Tags,
ArtifactConfig,
KmsKeyArn,
region
)
SELECT 
'{{ Name }}',
'{{ Code }}' /* required */,
'{{ ArtifactS3Location }}' /* required */,
'{{ ExecutionRoleArn }}' /* required */,
'{{ Schedule }}' /* required */,
'{{ RunConfig }}',
{{ SuccessRetentionPeriodInDays }},
{{ FailureRetentionPeriodInDays }},
'{{ RuntimeVersion }}' /* required */,
'{{ VpcConfig }}',
'{{ ResourcesToReplicateTags }}',
'{{ ProvisionedResourceCleanup }}',
'{{ BrowserConfigs }}',
'{{ AddReplicaLocations }}',
'{{ Tags }}',
'{{ ArtifactConfig }}',
'{{ KmsKeyArn }}',
'{{ region }}'
RETURNING
canary
;

# Description fields are for documentation purposes
- name: canaries
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the canaries resource.
  - name: Name
    value: "{{ Name }}"
  - name: Code
    description: |
      Use this structure to input your script code for the canary. This structure contains the Lambda handler with the location where the canary should start running the script. If the script is stored in an Amazon S3 bucket, the bucket name, key, and version are also included. If the script was passed into the canary directly, the script code is contained in the value of Zipfile. If you are uploading your canary scripts with an Amazon S3 bucket, your zip file should include your script in a certain folder structure. For Node.js canaries, the folder structure must be nodejs/node_modules/myCanaryFilename.js For more information, see Packaging your Node.js canary files For Python canaries, the folder structure must be python/myCanaryFilename.py or python/myFolder/myCanaryFilename.py For more information, see Packaging your Python canary files
    value:
      S3Bucket: "{{ S3Bucket }}"
      S3Key: "{{ S3Key }}"
      S3Version: "{{ S3Version }}"
      ZipFile: "{{ ZipFile }}"
      Handler: "{{ Handler }}"
      BlueprintTypes:
        - "{{ BlueprintTypes }}"
      Dependencies:
        - Type: "{{ Type }}"
          Reference: "{{ Reference }}"
  - name: ArtifactS3Location
    value: "{{ ArtifactS3Location }}"
  - name: ExecutionRoleArn
    value: "{{ ExecutionRoleArn }}"
  - name: Schedule
    description: |
      This structure specifies how often a canary is to make runs and the date and time when it should stop making runs.
    value:
      Expression: "{{ Expression }}"
      DurationInSeconds: {{ DurationInSeconds }}
      RetryConfig:
        MaxRetries: {{ MaxRetries }}
  - name: RunConfig
    description: |
      A structure that contains input information for a canary run.
    value:
      TimeoutInSeconds: {{ TimeoutInSeconds }}
      MemoryInMB: {{ MemoryInMB }}
      ActiveTracing: {{ ActiveTracing }}
      EnvironmentVariables: "{{ EnvironmentVariables }}"
      EphemeralStorage: {{ EphemeralStorage }}
  - name: SuccessRetentionPeriodInDays
    value: {{ SuccessRetentionPeriodInDays }}
  - name: FailureRetentionPeriodInDays
    value: {{ FailureRetentionPeriodInDays }}
  - name: RuntimeVersion
    value: "{{ RuntimeVersion }}"
  - name: VpcConfig
    description: |
      If this canary is to test an endpoint in a VPC, this structure contains information about the subnets and security groups of the VPC endpoint. For more information, see Running a Canary in a VPC.
    value:
      SubnetIds:
        - "{{ SubnetIds }}"
      SecurityGroupIds:
        - "{{ SecurityGroupIds }}"
      Ipv6AllowedForDualStack: {{ Ipv6AllowedForDualStack }}
  - name: ResourcesToReplicateTags
    value:
      - "{{ ResourcesToReplicateTags }}"
  - name: ProvisionedResourceCleanup
    value: "{{ ProvisionedResourceCleanup }}"
    valid_values: ['AUTOMATIC', 'OFF']
  - name: BrowserConfigs
    value:
      - BrowserType: "{{ BrowserType }}"
  - name: AddReplicaLocations
    value:
      - Location: "{{ Location }}"
        VpcConfig:
          SubnetIds:
            - "{{ SubnetIds }}"
          SecurityGroupIds:
            - "{{ SecurityGroupIds }}"
          Ipv6AllowedForDualStack: {{ Ipv6AllowedForDualStack }}
        KmsKeyArn: "{{ KmsKeyArn }}"
  - name: Tags
    value: "{{ Tags }}"
  - name: ArtifactConfig
    description: |
      A structure that contains the configuration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3.
    value:
      S3Encryption:
        EncryptionMode: "{{ EncryptionMode }}"
        KmsKeyArn: "{{ KmsKeyArn }}"
  - name: KmsKeyArn
    value: "{{ KmsKeyArn }}"

`UPDATE` examples

update_canary

Updates the configuration of a canary that has already been created. For multibrowser canaries, you can add or remove browsers by updating the browserConfig list in the update call. For example: To add Firefox to a canary that currently uses Chrome, specify browserConfigs as [CHROME, FIREFOX] To remove Firefox and keep only Chrome, specify browserConfigs as [CHROME] You can't use this operation to update the tags of an existing canary. To change the tags of an existing canary, use TagResource. When you use the dryRunId field when updating a canary, the only other field you can provide is the Schedule. Adding any other field will thrown an exception.

UPDATE aws.synthetics.canaries
SET 
Code = '{{ Code }}',
ExecutionRoleArn = '{{ ExecutionRoleArn }}',
RuntimeVersion = '{{ RuntimeVersion }}',
Schedule = '{{ Schedule }}',
RunConfig = '{{ RunConfig }}',
SuccessRetentionPeriodInDays = {{ SuccessRetentionPeriodInDays }},
FailureRetentionPeriodInDays = {{ FailureRetentionPeriodInDays }},
VpcConfig = '{{ VpcConfig }}',
VisualReference = '{{ VisualReference }}',
ArtifactS3Location = '{{ ArtifactS3Location }}',
ArtifactConfig = '{{ ArtifactConfig }}',
ProvisionedResourceCleanup = '{{ ProvisionedResourceCleanup }}',
DryRunId = '{{ DryRunId }}',
VisualReferences = '{{ VisualReferences }}',
BrowserConfigs = '{{ BrowserConfigs }}',
AddReplicaLocations = '{{ AddReplicaLocations }}',
RemoveReplicaLocations = '{{ RemoveReplicaLocations }}',
KmsKeyArn = '{{ KmsKeyArn }}'
WHERE 
name = '{{ name }}' --required
AND region = '{{ region }}' --required;

`DELETE` examples

delete_canary

Permanently deletes the specified canary. If the canary's ProvisionedResourceCleanup field is set to AUTOMATIC or you specify DeleteLambda in this operation as true, CloudWatch Synthetics also deletes the Lambda functions and layers that are used by the canary. Other resources used and created by the canary are not automatically deleted. After you delete a canary, you should also delete the following: The CloudWatch alarms created for this canary. These alarms have a name of Synthetics-Alarm-first-198-characters-of-canary-name-canaryId-alarm number Amazon S3 objects and buckets, such as the canary's artifact location. IAM roles created for the canary. If they were created in the console, these roles have the name role/service-role/CloudWatchSyntheticsRole-First-21-Characters-of-CanaryName CloudWatch Logs log groups created for the canary. These logs groups have the name /aws/lambda/cwsyn-First-21-Characters-of-CanaryName Before you delete a canary, you might want to use GetCanary to display the information about this canary. Make note of the information returned by this operation so that you can delete these resources after you delete the canary.

DELETE FROM aws.synthetics.canaries
WHERE name = '{{ name }}' --required
AND region = '{{ region }}' --required
AND deleteLambda = '{{ deleteLambda }}'
;

Lifecycle Methods

start_canary_dry_run

Use this operation to start a dry run for a canary that has already been created

EXEC aws.synthetics.canaries.start_canary_dry_run 
@name='{{ name }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"Code": "{{ Code }}", 
"RuntimeVersion": "{{ RuntimeVersion }}", 
"RunConfig": "{{ RunConfig }}", 
"VpcConfig": "{{ VpcConfig }}", 
"ExecutionRoleArn": "{{ ExecutionRoleArn }}", 
"SuccessRetentionPeriodInDays": {{ SuccessRetentionPeriodInDays }}, 
"FailureRetentionPeriodInDays": {{ FailureRetentionPeriodInDays }}, 
"VisualReference": "{{ VisualReference }}", 
"ArtifactS3Location": "{{ ArtifactS3Location }}", 
"ArtifactConfig": "{{ ArtifactConfig }}", 
"ProvisionedResourceCleanup": "{{ ProvisionedResourceCleanup }}", 
"BrowserConfigs": "{{ BrowserConfigs }}", 
"VisualReferences": "{{ VisualReferences }}"
}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​

Lifecycle Methods​