Canary

class aws_cdk.aws_synthetics.Canary(scope, id, *, runtime, test, active_tracing=None, artifact_s3_encryption_mode=None, artifact_s3_kms_key=None, artifacts_bucket_lifecycle_rules=None, artifacts_bucket_location=None, canary_name=None, cleanup=None, environment_variables=None, failure_retention_period=None, memory=None, role=None, schedule=None, security_groups=None, start_after_creation=None, success_retention_period=None, timeout=None, time_to_live=None, vpc=None, vpc_subnets=None)

Bases: Resource

Define a new Canary.

ExampleMetadata:: infused

Example:

import aws_cdk as cdk


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_6_2,
    memory=cdk.Size.mebibytes(1024)
)

Parameters:

scope (Construct) –
id (str) –
runtime (Runtime) – Specify the runtime version to use for the canary.
test (Test) – The type of test that you want your canary to run. Use Test.custom() to specify the test to run.
active_tracing (Optional[bool]) – Specifies whether this canary is to use active AWS X-Ray tracing when it runs. Active tracing enables this canary run to be displayed in the ServiceLens and X-Ray service maps even if the canary does not hit an endpoint that has X-Ray tracing enabled. Using X-Ray tracing incurs charges. You can enable active tracing only for canaries that use version syn-nodejs-2.0 or later for their canary runtime. Default: false
artifact_s3_encryption_mode (Optional[ArtifactsEncryptionMode]) – Canary Artifacts in S3 encryption mode. Artifact encryption is only supported for canaries that use Synthetics runtime version syn-nodejs-puppeteer-3.3 or later. Default: - Artifacts are encrypted at rest using an AWS managed key. ArtifactsEncryptionMode.KMS is set if you specify artifactS3KmsKey.
artifact_s3_kms_key (Optional[IKey]) – The KMS key used to encrypt canary artifacts. Default: - no kms key if artifactS3EncryptionMode is set to S3_MANAGED. A key will be created if one is not provided and artifactS3EncryptionMode is set to KMS.
artifacts_bucket_lifecycle_rules (Optional[Sequence[Union[LifecycleRule, Dict[str, Any]]]]) – Lifecycle rules for the generated canary artifact bucket. Has no effect if a bucket is passed to artifactsBucketLocation. If you pass a bucket to artifactsBucketLocation, you can add lifecycle rules to the bucket itself. Default: - no rules applied to the generated bucket.
artifacts_bucket_location (Union[ArtifactsBucketLocation, Dict[str, Any], None]) – The s3 location that stores the data of the canary runs. Default: - A new s3 bucket will be created without a prefix.
canary_name (Optional[str]) – 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. Default: - A unique name will be generated from the construct ID
cleanup (Optional[Cleanup]) – Specify the underlying resources to be cleaned up when the canary is deleted. Using Cleanup.LAMBDA will create a Custom Resource to achieve this. Default: Cleanup.NOTHING
environment_variables (Optional[Mapping[str, str]]) – 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. Default: - No environment variables.
failure_retention_period (Optional[Duration]) – How many days should failed runs be retained. Default: Duration.days(31)
memory (Optional[Size]) – The maximum amount of memory that the canary can use while running. This value must be a multiple of 64 Mib. The range is 960 MiB to 3008 MiB. Default: Size.mebibytes(1024)
role (Optional[IRole]) – 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. Default: - A unique role will be generated for this canary. You can add permissions to roles by calling ‘addToRolePolicy’.
schedule (Optional[Schedule]) – 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(). Default: ‘rate(5 minutes)’
security_groups (Optional[Sequence[ISecurityGroup]]) – The list of security groups to associate with the canary’s network interfaces. You must provide vpc when using this prop. 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.
start_after_creation (Optional[bool]) – Whether or not the canary should start after creation. Default: true
success_retention_period (Optional[Duration]) – How many days should successful runs be retained. Default: Duration.days(31)
timeout (Optional[Duration]) – How long the canary is allowed to run before it must stop. You can’t set this time to be longer than the frequency of the runs of this canary. The minimum allowed value is 3 seconds. The maximum allowed value is 840 seconds (14 minutes). Default: - the frequency of the canary is used as this value, up to a maximum of 900 seconds.
time_to_live (Optional[Duration]) – 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. Default: - no limit
vpc (Optional[IVpc]) – The VPC where this canary is run. Specify this if the canary needs to access resources in a VPC. Default: - Not in VPC
vpc_subnets (Union[SubnetSelection, Dict[str, Any], None]) – Where to place the network interfaces within the VPC. You must provide vpc when using this prop. Default: - the Vpc default strategy if not specified

Methods

apply_removal_policy(policy)

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).

Parameters:

policy (RemovalPolicy) –

Return type:

None

metric_duration(*, account=None, color=None, dimensions_map=None, label=None, period=None, region=None, stack_account=None, stack_region=None, statistic=None, unit=None)

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

Parameters:

account (Optional[str]) – Account which this metric comes from. Default: - Deployment account.
color (Optional[str]) – The hex color code, prefixed with ‘#’ (e.g. ‘#00ff00’), to use when this metric is rendered on a graph. The Color class has a set of standard colors that can be used here. Default: - Automatic color
dimensions_map (Optional[Mapping[str, str]]) – Dimensions of the metric. Default: - No dimensions.
label (Optional[str]) – Label for this metric when added to a Graph in a Dashboard. You can use dynamic labels to show summary information about the entire displayed time series in the legend. For example, if you use:: [max: ${MAX}] MyMetric As the metric label, the maximum value in the visible range will be shown next to the time series name in the graph’s legend. Default: - No label
period (Optional[Duration]) – The period over which the specified statistic is applied. Default: Duration.minutes(5)
region (Optional[str]) – Region which this metric comes from. Default: - Deployment region.
stack_account (Optional[str]) – Account of the stack this metric is attached to. Default: - Deployment account.
stack_region (Optional[str]) – Region of the stack this metric is attached to. Default: - Deployment region.
statistic (Optional[str]) – What function to use for aggregating. Use the aws_cloudwatch.Stats helper class to construct valid input strings. Can be one of the following: - “Minimum” | “min” - “Maximum” | “max” - “Average” | “avg” - “Sum” | “sum” - “SampleCount | “n” - “pNN.NN” - “tmNN.NN” | “tm(NN.NN%:NN.NN%)” - “iqm” - “wmNN.NN” | “wm(NN.NN%:NN.NN%)” - “tcNN.NN” | “tc(NN.NN%:NN.NN%)” - “tsNN.NN” | “ts(NN.NN%:NN.NN%)” Default: Average
unit (Optional[Unit]) – Unit used to filter the metric stream. Only refer to datums emitted to the metric stream with the given unit and ignore all others. Only useful when datums are being emitted to the same metric stream under different units. The default is to use all matric datums in the stream, regardless of unit, which is recommended in nearly all cases. CloudWatch does not honor this property for graphs. Default: - All metric datums in the given metric stream

Default:

avg over 5 minutes

Return type:

Metric

metric_failed(*, account=None, color=None, dimensions_map=None, label=None, period=None, region=None, stack_account=None, stack_region=None, statistic=None, unit=None)

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

Default: sum over 5 minutes

Parameters:

account (Optional[str]) – Account which this metric comes from. Default: - Deployment account.
color (Optional[str]) – The hex color code, prefixed with ‘#’ (e.g. ‘#00ff00’), to use when this metric is rendered on a graph. The Color class has a set of standard colors that can be used here. Default: - Automatic color
dimensions_map (Optional[Mapping[str, str]]) – Dimensions of the metric. Default: - No dimensions.
label (Optional[str]) –
Label for this metric when added to a Graph in a Dashboard. You can use dynamic labels to show summary information about the entire displayed time series in the legend. For example, if you use:: [max: ${MAX}] MyMetric As the metric label, the maximum value in the visible range will be shown next to the time series name in the graph’s legend. Default: - No label
period (Optional[Duration]) – The period over which the specified statistic is applied. Default: Duration.minutes(5)
region (Optional[str]) – Region which this metric comes from. Default: - Deployment region.
stack_account (Optional[str]) – Account of the stack this metric is attached to. Default: - Deployment account.
stack_region (Optional[str]) – Region of the stack this metric is attached to. Default: - Deployment region.
statistic (Optional[str]) – What function to use for aggregating. Use the aws_cloudwatch.Stats helper class to construct valid input strings. Can be one of the following: - “Minimum” | “min” - “Maximum” | “max” - “Average” | “avg” - “Sum” | “sum” - “SampleCount | “n” - “pNN.NN” - “tmNN.NN” | “tm(NN.NN%:NN.NN%)” - “iqm” - “wmNN.NN” | “wm(NN.NN%:NN.NN%)” - “tcNN.NN” | “tc(NN.NN%:NN.NN%)” - “tsNN.NN” | “ts(NN.NN%:NN.NN%)” Default: Average
unit (Optional[Unit]) – Unit used to filter the metric stream. Only refer to datums emitted to the metric stream with the given unit and ignore all others. Only useful when datums are being emitted to the same metric stream under different units. The default is to use all matric datums in the stream, regardless of unit, which is recommended in nearly all cases. CloudWatch does not honor this property for graphs. Default: - All metric datums in the given metric stream

Return type:

Metric

metric_success_percent(*, account=None, color=None, dimensions_map=None, label=None, period=None, region=None, stack_account=None, stack_region=None, statistic=None, unit=None)

Measure the percentage of successful canary runs.

Parameters:

account (Optional[str]) – Account which this metric comes from. Default: - Deployment account.
color (Optional[str]) – The hex color code, prefixed with ‘#’ (e.g. ‘#00ff00’), to use when this metric is rendered on a graph. The Color class has a set of standard colors that can be used here. Default: - Automatic color
dimensions_map (Optional[Mapping[str, str]]) – Dimensions of the metric. Default: - No dimensions.
label (Optional[str]) –
Label for this metric when added to a Graph in a Dashboard. You can use dynamic labels to show summary information about the entire displayed time series in the legend. For example, if you use:: [max: ${MAX}] MyMetric As the metric label, the maximum value in the visible range will be shown next to the time series name in the graph’s legend. Default: - No label
period (Optional[Duration]) – The period over which the specified statistic is applied. Default: Duration.minutes(5)
region (Optional[str]) – Region which this metric comes from. Default: - Deployment region.
stack_account (Optional[str]) – Account of the stack this metric is attached to. Default: - Deployment account.
stack_region (Optional[str]) – Region of the stack this metric is attached to. Default: - Deployment region.
statistic (Optional[str]) – What function to use for aggregating. Use the aws_cloudwatch.Stats helper class to construct valid input strings. Can be one of the following: - “Minimum” | “min” - “Maximum” | “max” - “Average” | “avg” - “Sum” | “sum” - “SampleCount | “n” - “pNN.NN” - “tmNN.NN” | “tm(NN.NN%:NN.NN%)” - “iqm” - “wmNN.NN” | “wm(NN.NN%:NN.NN%)” - “tcNN.NN” | “tc(NN.NN%:NN.NN%)” - “tsNN.NN” | “ts(NN.NN%:NN.NN%)” Default: Average
unit (Optional[Unit]) – Unit used to filter the metric stream. Only refer to datums emitted to the metric stream with the given unit and ignore all others. Only useful when datums are being emitted to the same metric stream under different units. The default is to use all matric datums in the stream, regardless of unit, which is recommended in nearly all cases. CloudWatch does not honor this property for graphs. Default: - All metric datums in the given metric stream

Default:

avg over 5 minutes

Return type:

Metric

to_string()

Returns a string representation of this construct.

Return type:: str

Attributes

artifacts_bucket: Bucket where data from each canary run is stored.

canary_id

The canary ID.

Attribute:: true

canary_name

The canary Name.

Attribute:: true

canary_state

The state of the canary.

For example, ‘RUNNING’, ‘STOPPED’, ‘NOT STARTED’, or ‘ERROR’.

Attribute:: true

connections

Access the Connections object.

Will fail if not a VPC-enabled Canary

env

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: The tree node.

role: Execution role associated with this Canary.

stack: The stack in which this resource is defined.

Static Methods

classmethod is_construct(x)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

Parameters:: x (Any) – Any object.
Return type:: bool
Returns:: true if x is an object created from a class which extends Construct.

classmethod is_owned_resource(construct)

Returns true if the construct was created by CDK, and false otherwise.

Parameters:

construct (IConstruct) –

Return type:

bool

classmethod is_resource(construct)

Check whether the given construct is a Resource.

Parameters:

construct (IConstruct) –

Return type:

bool