banshee/cloud-collection/cloud/aws/https/cloudwatch-metric

One CloudWatch metric

Returns the newest value of one CloudWatch metric over the last hour, in the statistic chosen, and how old that value is, read through the CloudWatch API with an access key that may only read. The generic form: any namespace, any metric and its dimensions, all set on the probe (the CPU of an EC2 instance, the free storage of an RDS database, the messages of an SQS queue, a custom metric). Three watches are offered, each one set on the probe.

Versions

Generic: the CloudWatch API is one service, the same in every region. The collector asks for its version 2010-08-01 in the Query protocol, which AWS says it keeps supporting beside the JSON protocol its newer SDKs use.

How it works

GET https://monitoring.<aws:region>.amazonaws.com/?Action=GetMetricStatistics&Dimensions.member.1.Name=…&Dimensions.member.1.Value=…&EndTime=<now>&MetricName=<aws:metric>&Namespace=<aws:namespace>&Period=<aws:period>&StartTime=<now − 1 h>&Statistics.member.1=<aws:statistic>&Version=2010-08-01, signed by aws.sign (Signature Version 4, service monitoring). The answer is XML:

<GetMetricStatisticsResponse xmlns="http://monitoring.amazonaws.com/doc/2010-08-01/">
  <GetMetricStatisticsResult>
    <Label>CPUUtilization</Label>
    <Datapoints>
      <member><Timestamp>2026-10-28T08:05:00Z</Timestamp><Average>12.5</Average><Unit>Percent</Unit></member>
    </Datapoints>
  </GetMetricStatisticsResult>
  <ResponseMetadata><RequestId>…</RequestId></ResponseMetadata>
</GetMetricStatisticsResponse>

The dimensions are written one per line, Name=Value (InstanceId=i-0123456789abcdef0), and go in the request in that order. CloudWatch treats each combination of dimensions as its own metric: every dimension the metric is published with must be given, or it returns nothing.
value is the statistic of the newest point: CloudWatch gives the points in no order, and the collector looks for the one of the latest Timestamp.
age is the time from the start of that period to now, in minutes, against the poller's clock: a value that stops coming in shows by its age. With a period of 300 seconds, a value is commonly ten minutes old.
The times are written in UTC from the poller's clock, 2026-10-28T07:05:00Z and 2026-10-28T08:05:00Z.
No value in the hour stops the collector unreachable: CloudWatch answers a name, a namespace or a dimension it does not know with no point rather than with an error, and its message says so.
A region with other characters than lower-case letters, digits and hyphens, a period that is not a multiple of 60, or a dimension line without = stops the collector misconfigured before anything leaves.
A code 400, 401 or 403 stops the collector misconfigured, with the error code AWS writes (InvalidParameterValue, AccessDenied, SignatureDoesNotMatch…); a throttled request (Throttling), a code 500 or above, or any other code but 200 stops it unreachable.

The keys come from protocol:aws: the secret key never leaves the poller, only the signature it makes. The answer is not secret.

Prerequisites

An IAM user with an access key, or a role whose temporary keys are set with their session token, allowed this action and nothing else:

{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": "cloudwatch:GetMetricStatistics", "Resource": "*" }
  ]
}

The access key ID goes in protocol:aws:access-key-id, the secret key in protocol:aws:secret-access-key, the session token, for temporary keys only, in protocol:aws:session-token.

The poller reaches monitoring.<region>.amazonaws.com in HTTPS, and its clock is right within a few minutes: AWS refuses a request signed more than fifteen minutes away from its own time. The certificates of AWS are issued by public authorities: the profile "Standard" trusts them.
The names of the metrics, their dimensions and the statistics they support are in "AWS services that publish CloudWatch metrics", by service.

Variables

Name	Label	Says	Default
`aws:region`	Region	the AWS region of the metric, `eu-west-3`	—
`aws:namespace`	Namespace	the namespace, `AWS/EC2`	—
`aws:metric`	Metric	the name of the metric, `CPUUtilization`	—
`aws:dimensions`	Dimensions	one `Name=Value` per line; optional	—
`aws:statistic`	Statistic	`Average`, `Minimum`, `Maximum`, `Sum` or `SampleCount`	`Average`
`aws:period`	Period	the length of each period, in seconds, a multiple of 60	`300`

Outputs

Name	Label	Unit	Per instance
`value`	Value	that of the metric, which CloudWatch gives with each point and the collector does not declare	no
`age`	Age of the value	min	no

Watches

Name	Title	Kind	Defaults	Checked by default
`high`	Value too high	above a threshold, on `value`	no threshold: it raises nothing until thresholds are set on the probe	yes
`low`	Value too low	below a threshold, on `value`	no threshold	no
`stale`	Value not fresh	above a threshold, on `age`	warning above 30 min	yes

Limits

One metric per probe, and no percentile (ExtendedStatistics): the five statistics only.
A metric of a high resolution, published every second, is read by the minute at best.
The unit of the value is the metric's own (Percent, Bytes, Count); the screen shows none.
Not checked against an AWS account: the action, its parameters, their constraints and its fields are those of the Amazon CloudWatch API Reference ("GetMetricStatistics", "Datapoint") and of the Query protocol of AWS (Smithy, "AWS query protocol": the answer under GetMetricStatisticsResult, each item of a list under member); the reference no longer gives a sample of an XML answer.