CloudWatch

The CloudWatch API allows monitoring of AWS resources.

Metric Alarms

Alarms can be used to observe thresholds for data-of-interest, and trigger actions automatically. Please also consult the AWS docs on how alarms are evaluated in general. LocalStack currently supports metric-alarm evaluation with statistic and comparison-operator.

Metric Alarm Examples

Metric alarms evaluate the state, by taking into account the data points of E.g. you can create this alarm:

  1. $ awslocal cloudwatch put-metric-alarm \
  2.   --alarm-name my-alarm \
  3.   --metric-name Orders \
  4.   --namespace test \
  5.   --threshold 1 \
  6.   --comparison-operator LessThanThreshold \
  7.   --evaluation-periods 1 \
  8.   --period 30 \
  9.   --statistic Minimum \
  10.   --treat-missing notBreaching

You can now in separate terminal, watch the status of the alarm:

  1. $ watch "awslocal cloudwatch describe-alarms --alarm-names my-alarm | jq '.MetricAlarms[0].StateValue'"

And then add some data will cause a breach, and set the metric-alarm to state ALARM:

  1. $ awslocal cloudwatch put-metric-data --namespace test --metric-data '[{"MetricName": "Orders", "Value": -1}]'

The alarm state should change to ALARM after a few seconds, and eventually go back to OK - as we configured to treat missing data points as “not breaching”.

Metric Alarm with Action

Actions are triggered when the state of the alarm changes. For this you can configure alarm-actions, ok-actions and insufficient-data-actions. Currently, we only support SNS Topics. The topic must be created beforehand.

Here is an example with an alarm that will send a message to the defined topic once the alarm is in state ALARM. Note that the alarm-actions requires a valid ARN of an existing SNS topic.

  1. $ awslocal cloudwatch put-metric-alarm \
  2.   --alarm-name my-alarm \
  3.   --metric-name Orders \
  4.   --namespace test \
  5.   --threshold 50 \
  6.   --comparison-operator GreaterThanThreshold \
  7.   --evaluation-periods 1 \
  8.   --period 300 \
  9.   --statistic Maximum \
  10.   --treat-missing notBreaching \
  11.   --alarm-actions <topic-arn>

Known Limitations:

  • Anamoly detection, and extended-statics are not supported
  • unit values are ignored
  • composite-alarms are not evaluated
  • metric-streams are not supported

Last modified July 26, 2022: fix some typos (#214) (6ab8502d)