DocumentationChaosSearch Blog
Documentation
StatusHome Page
Start typing to search…

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

Field

Required

Description

name

Yes

The name of the monitor

type

Yes

Specify monitor.

enabled

Yes

Specifies true or false to indicate whether the monitor is enabled.

schedule

Yes

Specifies how frequently to run the monitor.

period

Yes

A container to specify the schedule information

interval

Yes

Specifies the number of the schedule interval, such as 1, 2, 3, and so on.

unit

Yes

Specifies the units of the schedule interval, such as HOURS, MINUTES, DAYS.

inputs

Yes

A container to specify the monitor definition

search

Yes

A container to specify the extraction query

indices

Yes

Specify one or more Refinery views to use as the indexes for the extraction query or visualization.

query

Yes

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

triggers

Yes

A container for the trigger definition(s)

name

Yes

The name of the trigger for the associated monitor

severity

Yes

Specifies the severity level for the triggered condition where 1 is the highest severity and 5 is the lowest.

condition

Yes

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

script

Yes

A container that defines the trigger condition for an extraction query monitor.

lang

Yes

Specifies the language used for the script of the trigger condition. For example: painless

source

Yes

Specifies the trigger condition.

actions

Yes

A container that defines the action to take when the monitor is triggered.

name

Yes

The name of the action being defined

destination_id

Yes

The 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_template

Yes

A container that specifies the subject of the notification

lang

Yes

Specifies the language used for the script of the subject statement. For example, specify mustache to use mustache Web templates.

source

Yes

Specify the message subject string, with or without mustache Web templates.

message_template

Yes

A container that specifies the message body of the notification

lang

Yes

Specifies the scripting language used for the message body. For example: mustache

source

Yes

Specify the message body content, with or without mustache Web templates.

throttle_enabled

No

Specifies whether you want to limit the number of notifications you receive within a given time frame.

throttle

No

A container to specify the throttle rules

value

No

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

unit

No

Specify the throttle temporal units such as MIN

Updated 8 days ago