On this page:
cw-endpoint
12.1 Contracts
unit/ c
period/ c
statistic/ c
dimensions/ c
12.2 Putting metric data and getting statistics
datum
put-metric-data
get-metric-statistics
12.3 Listing metrics
metric
list-metrics
12.4 Alarms
alarm
describe-alarms
describe-alarms-for-metric
alarm-history
describe-alarm-history

12 CloudWatch (Monitoring)

 (require (planet gh/aws:1:=4/cw))

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?
Set the endpoint for the service. Defaults to (endpoint "monitoring.us-east-1.amazonaws.com" #t).

12.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?))

12.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.

12.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.

12.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.