class Canary (construct)
Language | Type name |
---|---|
![]() | Amazon.CDK.AWS.Synthetics.Canary |
![]() | github.com/aws/aws-cdk-go/awscdk/v2/awssynthetics#Canary |
![]() | software.amazon.awscdk.services.synthetics.Canary |
![]() | aws_cdk.aws_synthetics.Canary |
![]() | aws-cdk-lib » aws_synthetics » Canary |
Implements
IConstruct
, IDependable
, IResource
, IConnectable
Define a new Canary.
Example
import * as cdk from "aws-cdk-lib";
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_6_2,
memory: cdk.Size.mebibytes(1024), // 1024 MiB
});
Initializer
new Canary(scope: Construct, id: string, props: CanaryProps)
Parameters
- scope
Construct
- id
string
- props
Canary
Props
Construct Props
Name | Type | Description |
---|---|---|
runtime | Runtime | Specify the runtime version to use for the canary. |
test | Test | The type of test that you want your canary to run. |
active | boolean | Specifies whether this canary is to use active AWS X-Ray tracing when it runs. |
artifact | Artifacts | Canary Artifacts in S3 encryption mode. |
artifact | IKey | The KMS key used to encrypt canary artifacts. |
artifacts | Lifecycle [] | Lifecycle rules for the generated canary artifact bucket. |
artifacts | Artifacts | The s3 location that stores the data of the canary runs. |
canary | string | The name of the canary. |
cleanup? | Cleanup | Specify the underlying resources to be cleaned up when the canary is deleted. |
environment | { [string]: string } | Key-value pairs that the Synthetics caches and makes available for your canary scripts. |
failure | Duration | How many days should failed runs be retained. |
memory? | Size | The maximum amount of memory that the canary can use while running. |
provisioned | boolean | Whether to also delete the Lambda functions and layers used by this canary when the canary is deleted. |
role? | IRole | Canary execution role. |
schedule? | Schedule | Specify the schedule for how often the canary runs. |
security | ISecurity [] | The list of security groups to associate with the canary's network interfaces. |
start | boolean | Whether or not the canary should start after creation. |
success | Duration | How many days should successful runs be retained. |
time | Duration | How long the canary will be in a 'RUNNING' state. |
timeout? | Duration | How long the canary is allowed to run before it must stop. |
vpc? | IVpc | The VPC where this canary is run. |
vpc | Subnet | Where to place the network interfaces within the VPC. |
runtime
Type:
Runtime
Specify the runtime version to use for the canary.
test
Type:
Test
The type of test that you want your canary to run.
Use Test.custom()
to specify the test to run.
activeTracing?
Type:
boolean
(optional, default: false)
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.
artifactS3EncryptionMode?
Type:
Artifacts
(optional, default: Artifacts are encrypted at rest using an AWS managed key. ArtifactsEncryptionMode.KMS
is set if you specify artifactS3KmsKey
.)
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.
artifactS3KmsKey?
Type:
IKey
(optional, 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
.)
The KMS key used to encrypt canary artifacts.
artifactsBucketLifecycleRules?
Type:
Lifecycle
[]
(optional, default: no rules applied to the generated bucket.)
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.
artifactsBucketLocation?
Type:
Artifacts
(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.
cleanup?
⚠️ Deprecated: use provisionedResourceCleanup
Type:
Cleanup
(optional, default: Cleanup.NOTHING)
Specify the underlying resources to be cleaned up when the canary is deleted.
Using Cleanup.LAMBDA
will create a Custom Resource to achieve this.
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.
memory?
Type:
Size
(optional, default: Size.mebibytes(1024))
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.
provisionedResourceCleanup?
Type:
boolean
(optional, default: undefined - the default behavior is to not delete the Lambda functions and layers)
Whether to also delete the Lambda functions and layers used by this canary when the canary is deleted.
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:
ISecurity
[]
(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.
timeout?
Type:
Duration
(optional, default: the frequency of the canary is used as this value, up to a maximum of 900 seconds.)
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).
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:
Subnet
(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
Name | Type | Description |
---|---|---|
artifacts | IBucket | Bucket where data from each canary run is stored. |
canary | string | The canary ID. |
canary | string | The canary Name. |
canary | string | The state of the canary. |
connections | Connections | Access the Connections object. |
env | Resource | The environment this resource belongs to. |
node | Node | The tree node. |
role | IRole | Execution role associated with this Canary. |
stack | Stack | The 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:
Resource
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
Name | Description |
---|---|
apply | Apply the given removal policy to this resource. |
metric | Measure the Duration of a single canary run, in seconds. |
metric | Measure the number of failed canary runs over a given time period. |
metric | Measure the percentage of successful canary runs. |
to | Returns a string representation of this construct. |
applyRemovalPolicy(policy)
public applyRemovalPolicy(policy: RemovalPolicy): void
Parameters
- policy
Removal
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
).
metricDuration(options?)
public metricDuration(options?: MetricOptions): Metric
Parameters
- options
Metric
— - configuration options for the metric.Options
Returns
Measure the Duration of a single canary run, in seconds.
metricFailed(options?)
public metricFailed(options?: MetricOptions): Metric
Parameters
- options
Metric
— - configuration options for the metric.Options
Returns
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
Metric
— - configuration options for the metric.Options
Returns
Measure the percentage of successful canary runs.
toString()
public toString(): string
Returns
string
Returns a string representation of this construct.