Package software.amazon.awscdk.services.synthetics

Class CfnCanary

java.lang.Object

software.amazon.jsii.JsiiObject

software.constructs.Construct

software.amazon.awscdk.CfnElement

software.amazon.awscdk.CfnRefElement

software.amazon.awscdk.CfnResource

software.amazon.awscdk.services.synthetics.CfnCanary

All Implemented Interfaces:

IInspectable, ITaggable, software.amazon.jsii.JsiiSerializable, software.constructs.IConstruct, software.constructs.IDependable

@Generated(value="jsii-pacmak/1.109.0 (build c221850)",
           date="2025-03-19T18:01:43.698Z")
@Stability(Stable)
public class CfnCanary
extends CfnResource
implements IInspectable, ITaggable

Creates or updates 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.

Canaries are automated scripts that run at specified intervals against an endpoint. They include Python or Node.js code to create a Lambda function. This code needs to be packaged in a certain way, depending on the language. For more information, see Writing a canary script .

To create canaries, you must have the CloudWatchSyntheticsFullAccess policy. If you are creating a new IAM role for the canary, you also need the 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 .

Example:

 // The code below shows an example of how to instantiate this type.
 // The values are placeholders you should change.
 import software.amazon.awscdk.services.synthetics.*;
 CfnCanary cfnCanary = CfnCanary.Builder.create(this, "MyCfnCanary")
         .artifactS3Location("artifactS3Location")
         .code(CodeProperty.builder()
                 .handler("handler")
                 // the properties below are optional
                 .s3Bucket("s3Bucket")
                 .s3Key("s3Key")
                 .s3ObjectVersion("s3ObjectVersion")
                 .script("script")
                 .sourceLocationArn("sourceLocationArn")
                 .build())
         .executionRoleArn("executionRoleArn")
         .name("name")
         .runtimeVersion("runtimeVersion")
         .schedule(ScheduleProperty.builder()
                 .expression("expression")
                 // the properties below are optional
                 .durationInSeconds("durationInSeconds")
                 .build())
         // the properties below are optional
         .artifactConfig(ArtifactConfigProperty.builder()
                 .s3Encryption(S3EncryptionProperty.builder()
                         .encryptionMode("encryptionMode")
                         .kmsKeyArn("kmsKeyArn")
                         .build())
                 .build())
         .deleteLambdaResourcesOnCanaryDeletion(false)
         .failureRetentionPeriod(123)
         .provisionedResourceCleanup("provisionedResourceCleanup")
         .resourcesToReplicateTags(List.of("resourcesToReplicateTags"))
         .runConfig(RunConfigProperty.builder()
                 .activeTracing(false)
                 .environmentVariables(Map.of(
                         "environmentVariablesKey", "environmentVariables"))
                 .memoryInMb(123)
                 .timeoutInSeconds(123)
                 .build())
         .startCanaryAfterCreation(false)
         .successRetentionPeriod(123)
         .tags(List.of(CfnTag.builder()
                 .key("key")
                 .value("value")
                 .build()))
         .visualReference(VisualReferenceProperty.builder()
                 .baseCanaryRunId("baseCanaryRunId")
                 // the properties below are optional
                 .baseScreenshots(List.of(BaseScreenshotProperty.builder()
                         .screenshotName("screenshotName")
                         // the properties below are optional
                         .ignoreCoordinates(List.of("ignoreCoordinates"))
                         .build()))
                 .build())
         .vpcConfig(VPCConfigProperty.builder()
                 .securityGroupIds(List.of("securityGroupIds"))
                 .subnetIds(List.of("subnetIds"))
                 // the properties below are optional
                 .ipv6AllowedForDualStack(false)
                 .vpcId("vpcId")
                 .build())
         .build();
 

See Also:

• http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-synthetics-canary.html

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	CfnCanary.ArtifactConfigProperty	A structure that contains the configuration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3 .
static interface	CfnCanary.BaseScreenshotProperty	A structure representing a screenshot that is used as a baseline during visual monitoring comparisons made by the canary.
static final class	CfnCanary.Builder	A fluent builder for CfnCanary.
static interface	CfnCanary.CodeProperty	Use this structure to input your script code for the canary.
static interface	CfnCanary.RunConfigProperty	A structure that contains input information for a canary run.
static interface	CfnCanary.S3EncryptionProperty	A structure that contains the configuration of the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3 .
static interface	CfnCanary.ScheduleProperty	This structure specifies how often a canary is to make runs and the date and time when it should stop making runs.
static interface	CfnCanary.VisualReferenceProperty	Defines the screenshots to use as the baseline for comparisons during visual monitoring comparisons during future runs of this canary.
static interface	CfnCanary.VPCConfigProperty	If this canary is to test an endpoint in a VPC, this structure contains information about the subnet and security groups of the VPC endpoint.

Nested classes/interfaces inherited from class software.amazon.jsii.JsiiObject

software.amazon.jsii.JsiiObject.InitializationMode

Nested classes/interfaces inherited from interface software.constructs.IConstruct

software.constructs.IConstruct.Jsii$Default

Nested classes/interfaces inherited from interface software.amazon.awscdk.IInspectable

IInspectable.Jsii$Default, IInspectable.Jsii$Proxy

Nested classes/interfaces inherited from interface software.amazon.awscdk.ITaggable

ITaggable.Jsii$Default, ITaggable.Jsii$Proxy

Field Summary

Fields

Modifier and Type	Field	Description
static final String	CFN_RESOURCE_TYPE_NAME	The CloudFormation resource type name for this resource class.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	CfnCanary(software.amazon.jsii.JsiiObject.InitializationMode initializationMode)
protected	CfnCanary(software.amazon.jsii.JsiiObjectRef objRef)
	CfnCanary(software.constructs.Construct scope, String id, CfnCanaryProps props)

Method Summary

Modifier and Type	Method	Description
Object	getArtifactConfig()	A structure that contains the configuration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3.
String	getArtifactS3Location()	The location in Amazon S3 where Synthetics stores artifacts from the runs of this canary.
String	getAttrCodeSourceLocationArn()	Ref returns the ARN of the Lambda layer where Synthetics stores the canary script code.
String	getAttrId()	The ID of the canary.
String	getAttrState()	The state of the canary.
protected Map<String,Object>	getCfnProperties()
Object	getCode()	Use this structure to input your script code for the canary.
Object	getDeleteLambdaResourcesOnCanaryDeletion()	Deprecated. this property has been deprecated
String	getExecutionRoleArn()	The ARN of the IAM role to be used to run the canary.
Number	getFailureRetentionPeriod()	The number of days to retain data about failed runs of this canary.
String	getName()	The name for this canary.
String	getProvisionedResourceCleanup()	Specifies whether to also delete the Lambda functions and layers used by this canary when the canary is deleted.
List<String>	getResourcesToReplicateTags()	To have the tags that you apply to this canary also be applied to the Lambda function that the canary uses, specify this property with the value lambda-function .
Object	getRunConfig()	A structure that contains input information for a canary run.
String	getRuntimeVersion()	Specifies the runtime version to use for the canary.
Object	getSchedule()	A structure that contains information about how often the canary is to run, and when these runs are to stop.
Object	getStartCanaryAfterCreation()	Specify TRUE to have the canary start making runs immediately after it is created.
Number	getSuccessRetentionPeriod()	The number of days to retain data about successful runs of this canary.
TagManager	getTags()	Tag Manager which manages the tags for this resource.
List<CfnTag>	getTagsRaw()	The list of key-value pairs that are associated with the canary.
Object	getVisualReference()	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.
Object	getVpcConfig()	If this canary is to test an endpoint in a VPC, this structure contains information about the subnet and security groups of the VPC endpoint.
void	inspect(TreeInspector inspector)	Examines the CloudFormation resource and discloses attributes.
protected Map<String,Object>	renderProperties(Map<String,Object> props)
void	setArtifactConfig(IResolvable value)	A structure that contains the configuration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3.
void	setArtifactConfig(CfnCanary.ArtifactConfigProperty value)	A structure that contains the configuration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3.
void	setArtifactS3Location(String value)	The location in Amazon S3 where Synthetics stores artifacts from the runs of this canary.
void	setCode(IResolvable value)	Use this structure to input your script code for the canary.
void	setCode(CfnCanary.CodeProperty value)	Use this structure to input your script code for the canary.
void	setDeleteLambdaResourcesOnCanaryDeletion(Boolean value)	Deprecated. this property has been deprecated
void	setDeleteLambdaResourcesOnCanaryDeletion(IResolvable value)	Deprecated. this property has been deprecated
void	setExecutionRoleArn(String value)	The ARN of the IAM role to be used to run the canary.
void	setFailureRetentionPeriod(Number value)	The number of days to retain data about failed runs of this canary.
void	setName(String value)	The name for this canary.
void	setProvisionedResourceCleanup(String value)	Specifies whether to also delete the Lambda functions and layers used by this canary when the canary is deleted.
void	setResourcesToReplicateTags(List<String> value)	To have the tags that you apply to this canary also be applied to the Lambda function that the canary uses, specify this property with the value lambda-function .
void	setRunConfig(IResolvable value)	A structure that contains input information for a canary run.
void	setRunConfig(CfnCanary.RunConfigProperty value)	A structure that contains input information for a canary run.
void	setRuntimeVersion(String value)	Specifies the runtime version to use for the canary.
void	setSchedule(IResolvable value)	A structure that contains information about how often the canary is to run, and when these runs are to stop.
void	setSchedule(CfnCanary.ScheduleProperty value)	A structure that contains information about how often the canary is to run, and when these runs are to stop.
void	setStartCanaryAfterCreation(Boolean value)	Specify TRUE to have the canary start making runs immediately after it is created.
void	setStartCanaryAfterCreation(IResolvable value)	Specify TRUE to have the canary start making runs immediately after it is created.
void	setSuccessRetentionPeriod(Number value)	The number of days to retain data about successful runs of this canary.
void	setTagsRaw(List<CfnTag> value)	The list of key-value pairs that are associated with the canary.
void	setVisualReference(IResolvable value)	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.
void	setVisualReference(CfnCanary.VisualReferenceProperty value)	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.
void	setVpcConfig(IResolvable value)	If this canary is to test an endpoint in a VPC, this structure contains information about the subnet and security groups of the VPC endpoint.
void	setVpcConfig(CfnCanary.VPCConfigProperty value)	If this canary is to test an endpoint in a VPC, this structure contains information about the subnet and security groups of the VPC endpoint.

Methods inherited from class software.amazon.awscdk.CfnResource

addDeletionOverride, addDependency, addDependsOn, addMetadata, addOverride, addPropertyDeletionOverride, addPropertyOverride, applyRemovalPolicy, applyRemovalPolicy, applyRemovalPolicy, getAtt, getAtt, getCfnOptions, getCfnResourceType, getMetadata, getUpdatedProperites, getUpdatedProperties, isCfnResource, obtainDependencies, obtainResourceDependencies, removeDependency, replaceDependency, shouldSynthesize, toString, validateProperties

Methods inherited from class software.amazon.awscdk.CfnRefElement

getRef

Methods inherited from class software.amazon.awscdk.CfnElement

getCreationStack, getLogicalId, getStack, isCfnElement, overrideLogicalId

Methods inherited from class software.constructs.Construct

getNode, isConstruct

Methods inherited from class software.amazon.jsii.JsiiObject

jsiiAsyncCall, jsiiAsyncCall, jsiiCall, jsiiCall, jsiiGet, jsiiGet, jsiiSet, jsiiStaticCall, jsiiStaticCall, jsiiStaticGet, jsiiStaticGet, jsiiStaticSet, jsiiStaticSet

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface software.amazon.jsii.JsiiSerializable

$jsii$toJson

Field Details

CFN_RESOURCE_TYPE_NAME

@Stability(Stable)
public static final String CFN_RESOURCE_TYPE_NAME

The CloudFormation resource type name for this resource class.

Constructor Details

CfnCanary

protected CfnCanary(software.amazon.jsii.JsiiObjectRef objRef)

CfnCanary

protected CfnCanary(software.amazon.jsii.JsiiObject.InitializationMode initializationMode)

CfnCanary

@Stability(Stable)
public CfnCanary(@NotNull
 software.constructs.Construct scope,
 @NotNull
 String id,
 @NotNull
 CfnCanaryProps props)

Parameters:

scope - Scope in which this resource is defined. This parameter is required.

id - Construct identifier for this resource (unique in its scope). This parameter is required.

props - Resource properties. This parameter is required.

Method Details

inspect

@Stability(Stable)
public void inspect(@NotNull
 TreeInspector inspector)

Examines the CloudFormation resource and discloses attributes.

Specified by:

inspect in interface IInspectable

Parameters:

inspector - tree inspector to collect and process attributes. This parameter is required.

renderProperties

@Stability(Stable)
@NotNull
protected Map<String,Object> renderProperties(@NotNull
 Map<String,Object> props)

Overrides:

renderProperties in class CfnResource

Parameters:

props - This parameter is required.

getAttrCodeSourceLocationArn

@Stability(Stable)
@NotNull
public String getAttrCodeSourceLocationArn()

Ref returns the ARN of the Lambda layer where Synthetics stores the canary script code.

getAttrId

@Stability(Stable)
@NotNull
public String getAttrId()

The ID of the canary.

getAttrState

@Stability(Stable)
@NotNull
public String getAttrState()

The state of the canary.

For example, RUNNING .

getCfnProperties

@Stability(Stable)
@NotNull
protected Map<String,Object> getCfnProperties()

Overrides:

getCfnProperties in class CfnResource

getTags

@Stability(Stable)
@NotNull
public TagManager getTags()

Tag Manager which manages the tags for this resource.

Specified by:

getTags in interface ITaggable

getArtifactS3Location

@Stability(Stable)
@NotNull
public String getArtifactS3Location()

The location in Amazon S3 where Synthetics stores artifacts from the runs of this canary.

setArtifactS3Location

@Stability(Stable)
public void setArtifactS3Location(@NotNull
 String value)

The location in Amazon S3 where Synthetics stores artifacts from the runs of this canary.

getCode

@Stability(Stable)
@NotNull
public Object getCode()

Use this structure to input your script code for the canary.

setCode

@Stability(Stable)
public void setCode(@NotNull
 IResolvable value)

Use this structure to input your script code for the canary.

setCode

@Stability(Stable)
public void setCode(@NotNull
 CfnCanary.CodeProperty value)

Use this structure to input your script code for the canary.

getExecutionRoleArn

@Stability(Stable)
@NotNull
public String getExecutionRoleArn()

The ARN of the IAM role to be used to run the canary.

setExecutionRoleArn

@Stability(Stable)
public void setExecutionRoleArn(@NotNull
 String value)

The ARN of the IAM role to be used to run the canary.

getName

@Stability(Stable)
@NotNull
public String getName()

The name for this canary.

setName

@Stability(Stable)
public void setName(@NotNull
 String value)

The name for this canary.

getRuntimeVersion

@Stability(Stable)
@NotNull
public String getRuntimeVersion()

Specifies the runtime version to use for the canary.

setRuntimeVersion

@Stability(Stable)
public void setRuntimeVersion(@NotNull
 String value)

Specifies the runtime version to use for the canary.

getSchedule

@Stability(Stable)
@NotNull
public Object getSchedule()

A structure that contains information about how often the canary is to run, and when these runs are to stop.

setSchedule

@Stability(Stable)
public void setSchedule(@NotNull
 IResolvable value)

A structure that contains information about how often the canary is to run, and when these runs are to stop.

setSchedule

@Stability(Stable)
public void setSchedule(@NotNull
 CfnCanary.ScheduleProperty value)

A structure that contains information about how often the canary is to run, and when these runs are to stop.

getArtifactConfig

@Stability(Stable)
@Nullable
public Object getArtifactConfig()

A structure that contains the configuration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3.

setArtifactConfig

@Stability(Stable)
public void setArtifactConfig(@Nullable
 IResolvable value)

A structure that contains the configuration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3.

setArtifactConfig

@Stability(Stable)
public void setArtifactConfig(@Nullable
 CfnCanary.ArtifactConfigProperty value)

A structure that contains the configuration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3.

getDeleteLambdaResourcesOnCanaryDeletion

@Stability(Deprecated)
@Deprecated
@Nullable
public Object getDeleteLambdaResourcesOnCanaryDeletion()

Deprecated.

this property has been deprecated

(deprecated) Deletes associated lambda resources created by Synthetics if set to True.

setDeleteLambdaResourcesOnCanaryDeletion

@Stability(Deprecated)
@Deprecated
public void setDeleteLambdaResourcesOnCanaryDeletion(@Nullable
 Boolean value)

Deprecated.

this property has been deprecated

(deprecated) Deletes associated lambda resources created by Synthetics if set to True.

setDeleteLambdaResourcesOnCanaryDeletion

@Stability(Deprecated)
@Deprecated
public void setDeleteLambdaResourcesOnCanaryDeletion(@Nullable
 IResolvable value)

Deprecated.

this property has been deprecated

(deprecated) Deletes associated lambda resources created by Synthetics if set to True.

getFailureRetentionPeriod

@Stability(Stable)
@Nullable
public Number getFailureRetentionPeriod()

The number of days to retain data about failed runs of this canary.

setFailureRetentionPeriod

@Stability(Stable)
public void setFailureRetentionPeriod(@Nullable
 Number value)

The number of days to retain data about failed runs of this canary.

getProvisionedResourceCleanup

@Stability(Stable)
@Nullable
public String getProvisionedResourceCleanup()

Specifies whether to also delete the Lambda functions and layers used by this canary when the canary is deleted.

setProvisionedResourceCleanup

@Stability(Stable)
public void setProvisionedResourceCleanup(@Nullable
 String value)

Specifies whether to also delete the Lambda functions and layers used by this canary when the canary is deleted.

getResourcesToReplicateTags

@Stability(Stable)
@Nullable
public List<String> getResourcesToReplicateTags()

To have the tags that you apply to this canary also be applied to the Lambda function that the canary uses, specify this property with the value lambda-function .

setResourcesToReplicateTags

@Stability(Stable)
public void setResourcesToReplicateTags(@Nullable
 List<String> value)

To have the tags that you apply to this canary also be applied to the Lambda function that the canary uses, specify this property with the value lambda-function .

getRunConfig

@Stability(Stable)
@Nullable
public Object getRunConfig()

A structure that contains input information for a canary run.

setRunConfig

@Stability(Stable)
public void setRunConfig(@Nullable
 IResolvable value)

A structure that contains input information for a canary run.

setRunConfig

@Stability(Stable)
public void setRunConfig(@Nullable
 CfnCanary.RunConfigProperty value)

A structure that contains input information for a canary run.

getStartCanaryAfterCreation

@Stability(Stable)
@Nullable
public Object getStartCanaryAfterCreation()

Specify TRUE to have the canary start making runs immediately after it is created.

setStartCanaryAfterCreation

@Stability(Stable)
public void setStartCanaryAfterCreation(@Nullable
 Boolean value)

Specify TRUE to have the canary start making runs immediately after it is created.

setStartCanaryAfterCreation

@Stability(Stable)
public void setStartCanaryAfterCreation(@Nullable
 IResolvable value)

Specify TRUE to have the canary start making runs immediately after it is created.

getSuccessRetentionPeriod

@Stability(Stable)
@Nullable
public Number getSuccessRetentionPeriod()

The number of days to retain data about successful runs of this canary.

setSuccessRetentionPeriod

@Stability(Stable)
public void setSuccessRetentionPeriod(@Nullable
 Number value)

The number of days to retain data about successful runs of this canary.

getTagsRaw

@Stability(Stable)
@Nullable
public List<CfnTag> getTagsRaw()

The list of key-value pairs that are associated with the canary.

setTagsRaw

@Stability(Stable)
public void setTagsRaw(@Nullable
 List<CfnTag> value)

The list of key-value pairs that are associated with the canary.

getVisualReference

@Stability(Stable)
@Nullable
public Object getVisualReference()

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.

setVisualReference

@Stability(Stable)
public void setVisualReference(@Nullable
 IResolvable value)

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.

setVisualReference

@Stability(Stable)
public void setVisualReference(@Nullable
 CfnCanary.VisualReferenceProperty value)

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.

getVpcConfig

@Stability(Stable)
@Nullable
public Object getVpcConfig()

If this canary is to test an endpoint in a VPC, this structure contains information about the subnet and security groups of the VPC endpoint.

setVpcConfig

@Stability(Stable)
public void setVpcConfig(@Nullable
 IResolvable value)

If this canary is to test an endpoint in a VPC, this structure contains information about the subnet and security groups of the VPC endpoint.

setVpcConfig

@Stability(Stable)
public void setVpcConfig(@Nullable
 CfnCanary.VPCConfigProperty value)

If this canary is to test an endpoint in a VPC, this structure contains information about the subnet and security groups of the VPC endpoint.