@aws-cdk_aws-synthetics-alpha.Canary

class Canary (construct) ๐Ÿ”น

LanguageType name
.NETAmazon.CDK.AWS.Synthetics.Alpha.Canary
Gogithub.com/aws/aws-cdk-go/awscdksyntheticsalpha/v2#Canary
Javasoftware.amazon.awscdk.services.synthetics.alpha.Canary
Pythonaws_cdk.aws_synthetics_alpha.Canary
TypeScript (source)@aws-cdk/aws-synthetics-alpha ยป Canary

Implements IConstruct, IDependable, IResource, IConnectable

Define a new Canary.

Example

const canary = new synthetics.Canary(this, 'MyCanary', {
  schedule: synthetics.Schedule.rate(Duration.minutes(5)),
  test: synthetics.Test.custom({
    code: synthetics.Code.fromAsset(path.join(__dirname, 'canary')),
    handler: 'index.handler',
  }),
  runtime: synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_4_0,
  environmentVariables: {
    stage: 'prod',
  },
});

Initializer

new Canary(scope: Construct, id: string, props: CanaryProps)

Parameters

  • scope Construct
  • id string
  • props CanaryProps

Construct Props

NameTypeDescription
runtime๐Ÿ”นRuntimeSpecify the runtime version to use for the canary.
test๐Ÿ”นTestThe type of test that you want your canary to run.
artifactsBucketLocation?๐Ÿ”นArtifactsBucketLocationThe s3 location that stores the data of the canary runs.
canaryName?๐Ÿ”นstringThe name of the canary.
enableAutoDeleteLambdas?๐Ÿ”นbooleanWhether or not to delete the lambda resources when the canary is deleted.
environmentVariables?๐Ÿ”น{ [string]: string }Key-value pairs that the Synthetics caches and makes available for your canary scripts.
failureRetentionPeriod?๐Ÿ”นDurationHow many days should failed runs be retained.
role?๐Ÿ”นIRoleCanary execution role.
schedule?๐Ÿ”นScheduleSpecify the schedule for how often the canary runs.
securityGroups?๐Ÿ”นISecurityGroup[]The list of security groups to associate with the canary's network interfaces.
startAfterCreation?๐Ÿ”นbooleanWhether or not the canary should start after creation.
successRetentionPeriod?๐Ÿ”นDurationHow many days should successful runs be retained.
timeToLive?๐Ÿ”นDurationHow long the canary will be in a 'RUNNING' state.
vpc?๐Ÿ”นIVpcThe VPC where this canary is run.
vpcSubnets?๐Ÿ”นSubnetSelectionWhere to place the network interfaces within the VPC.

runtime๐Ÿ”น

Type: Runtime

Specify the runtime version to use for the canary.

See also: https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library.html


test๐Ÿ”น

Type: Test

The type of test that you want your canary to run.

Use Test.custom() to specify the test to run.


artifactsBucketLocation?๐Ÿ”น

Type: ArtifactsBucketLocation (optional, default: A new s3 bucket will be created without a prefix.)

The s3 location that stores the data of the canary runs.


canaryName?๐Ÿ”น

Type: string (optional, default: A unique name will be generated from the construct ID)

The name of the canary.

Be sure to give it a descriptive name that distinguishes it from other canaries in your account.

Do not include secrets or proprietary information in your canary name. The canary name makes up part of the canary ARN, which is included in outbound calls over the internet.

See also: https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/servicelens_canaries_security.html


enableAutoDeleteLambdas?๐Ÿ”น

Type: boolean (optional, default: false)

Whether or not to delete the lambda resources when the canary is deleted.

See also: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-synthetics-canary.html#cfn-synthetics-canary-deletelambdaresourcesoncanarydeletion


environmentVariables?๐Ÿ”น

Type: { [string]: string } (optional, default: No environment variables.)

Key-value pairs that the Synthetics caches and makes available for your canary scripts.

Use environment variables to apply configuration changes, such as test and production environment configurations, without changing your Canary script source code.


failureRetentionPeriod?๐Ÿ”น

Type: Duration (optional, default: Duration.days(31))

How many days should failed runs be retained.


role?๐Ÿ”น

Type: IRole (optional, default: A unique role will be generated for this canary. You can add permissions to roles by calling 'addToRolePolicy'.)

Canary execution role.

This is the role that will be assumed by the canary upon execution. It controls the permissions that the canary will have. The role must be assumable by the AWS Lambda service principal.

If not supplied, a role will be created with all the required permissions. If you provide a Role, you must add the required permissions.

See also: [required permissions: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-synthetics-canary.html#cfn-synthetics-canary-executionrolearn](required permissions: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-synthetics-canary.html#cfn-synthetics-canary-executionrolearn)


schedule?๐Ÿ”น

Type: Schedule (optional, default: 'rate(5 minutes)')

Specify the schedule for how often the canary runs.

For example, if you set schedule to rate(10 minutes), then the canary will run every 10 minutes. You can set the schedule with Schedule.rate(Duration) (recommended) or you can specify an expression using Schedule.expression().


securityGroups?๐Ÿ”น

Type: ISecurityGroup[] (optional, default: If the canary is placed within a VPC and a security group is not specified a dedicated security group will be created for this canary.)

The list of security groups to associate with the canary's network interfaces.

You must provide vpc when using this prop.


startAfterCreation?๐Ÿ”น

Type: boolean (optional, default: true)

Whether or not the canary should start after creation.


successRetentionPeriod?๐Ÿ”น

Type: Duration (optional, default: Duration.days(31))

How many days should successful runs be retained.


timeToLive?๐Ÿ”น

Type: Duration (optional, default: no limit)

How long the canary will be in a 'RUNNING' state.

For example, if you set timeToLive to be 1 hour and schedule to be rate(10 minutes), your canary will run at 10 minute intervals for an hour, for a total of 6 times.


vpc?๐Ÿ”น

Type: IVpc (optional, default: Not in VPC)

The VPC where this canary is run.

Specify this if the canary needs to access resources in a VPC.


vpcSubnets?๐Ÿ”น

Type: SubnetSelection (optional, default: the Vpc default strategy if not specified)

Where to place the network interfaces within the VPC.

You must provide vpc when using this prop.

Properties

NameTypeDescription
artifactsBucket๐Ÿ”นIBucketBucket where data from each canary run is stored.
canaryId๐Ÿ”นstringThe canary ID.
canaryName๐Ÿ”นstringThe canary Name.
canaryState๐Ÿ”นstringThe state of the canary.
connections๐Ÿ”นConnectionsAccess the Connections object.
env๐Ÿ”นResourceEnvironmentThe environment this resource belongs to.
node๐Ÿ”นNodeThe tree node.
role๐Ÿ”นIRoleExecution role associated with this Canary.
stack๐Ÿ”นStackThe stack in which this resource is defined.

artifactsBucket๐Ÿ”น

Type: IBucket

Bucket where data from each canary run is stored.


canaryId๐Ÿ”น

Type: string

The canary ID.


canaryName๐Ÿ”น

Type: string

The canary Name.


canaryState๐Ÿ”น

Type: string

The state of the canary.

For example, 'RUNNING', 'STOPPED', 'NOT STARTED', or 'ERROR'.


connections๐Ÿ”น

Type: Connections

Access the Connections object.

Will fail if not a VPC-enabled Canary


env๐Ÿ”น

Type: ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.


node๐Ÿ”น

Type: Node

The tree node.


role๐Ÿ”น

Type: IRole

Execution role associated with this Canary.


stack๐Ÿ”น

Type: Stack

The stack in which this resource is defined.

Methods

NameDescription
applyRemovalPolicy(policy)๐Ÿ”นApply the given removal policy to this resource.
metricDuration(options?)๐Ÿ”นMeasure the Duration of a single canary run, in seconds.
metricFailed(options?)๐Ÿ”นMeasure the number of failed canary runs over a given time period.
metricSuccessPercent(options?)๐Ÿ”นMeasure the percentage of successful canary runs.
toString()๐Ÿ”นReturns a string representation of this construct.

applyRemovalPolicy(policy)๐Ÿ”น

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

  • policy RemovalPolicy

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).


metricDuration(options?)๐Ÿ”น

public metricDuration(options?: MetricOptions): Metric

Parameters

  • options MetricOptions โ€” - configuration options for the metric.

Returns

  • Metric

Measure the Duration of a single canary run, in seconds.


metricFailed(options?)๐Ÿ”น

public metricFailed(options?: MetricOptions): Metric

Parameters

  • options MetricOptions โ€” - configuration options for the metric.

Returns

  • Metric

Measure the number of failed canary runs over a given time period.

Default: sum over 5 minutes


metricSuccessPercent(options?)๐Ÿ”น

public metricSuccessPercent(options?: MetricOptions): Metric

Parameters

  • options MetricOptions โ€” - configuration options for the metric.

Returns

  • Metric

Measure the percentage of successful canary runs.


toString()๐Ÿ”น

public toString(): string

Returns

  • string

Returns a string representation of this construct.