Package software.amazon.awscdk.services.synthetics

Interface CanaryProps

All Superinterfaces:
software.amazon.jsii.JsiiSerializable
All Known Implementing Classes:
CanaryProps.Jsii$Proxy
@Generated(value="jsii-pacmak/1.109.0 (build c221850)", date="2025-03-14T03:25:06.599Z") @Stability(Stable) public interface CanaryProps extends software.amazon.jsii.JsiiSerializable
Properties for a canary.

Example: 

 import software.amazon.awscdk.*;
 Canary canary = Canary.Builder.create(this, "MyCanary")
         .schedule(Schedule.rate(Duration.minutes(5)))
         .test(Test.custom(CustomTestOptions.builder()
                 .code(Code.fromAsset(join(__dirname, "canary")))
                 .handler("index.handler")
                 .build()))
         .runtime(Runtime.SYNTHETICS_NODEJS_PUPPETEER_6_2)
         .memory(Size.mebibytes(1024))
         .build();

  • Method Details

    • getRuntime

      @Stability(Stable) @NotNull Runtime getRuntime()
      Specify the runtime version to use for the canary.

      See Also:

    • getTest

      @Stability(Stable) @NotNull Test getTest()
      The type of test that you want your canary to run.

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

    • getActiveTracing

      @Stability(Stable) @Nullable default Boolean getActiveTracing()
      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

      See Also:

    • getArtifactS3EncryptionMode

      @Stability(Stable) @Nullable default ArtifactsEncryptionMode getArtifactS3EncryptionMode()
      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`.

      See Also:

    • getArtifactS3KmsKey

      @Stability(Stable) @Nullable default IKey getArtifactS3KmsKey()
      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`.

    • getArtifactsBucketLifecycleRules

      @Stability(Stable) @Nullable default List<LifecycleRule> getArtifactsBucketLifecycleRules()
      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.

    • getArtifactsBucketLocation

      @Stability(Stable) @Nullable default ArtifactsBucketLocation getArtifactsBucketLocation()
      The s3 location that stores the data of the canary runs.

      Default: - A new s3 bucket will be created without a prefix.

    • getCanaryName

      @Stability(Stable) @Nullable default String getCanaryName()
      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

      See Also:

    • getCleanup

      @Stability(Deprecated) @Deprecated @Nullable default Cleanup getCleanup()
      Deprecated.
      use provisionedResourceCleanup
      (deprecated) 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

    • getEnvironmentVariables

      @Stability(Stable) @Nullable default Map<String,String> getEnvironmentVariables()
      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.

    • getFailureRetentionPeriod

      @Stability(Stable) @Nullable default Duration getFailureRetentionPeriod()
      How many days should failed runs be retained.

      Default: Duration.days(31)

    • getMemory

      @Stability(Stable) @Nullable default Size getMemory()
      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)

    • getProvisionedResourceCleanup

      @Stability(Stable) @Nullable default Boolean getProvisionedResourceCleanup()
      Whether to also delete the Lambda functions and layers used by this canary when the canary is deleted.

      Default: undefined - the default behavior is to not delete the Lambda functions and layers

    • getRole

      @Stability(Stable) @Nullable default IRole getRole()
      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'.

      See Also:

    • getSchedule

      @Stability(Stable) @Nullable default Schedule getSchedule()
      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)'

    • getSecurityGroups

      @Stability(Stable) @Nullable default List<ISecurityGroup> getSecurityGroups()
      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.

    • getStartAfterCreation

      @Stability(Stable) @Nullable default Boolean getStartAfterCreation()
      Whether or not the canary should start after creation.

      Default: true

    • getSuccessRetentionPeriod

      @Stability(Stable) @Nullable default Duration getSuccessRetentionPeriod()
      How many days should successful runs be retained.

      Default: Duration.days(31)

    • getTimeout

      @Stability(Stable) @Nullable default Duration getTimeout()
      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.

    • getTimeToLive

      @Stability(Stable) @Nullable default Duration getTimeToLive()
      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

    • getVpc

      @Stability(Stable) @Nullable default IVpc getVpc()
      The VPC where this canary is run.

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

      Default: - Not in VPC

    • getVpcSubnets

      @Stability(Stable) @Nullable default SubnetSelection getVpcSubnets()
      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

    • builder

      @Stability(Stable) static CanaryProps.Builder builder()
      Returns:
      a CanaryProps.Builder of CanaryProps