chaossearch_monitor Resource

Define a Search Analytics monitor using Terraform

The chaossearch_monitor resource defines a Search Analytics monitor that can watch for specific events or conditions, and send an alert or notification when the condition or event is detected. Monitors can be defined by a visual graph or by an extraction query. You must also create one or more destinations to specify the locations where the notifications are sent when the alert is triggered.

It can be helpful to create a monitor using the Search Analytics > Alerts UI and then export the monitor as a JSON file to see the format and options for the resource fields. For more information about monitors and fields, see Alert Monitors.

πŸ“˜

Monitors require user_name/password authentication.

When you define monitor resources in your Terraform files, you must specify a username/password login pair because API key authentication is not supported for monitors. If you specify only an API key and secret combination, the chaossearch_monitor resource fails and displays the error:
Error: Failed to authenticate => API Keys used with incompatible resource

Example Usage

The structure of a monitor resource that uses a query extraction as a trigger follows:

resource "chaossearch_monitor" "monitor" {
  name = "tf-monitor-name"
  type = "monitor"
  enabled = true
  schedule {
    period {
      interval = 1
      unit = "MINUTES"
    }
  }
  inputs {
    search {
      indices = ["example-view-name"]
      query = jsonencode({
        "size": 0,
        "aggregations": {
            "when": {
                "avg": {
                    "field": "Magnitude"
                },
                "meta": null
            }
        },
        "query": {
            "bool": {
                "filter": [
                    {
                        "range": {
                            "Period": {
                                "gte": "{{period_end}}||-1h",
                                "lte": "{{period_end}}",
                                "format": "epoch_millis"
                            }
                        }
                    }
                ]
            }
        }
      })
    }
  }
  triggers {
    name = "tf-provider-trigger"
    severity = "1"
    condition {
      script {
        lang = "painless"
        source = "ctx.results[0].hits.total.value > 1000"
      }
    }
    actions {
      name = "tf-provider-action"
      destination_id = "WyJkZXN0IiwienotdGYtcHJvdmlkZXItZGVzdC1jdXN0b20td2ViaG9vayJd"
      subject_template {
        lang = "mustache"
        source = "Monitor {{ctx.monitor.name}} Triggered"
      }
      message_template {
        lang = "mustache"
        source = "Monitor {{ctx.monitor.name}} just entered alert status. Please investigate the issue.\n- Trigger: {{ctx.trigger.name}}\n- Severity: {{ctx.trigger.severity}}\n- Period start: {{ctx.periodStart}}\n- Period end: {{ctx.periodEnd}}"
      }
      throttle_enabled = true
      throttle {
        value = 10
        unit = "MIN"
      }
    }
  }
}

πŸ“˜

NOTE

Multiple trigger blocks and action blocks can be defined in one resource. All fields are required except for throttle_enabled and throttle.

Argument Reference

FieldRequiredDescription
nameYesThe name of the monitor
typeYesSpecify monitor.
enabledYesSpecifies true or false to indicate whether the monitor is enabled.
scheduleYesSpecifies how frequently to run the monitor.
periodYesA container to specify the schedule information
intervalYesSpecifies the number of the schedule interval, such as 1, 2, 3, and so on.
unitYesSpecifies the units of the schedule interval, such as HOURS, MINUTES, DAYS.
inputsYesA container to specify the monitor definition
searchYesA container to specify the extraction query
indicesYesSpecify one or more Refinery views to use as the indexes for the extraction query or visualization.
queryYesA container specified as a jsonencode value that contains the monitor definition's JSON fields. Example:
query = jsonencode({ "query": { "match": { "sent_bytes": { "query": 100000 } } } })

To see examples of different query statements, you can export a monitor definition from the UI in JSON format.
triggersYesA container for the trigger definition(s)
nameYesThe name of the trigger for the associated monitor
severityYesSpecifies the severity level for the triggered condition where 1 is the highest severity and 5 is the lowest.
conditionYesFor an extraction query monitor, you specify an extraction query response, a trigger condition, and a trigger condition response, where you can specify and tune the trigger criteria.

For a visual query monitor, select the threshold to use for the trigger. You can choose options such as IS ABOVE, IS BELOW, or IS EXACTLY, and the value to use as the threshold. When the trigger condition is true, the trigger is activated.
scriptYesA container that defines the trigger condition for an extraction query monitor.
langYesSpecifies the language used for the script of the trigger condition. For example: painless
sourceYesSpecifies the trigger condition.
actionsYesA container that defines the action to take when the monitor is triggered.
nameYesThe name of the action being defined
destination_idYesThe internal ID (not a name) of the destination to which to send the alert notification. The destination must be created before you define this monitor/trigger.
subject_templateYesA container that specifies the subject of the notification
langYesSpecifies the language used for the script of the subject statement. For example, specify mustache to use mustache Web templates.
sourceYesSpecify the message subject string, with or without mustache Web templates.
message_templateYesA container that specifies the message body of the notification
langYesSpecifies the scripting language used for the message body. For example: mustache
sourceYesSpecify the message body content, with or without mustache Web templates.
throttle_enabledNoSpecifies whether you want to limit the number of notifications you receive within a given time frame.
throttleNoA container to specify the throttle rules
valueNoSpecify the throttle timeframe of 1 to 1440 minutes.
If a monitor checks a trigger condition every minute, you could receive one notification per minute. If you set throttling to 60 minutes, you receive no more than one notification per hour, even if the trigger condition is met throughout that hour.
unitNoSpecify the throttle temporal units such as MIN