Canary

class aws_cdk.aws_synthetics.Canary(scope, id, *, runtime, test, artifacts_bucket_location=None, canary_name=None, environment_variables=None, failure_retention_period=None, role=None, schedule=None, start_after_creation=None, success_retention_period=None, time_to_live=None)

Bases: aws_cdk.core.Resource

(experimental) Define a new Canary.

Stability

experimental

Parameters
  • scope (Construct) –

  • id (str) –

  • runtime (Runtime) – (experimental) Specify the runtime version to use for the canary.

  • test (Test) – (experimental) The type of test that you want your canary to run. Use Test.custom() to specify the test to run.

  • artifacts_bucket_location (Optional[ArtifactsBucketLocation]) – (experimental) 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]) – (experimental) 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

  • environment_variables (Optional[Mapping[str, str]]) – (experimental) 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]) – (experimental) How many days should failed runs be retained. Default: Duration.days(31)

  • role (Optional[IRole]) – (experimental) 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]) – (experimental) 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)’

  • start_after_creation (Optional[bool]) – (experimental) Whether or not the canary should start after creation. Default: true

  • success_retention_period (Optional[Duration]) – (experimental) How many days should successful runs be retained. Default: Duration.days(31)

  • time_to_live (Optional[Duration]) – (experimental) 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

Stability

experimental

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.DELETE), 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=None, dimensions_map=None, label=None, period=None, region=None, statistic=None, unit=None)

(experimental) 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 (Optional[Mapping[str, Any]]) – (deprecated) Dimensions of the metric. Default: - No dimensions.

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

  • statistic (Optional[str]) – What function to use for aggregating. Can be one of the following: - “Minimum” | “min” - “Maximum” | “max” - “Average” | “avg” - “Sum” | “sum” - “SampleCount | “n” - “pNN.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

Stability

experimental

Return type

Metric

metric_failed(*, account=None, color=None, dimensions=None, dimensions_map=None, label=None, period=None, region=None, statistic=None, unit=None)

(experimental) 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 (Optional[Mapping[str, Any]]) – (deprecated) Dimensions of the metric. Default: - No dimensions.

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

  • statistic (Optional[str]) – What function to use for aggregating. Can be one of the following: - “Minimum” | “min” - “Maximum” | “max” - “Average” | “avg” - “Sum” | “sum” - “SampleCount | “n” - “pNN.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

Stability

experimental

Return type

Metric

metric_success_percent(*, account=None, color=None, dimensions=None, dimensions_map=None, label=None, period=None, region=None, statistic=None, unit=None)

(experimental) 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 (Optional[Mapping[str, Any]]) – (deprecated) Dimensions of the metric. Default: - No dimensions.

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

  • statistic (Optional[str]) – What function to use for aggregating. Can be one of the following: - “Minimum” | “min” - “Maximum” | “max” - “Average” | “avg” - “Sum” | “sum” - “SampleCount | “n” - “pNN.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

Stability

experimental

Return type

Metric

to_string()

Returns a string representation of this construct.

Return type

str

Attributes

artifacts_bucket

(experimental) Bucket where data from each canary run is stored.

Stability

experimental

Return type

IBucket

canary_id

(experimental) The canary ID.

Stability

experimental

Attribute

true

Return type

str

canary_name

(experimental) The canary Name.

Stability

experimental

Attribute

true

Return type

str

canary_state

(experimental) The state of the canary.

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

Stability

experimental

Attribute

true

Return type

str

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.

Return type

ResourceEnvironment

node

The construct tree node associated with this construct.

Return type

ConstructNode

role

(experimental) Execution role associated with this Canary.

Stability

experimental

Return type

IRole

stack

The stack in which this resource is defined.

Return type

Stack

Static Methods

classmethod is_construct(x)

Return whether the given object is a Construct.

Parameters

x (Any) –

Return type

bool

classmethod is_resource(construct)

Check whether the given construct is a Resource.

Parameters

construct (IConstruct) –

Return type

bool