10 CloudWatch (Monitoring)

package: aws

Among the Amazon Web Services, the CloudWatch API is the most quirky, least documented, and provides the fewest specific examples of making requests.

As a result, there are more likely to be mistakes or problems in this module. Your feedback or contributions to improve it are welcome.

Meanwhle, I’ve tried to focus mostly on put-metric-data, less on the other metrics procedures, and least of all on alarms and alarm history. (This is in line with the overall priority of this library, which is to support applications not “infrastucture.”)

parameter
(cw-endpoint) → endpoint?
(cw-endpoint v) → void?
v : endpoint?
= (endpoint "monitoring.us-east-1.amazonaws.com" #t)

The endpoint for the service.

parameter
(cw-region) → string?
(cw-region v) → void?
v : string?
= "us-east-1"

The region for the service.

10.1 Contracts

value
unit/c
:
(or/c 'None
      'Percent
      'Count
      'Seconds 'Microseconds 'Milliseconds
      'Bytes 'Kilobytes 'Megabytes 'Gigabytes 'Terabytes
      'Bits 'Kilobits 'Megabits 'Gigabits 'Terabits
      'Count/Second
      'Bytes/Second 'Kilobytes/Second 'Megabytes/Second
        'Gigabytes/Second 'Terabytes/Second
      'Bits/Second 'Kilobits/Second 'Megabits/Second
        'Gigabits/Second 'Terabits/Second)

A contract for the Units that CloudWatch accepts.

value
period/c :
(make-flat-contract
#:name 'non-zero-multiple-of-60
#:first-order (lambda (x)
(and (>= x 60)
(zero? (modulo x 60)))))

A contract for the period argument to get-metric-statistcs and describe-alarms-for-metric. CloudWatch requires the Period to be a non-zero multiple of 60 seconds.

value
statistic/c
: (or/c 'Sum 'Average 'Maximum 'Minimum 'SampleCount)

A contract for the Statistic values that CloudWatch knows about.

value
dimensions/c : (listof (list/c symbol? string?))

10.2 Putting metric data and getting statistics

struct
(struct datum ( metric-name
value
min
max
sum
sample-count
unit
timestamp
dimensions)
    #:extra-constructor-name make-datum)
  metric-name : string?
  value : (or/c #f number?)
  min : (or/c #f number?)
  max : (or/c #f number?)
  sum : (or/c #f number?)
  sample-count : (or/c #f number?)
  unit : unit/c
  timestamp : exact-integer?
  dimensions : dimensions/c

This struct is accepted by put-metric-data and returned by get-metric-statistics.

The timestamp member is an exact-integer?, like current-seconds, but all CloudWatch timestamps are UTC not local time.

procedure
(put-metric-data namespace data) → void?
namespace : string?
data : (listof datum?)

Put metric data to CloudWatch.

The value member must not be #f.

The min, max, sum, and sample-count members may be #f if you are putting individual values and will let CloudWatch do the aggregation, or, they may be non-#f if you are providing CloudWatch data you have already aggregated.

procedure
(get-metric-statistics #:metric-name metric-name
#:namespace namespace
#:statistics statistics
#:unit unit
#:start-time start-time
#:end-time end-time
[ #:period period
#:dimensions dimensions])
→ (listof datum?)
  metric-name : string?
  namespace : string?
  statistics : (listof statistic/c)
  unit : unit/c
  start-time : exact-integer?
  end-time : exact-integer?
  period : period/c = 60
  dimensions : dimensions/c = '()

Return statistics for a given metric metric-name in namespace. The statistics are returned as a list of datum structs.

The value member of datum will always be #f because CloudWatch only returns aggregated data. Even if you put individual values using put-metric-data, it will return only the aggregated statistics.

Whether the min, max, sum, and sample-count members of datum are #f, depends on whether you asked those statistics to be returned by specifying them in statistics. For example if statistics includes the symbol 'Sum, then the sum member will be non-#f, otherwise it will be #f.

Added in version 1.4 of package aws.

10.3 Listing metrics

struct
(struct metric (name namespace dimensions)
    #:extra-constructor-name make-metric)
  name : string?
  namespace : string?
  dimensions : dimensions/c

procedure
(list-metrics [ #:metric-name metric-name
#:namespace namespace
#:dimensions dimensions]) → (listof metric?)
  metric-name : (or/c #f string?) = #f
  namespace : (or/c #f string?) = #f
  dimensions : dimensions/c = '()

Return a list of metric? meeting the criteria.

10.4 Alarms

struct
(struct alarm ( name
description
arn
configuration-updated-timestamp
metric-name
namespace
threshold
comparison-operator
alarm-actions
ok-actions
insufficient-data-actions
state-value
state-reason
state-reason-data
state-updated-timestamp
period
actions-enabled
evaluation-periods
statistic
dimensions)
    #:extra-constructor-name make-alarm)
  name : string?
  description : string?
  arn : string?
  configuration-updated-timestamp : exact-integer?
  metric-name : string?
  namespace : string?
  threshold : number?
  comparison-operator : string?
  alarm-actions : xexpr?
  ok-actions : xexpr?
  insufficient-data-actions : xexpr?
  state-value : string?
  state-reason : string?
  state-reason-data : string?
  state-updated-timestamp : exact-integer?
  period : period/c
  actions-enabled : boolean?
  evaluation-periods : exact-nonnegative-integer
  statistic : string?
  dimensions : dimensions/c

A structure used by describe-alarms and describe-alarms-for-metric.

The configuration-updated-timestamp and state-updated-timestamp members are exact-integer? as with current-seconds, but remember the CloudWatch times are UTC not local time.

procedure
(describe-alarms [ #:alarm-name-prefix alarm-name-prefix
#:alarm-names alarm-names
#:state-value state-value])
→ (listof metric-alarm?)
  alarm-name-prefix : (or/c #f string?) = #f
  alarm-names : (listof string?) = '()
  state-value : (or/c #f 'OK 'ALARM 'INSUFFICIENT_DATA) = #f

Return the alarms meeting the criteria.

procedure
(describe-alarms-for-metric #:metric-name metric-name
#:namespace namespace
[ #:statistic statistic
#:unit unit
#:period period
#:dimensions dimensions])
→ (listof metric-alarm?)
  metric-name : string?
  namespace : string?
  statistic : (or/c #f statistic/c) = #f
  unit : (or/c #f unit/c) = #f
  period : (or/c #f period/c) = #f
  dimensions : dimensions/c = '()

Return the alarms meeting the criteria.

struct
(struct alarm-history (timestamp item-type name data summary)
    #:extra-constructor-name make-alarm-history)
  timestamp : exact-integer?
  item-type : symbol?
  name : string?
  data : xexpr?
  summary : string?

The data is JSON, which you will get as an xexpr? and need to parse yourself.

The timestamp member is an exact-integer?, like current-seconds, but all CloudWatch timestamps are UTC not local time.

procedure
(describe-alarm-history [ #:alarm-name alarm-name
#:start-date start-date
#:end-date end-date
#:history-type history-type])
→ (listof alarm-history?)
  alarm-name : (or/c #f string?) = #f
  start-date : (or/c #f exact-integer?) = #f
  end-date : (or/c #f exact-integer?) = #f
   history-type : (or/c #f 'ConfigurationUpdate 'StateUpdate 'Action)
= #f

Return the history for alarms meeting the criteria.

top ← prev up next →

1	Introduction
2	All Services
3	S3 (Storage)
4	SDB (Database)
5	SES (Email)
6	SNS (Notifications)
7	SQS (Queues)
8	Route 53 (DNS)
9	Dynamo DB
10	Cloud Watch (Monitoring)
11	Glacier (Archives)
12	Utilities
13	Unit tests
14	License

10.1	Contracts
10.2	Putting metric data and getting statistics
10.3	Listing metrics
10.4	Alarms