[ aws . synthetics ]

describe-canaries

Description

This operation returns a list of the canaries in your account, along with full details about each canary.

This operation does not have resource-level authorization, so if a user is able to use DescribeCanaries , the user can see all of the canaries in the account. A deny policy can only be used to restrict access to all canaries. It cannot be used on specific resources.

See also: AWS API Documentation

See ‘aws help’ for descriptions of global parameters.

Synopsis

  describe-canaries
[--next-token <value>]
[--max-results <value>]
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]

Options

--next-token (string)

A token that indicates that there is more data available. You can use this token in a subsequent operation to retrieve the next set of results.

--max-results (integer)

Specify this parameter to limit how many canaries are returned each time you use the DescribeCanaries operation. If you omit this parameter, the default of 100 is used.

--cli-input-json | --cli-input-yaml (string) Reads arguments from the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with --cli-input-yaml.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. Similarly, if provided yaml-input it will print a sample input YAML that can be used with --cli-input-yaml. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

See ‘aws help’ for descriptions of global parameters.

Output

Canaries -> (list)

Returns an array. Each item in the array contains the full information about one canary.

(structure)

This structure contains all information about one canary in your account.

Id -> (string)

The unique ID of this canary.

Name -> (string)

The name of the canary.

Code -> (structure)

This structure contains information about the canary’s Lambda handler and where its code is stored by CloudWatch Synthetics.

SourceLocationArn -> (string)

The ARN of the Lambda layer where Synthetics stores the canary script code.

Handler -> (string)

The entry point to use for the source code when running the canary.

ExecutionRoleArn -> (string)

The ARN of the IAM role used to run the canary. This role must include lambda.amazonaws.com as a principal in the trust policy.

Schedule -> (structure)

A structure that contains information about how often the canary is to run, and when these runs are to stop.

Expression -> (string)

A rate expression that defines how often the canary is to run. The syntax is rate(*number unit* ) . unit can be minute , minutes , or hour .

For example, rate(1 minute) runs the canary once a minute, rate(10 minutes) runs it once every 10 minutes, and rate(1 hour) runs it once every hour.

Specifying rate(0 minute) or rate(0 hour) is a special value that causes the canary to run only once when it is started.

DurationInSeconds -> (long)

How long, in seconds, for the canary to continue making regular runs after it was created. The runs are performed according to the schedule in the Expression value.

RunConfig -> (structure)

A structure that contains information about a canary run.

TimeoutInSeconds -> (integer)

How long the canary is allowed to run before it must stop.

MemoryInMB -> (integer)

The maximum amount of memory available to the canary while it is running, in MB. This value must be a multiple of 64.

ActiveTracing -> (boolean)

Displays whether this canary run used active AWS X-Ray tracing.

SuccessRetentionPeriodInDays -> (integer)

The number of days to retain data about successful runs of this canary.

FailureRetentionPeriodInDays -> (integer)

The number of days to retain data about failed runs of this canary.

Status -> (structure)

A structure that contains information about the canary’s status.

State -> (string)

The current state of the canary.

StateReason -> (string)

If the canary has insufficient permissions to run, this field provides more details.

StateReasonCode -> (string)

If the canary cannot run or has failed, this field displays the reason.

Timeline -> (structure)

A structure that contains information about when the canary was created, modified, and most recently run.

Created -> (timestamp)

The date and time the canary was created.

LastModified -> (timestamp)

The date and time the canary was most recently modified.

LastStarted -> (timestamp)

The date and time that the canary’s most recent run started.

LastStopped -> (timestamp)

The date and time that the canary’s most recent run ended.

ArtifactS3Location -> (string)

The location in Amazon S3 where Synthetics stores artifacts from the runs of this canary. Artifacts include the log file, screenshots, and HAR files.

EngineArn -> (string)

The ARN of the Lambda function that is used as your canary’s engine. For more information about Lambda ARN format, see Resources and Conditions for Lambda Actions .

RuntimeVersion -> (string)

Specifies the runtime version to use for the canary. For more information about runtime versions, see Canary Runtime Versions .

VpcConfig -> (structure)

If this canary is to test an endpoint in a VPC, this structure contains information about the subnets and security groups of the VPC endpoint. For more information, see Running a Canary in a VPC .

VpcId -> (string)

The IDs of the VPC where this canary is to run.

SubnetIds -> (list)

The IDs of the subnets where this canary is to run.

(string)

SecurityGroupIds -> (list)

The IDs of the security groups for this canary.

(string)

Tags -> (map)

The list of key-value pairs that are associated with the canary.

key -> (string)

value -> (string)

NextToken -> (string)

A token that indicates that there is more data available. You can use this token in a subsequent DescribeCanaries operation to retrieve the next set of results.