feat: support pulling from cloudwatch metrics

This commit introduces a new submodule, `cloudwatch_metrics`. Similar to
our API snapshot functionality, we set up a eventbridge rule that
periodically triggers the lambda with a custom payload.

This payload tells the lambda what metrics to scrape for. Callers of
this module can configure metric collection through the `period`,
`interval`, `delay` and `filters` variables.

Users must provide a list of filters. Each filter must have a namespace,
and an optional set of metric names and dimensions.

Co-authored-by: Ben Drucker <bvdrucker@gmail.com>

Author: João Taveira Araújo

modules/cloudwatch_metrics/README.md

@@ -0,0 +1,89 @@
+# Observe Lambda CloudWatch Metrics Configuration
+
+This module configures the Observe Lambda to periodically pull metrics from AWS
+CloudWatch. While configured in a similar manner to the "snapshot" module, the
+CloudWatch Metrics functionality is distinct in that it does not simply log
+responses to raw API calls. The Lambda takes a simplified configuration for
+querying sets of metrics, and produces a list of metrics more readily consumed
+than the raw API response from AWS.
+
+This module sets up an event rule in EventBridge which triggers the Observe
+Lambda periodically. Additionally, the module will add a policy to the existing
+Lambda to ensure that all requested endpoints are accessible.
+
+## Usage
+
+```hcl
+module "observe_lambda" {
+  source           = "observeinc/lambda/aws"
+  observe_customer = var.observe_customer
+  observe_token    = var.observe_token
+  observe_domain   = var.observe_domain
+  name             = random_pet.run.id
+}
+
+module "cloudwatch_metrics" {
+  source = "observeinc/lambda/aws//modules/cloudwatch_metrics"
+  lambda = module.observe_lambda
+
+  filters = [
+    {
+        namespace = "AWS/RDS"
+    }
+  ]
+}
+```
+
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 2.68 |
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 2.68 |
+
+## Modules
+
+No modules.
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [aws_cloudwatch_event_rule.trigger](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_event_rule) | resource |
+| [aws_cloudwatch_event_target.target](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_event_target) | resource |
+| [aws_iam_policy.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_policy) | resource |
+| [aws_iam_role_policy_attachment.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
+| [aws_lambda_permission.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lambda_permission) | resource |
+| [aws_arn.function](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/arn) | data source |
+| [aws_arn.role](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/arn) | data source |
+| [aws_iam_policy_document.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_delay"></a> [delay](#input\_delay) | Collection delay in seconds. This delay accounts for the lag in metrics availability via Cloudwatch API. | `number` | `300` | no |
+| <a name="input_eventbridge_name_prefix"></a> [eventbridge\_name\_prefix](#input\_eventbridge\_name\_prefix) | Prefix used for eventbridge rule | `string` | `"observe-lambda-metrics-"` | no |
+| <a name="input_eventbridge_schedule_event_bus_name"></a> [eventbridge\_schedule\_event\_bus\_name](#input\_eventbridge\_schedule\_event\_bus\_name) | Event Bus for EventBridge scheduled events | `string` | `"default"` | no |
+| <a name="input_filters"></a> [filters](#input\_filters) | List of filters. | <pre>list(object({<br>    namespace    = string<br>    list_mode    = optional(string)<br>    metric_names = optional(list(string))<br>    dimensions = optional(list(object({<br>      name  = string<br>      value = optional(string)<br>    })))<br>  }))</pre> | n/a | yes |
+| <a name="input_iam_name_prefix"></a> [iam\_name\_prefix](#input\_iam\_name\_prefix) | Prefix used for all created IAM roles and policies | `string` | `""` | no |
+| <a name="input_interval"></a> [interval](#input\_interval) | Interval in seconds between collection runs. Use a multiple of period to avoid gaps. | `number` | `300` | no |
+| <a name="input_lambda"></a> [lambda](#input\_lambda) | Observe Lambda module | <pre>object({<br>    lambda_function = object({<br>      arn  = string<br>      role = string<br>    })<br>  })</pre> | n/a | yes |
+| <a name="input_period"></a> [period](#input\_period) | Period in seconds between metric data points. Must be a multiple of 60. | `number` | `60` | no |
+| <a name="input_statement_id_prefix"></a> [statement\_id\_prefix](#input\_statement\_id\_prefix) | Prefix used for Lambda permission statement ID | `string` | `""` | no |
+
+## Outputs
+
+No outputs.
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+
+## License
+
+Apache 2 Licensed. See LICENSE for full details.

modules/cloudwatch_metrics/main.tf

@@ -0,0 +1,65 @@
+locals {
+  iam_name_prefix     = var.iam_name_prefix != "" ? var.iam_name_prefix : var.eventbridge_name_prefix
+  statement_id_prefix = var.statement_id_prefix != "" ? var.statement_id_prefix : local.iam_name_prefix
+  role_resource       = split("/", data.aws_arn.role.resource)
+  role_name           = local.role_resource[length(local.role_resource) - 1]
+}
+
+data "aws_arn" "role" {
+  arn = var.lambda.lambda_function.role
+}
+
+data "aws_arn" "function" {
+  arn = var.lambda.lambda_function.arn
+}
+
+data "aws_iam_policy_document" "this" {
+  statement {
+    actions = [
+      "cloudwatch:ListMetrics",
+      "cloudwatch:GetMetricData",
+    ]
+
+    resources = [
+      "*",
+    ]
+  }
+}
+
+resource "aws_iam_policy" "this" {
+  name_prefix = local.iam_name_prefix
+  policy      = data.aws_iam_policy_document.this.json
+}
+
+resource "aws_iam_role_policy_attachment" "this" {
+  role       = local.role_name
+  policy_arn = aws_iam_policy.this.arn
+}
+
+resource "aws_cloudwatch_event_rule" "trigger" {
+  name_prefix         = var.eventbridge_name_prefix
+  description         = "Periodically trigger Observe Lambda to collect CloudWatch metrics"
+  schedule_expression = "cron(${var.interval / 60} * * * ? *)"
+  event_bus_name      = var.eventbridge_schedule_event_bus_name
+}
+
+resource "aws_cloudwatch_event_target" "target" {
+  arn  = var.lambda.lambda_function.arn
+  rule = aws_cloudwatch_event_rule.trigger.name
+  input = jsonencode({
+    metrics = {
+      period   = var.period
+      interval = var.interval
+      delay    = var.delay
+      filters  = var.filters
+    }
+  })
+}
+
+resource "aws_lambda_permission" "this" {
+  statement_id_prefix = local.statement_id_prefix
+  action              = "lambda:InvokeFunction"
+  principal           = "events.amazonaws.com"
+  function_name       = trimprefix(data.aws_arn.function.resource, "function:")
+  source_arn          = aws_cloudwatch_event_rule.trigger.arn
+}

modules/cloudwatch_metrics/outputs.tf

@@ -0,0 +1,79 @@
+variable "lambda" {
+  description = "Observe Lambda module"
+  type = object({
+    lambda_function = object({
+      arn  = string
+      role = string
+    })
+  })
+}
+
+variable "iam_name_prefix" {
+  description = "Prefix used for all created IAM roles and policies"
+  type        = string
+  nullable    = false
+  default     = ""
+}
+
+variable "statement_id_prefix" {
+  description = "Prefix used for Lambda permission statement ID"
+  type        = string
+  nullable    = false
+  default     = ""
+}
+
+variable "eventbridge_name_prefix" {
+  description = "Prefix used for eventbridge rule"
+  type        = string
+  nullable    = false
+  default     = "observe-lambda-metrics-"
+}
+
+variable "interval" {
+  description = "Interval in seconds between collection runs. Use a multiple of period to avoid gaps."
+  type        = number
+  nullable    = false
+  default     = 300
+  validation {
+    condition     = var.interval >= 60 && var.interval < 3600
+    error_message = "interval must be greater than or equal to 60 and less than 3600."
+  }
+}
+
+variable "period" {
+  description = "Period in seconds between metric data points. Must be a multiple of 60."
+  type        = number
+  nullable    = false
+  default     = 60
+  validation {
+    condition     = var.period >= 60 && var.period % 60 == 0
+    error_message = "period must be at least 60 seconds, and a multiple of 60."
+  }
+}
+
+variable "delay" {
+  description = "Collection delay in seconds. This delay accounts for the lag in metrics availability via Cloudwatch API."
+  type        = number
+  nullable    = false
+  default     = 300
+}
+
+variable "filters" {
+  description = "List of filters."
+  type = list(object({
+    namespace    = string
+    list_mode    = optional(string)
+    metric_names = optional(list(string))
+    dimensions = optional(list(object({
+      name  = string
+      value = optional(string)
+    })))
+  }))
+}
+
+variable "eventbridge_schedule_event_bus_name" {
+  description = "Event Bus for EventBridge scheduled events"
+  type        = string
+  nullable    = false
+  default     = "default"
+}

modules/cloudwatch_metrics/variables.tf

@@ -0,0 +1,10 @@
+terraform {
+  required_version = ">= 1.3"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 2.68"
+    }
+  }
+}