State change events

On top of standard telemetry, Geopoiesis runs can be monitored by subscribing to CloudWatch Events. Each run state change triggers an event, whose payload is the same as passed to initialization hooks. In order to subscribe to those, you will need to create a CloudWatch Events rule. In order to construct your pattern, here is what you need to know about Geopoiesis events:

  • source is always set to geopoiesis.io;

  • detail-type is always set to Geopoiesis run state change;

  • resources array always consists of just element, which is the name of your scope prefixed by scope:;

An example pattern to capture all finished runs targeting the tracked branch could look like this:

target.json
{
"source": [
"geopoiesis.io"
],
"detail-type": [
"Geopoiesis run state change"
],
"detail": {
"finished": [true],
"type": ["TRACKED_CHANGE"]
}
}

In order to start capturing events matched by the above pattern, you will need to create a target for the rule, which is normally an SNS topic, an SQS queue or a Lambda function. If this is your first time dealing with CloudWatch Events, please study some of the tutorials provided by AWS.

State change events are not generated for runs that have no chance of modifying Terraform state, i.e. for CI runs on non-tracked branches.

Use case

The main use case of event notifications is integration with third party tools. For example, you may want to notify your team Slack channel every time an infrastructure change is started and/or finished. You can also log the event either purely for auditing purposes, or to provide context to other data, like your StatsD metrics.