From version 5.0 onward, Watcher is part of X-Pack. For more information, see Alerting on cluster and index events.

› ›

Condition

When a watch is triggered, its condition determines whether or not to execute its actions. Watcher supports four condition types: always, never, script and compare.

If you omit the condition definition from a watch, the condition defaults to always.

When a condition is evaluated, it has full access to the watch execution context, including the watch payload (ctx.payload.*). The script, compare and array-compare conditions can use the data in the payload to determine whether or not the necessary conditions have been met.

Always Condition

edit

A watch condition that always evaluates to true. When you use the always condition, the watch’s actions are always executed when the watch is triggered, unless the action is throttled.

If you omit the condition definition from a watch, the condition defaults to always.

You can use the always condition to configure watches that should run on a set schedule, such as:

"At noon every Friday, send a status report email to sys.admin@example.com"

To configure this watch, you define an input that loads the status data, set a schedule that triggers every Friday, set the condition to always, and configure an email action to send the status data.

Using the Always Condition

edit

There are no attributes to specify for the always condition. To use the always condition, you simply specify the condition type and associate it with an empty object:

"condition" : {
  "always" : {}
}

Never Condition

edit

A watch condition that always evaluates to false. If you use this condition, the watch’s actions are never executed. The watch’s input is executed, a record is added to the watch history, and processing stops. This condition is generally only used for testing.

Using the Never Condition

edit

There are no attributes to specify for the never condition. To use the never condition, you simply specify the condition type and associate it with an empty object:

PUT _watcher/watch/my-watch
{
  ...

  "condition" : {
    "never" : {}
  }
  ...
}

Script Condition

edit

A watch condition that evaluates a script. The default scripting language is groovy. You can use any of the scripting languages supported by Elasticsearch as long as the language supports evaluating expressions to Boolean values. Note that the mustache and expression languages are too limited to be used by this condition. For more information, see Scripting in the Elasticsearch Reference.

You must explicitly enable dynamic scripts in elasticsearch.yml to use inline or indexed scripts.

Using a Script Condition

edit

The following snippet configures an inline script condition that always returns true:

"condition" : {
  "script" : "return true"
}

This example defines a script as a simple string. This format is actually a shortcut for defining an inline groovy script. The formal definition of a script is an object that specifies the script type and optional language and parameter values. If the lang attribute is omitted, the language defaults to groovy. Elasticsearch supports three script types: Inline, File, and Indexed.

For example, the following snippet shows a formal definition of an inline script that explicitly specifies the language and defines a single script parameter, result.

"condition" : {
  "script" : {
    "inline" : "return result",
    "lang" : "groovy",
    "params" : {
      "result" : true
    }
  }
}

Inline Scripts

edit

Inline scripts are scripts that are defined in the condition itself. The following snippet shows the formal configuration of a simple groovy script that always returns true.

"condition" : {
  "script" : {
    "inline" : "return true"
  }
}

File Scripts

edit

File scripts are scripts that are defined in files stored in the config/scripts directory. The following snippet shows how to refer to the my_script.groovy file:

"condition" : {
    "script" : {
      "file" : "my_script"
    }
  }

As with Inline scripts, you can also specify the script language and parameters:

"condition" : {
  "script" : {
    "file" : "my_script",
    "lang" : "javascript",
    "params" : {
      "result" : true
    }
  }
}

Indexed Scripts

edit

Indexed scripts refer to scripts that were indexed in Elasticsearch. The following snippet shows how to refer to a script by its id:

"condition" : {
  "script" : {
    "id" : "my_script"
  }
}

As with File and Inline scripts, you can also specify the script language and parameters:

"condition" : {
  "script" : {
    "id" : "my_script",
    "lang" : "javascript",
    "params" : { "color" : "red" }
  }
}

Accessing the Watch Payload

edit

A script can access the current watch execution context, including the payload data, as well as any parameters passed in through the condition definition.

For example, the following snippet defines a watch that uses a search input and uses a script condition to check if the number of hits is above a specified threshold:

{
  "input" : {
    "search" : {
      "indices" : "log-events",
      "body" : {
        "size" : 0,
        "query" : { "match" : { "status" : "error" } }
      }
    }
  },
  "condition" : {
    "script" : {
      "script" : "return ctx.payload.hits.total > threshold",
      "params" : {
        "threshold" : 5
      }
    }
  }
  ...
}

When you’re using a scripted condition to evaluate an Elasticsearch response, keep in mind that the fields in the response are no longer in their native data types. For example, the @timestamp in the response is a string, rather than a DateTime. To compare the response @timestamp against the ctx.execution_time, you need to parse the @timestamp string into a DateTime. For example:

org.elasticsearch.common.joda.time.DateTime.parse(@timestamp)

You can reference the following variables in the watch context:

Name	Description
`ctx.watch_id`	The id of the watch that is currently executing.
`ctx.execution_time`	The time execution of this watch started.
`ctx.trigger.triggered_time`	The time this watch was triggered.
`ctx.trigger.scheduled_time`	The time this watch was supposed to be triggered.
`ctx.metadata.*`	Any metadata associated with the watch.
`ctx.payload.*`	The payload data loaded by the watch’s input.

Compare Condition

edit

A watch condition that simply compares a value in the Watch Execution Context Model to given value. The value in the model is identified by a path within that model.

While limited in its functionality, the advantage of this condition over the Script Condition is that you do not have to enable dynamic scripting to use compare conditions.

Using a Compare Condition

edit

The following snippet configures a compare condition that returns true if the number of the total hits in the search result (typically loaded by the Search Input) is higher or equals 5:

{
  ...

  "condition" : {
    "compare" : {
      "ctx.payload.hits.total" : { 
        "gte" : 5 
      }
  }
  ...
}

	The field name is the path to the execution context model
	The field name (here `gte`) is the comparison operator, and the value is the value to compare to.

The path is a "dot-notation" expression that can reference the following variables in the watch context:

Name	Description
`ctx.watch_id`	The id of the watch that is currently executing.
`ctx.execution_time`	The time execution of this watch started.
`ctx.trigger.triggered_time`	The time this watch was triggered.
`ctx.trigger.scheduled_time`	The time this watch was supposed to be triggered.
`ctx.metadata.*`	Any metadata associated with the watch.
`ctx.payload.*`	The payload data loaded by the watch’s input.

You can reference entries in arrays using their zero-based array indices. For example, to access the third element of the ctx.payload.hits.hits array, use ctx.payload.hits.hits.2.

The comparison operator can be any one of the following:

Name	Description
`eq`	Returns `true` when the resolved value equals the given one (applies to numeric, string, list, object and values)
`not_eq`	Returns `true` when the resolved value does not equal the given one (applies to numeric, string, list, object and null values)
`gt`	Returns `true` when the resolved value is greater than the given one (applies to numeric and string values)
`gte`	Returns `true` when the resolved value is greater/equal than/to the given one (applies to numeric and string values)
`lt`	Returns `true` when the resolved value is less than the given one (applies to numeric and string values)
`lte`	Returns `true` when the resolved value is less/equal than/to the given one (applies to numeric and string values)

When dealing with dates/times, the specified value can hold date math expression in the form of <{expression}>. For example, one can compare the watch execution time as follows:

{
  ...

  "condition" : {
    "compare" : {
      "ctx.execution_time" : {
        "gte" : "<{now-5m}>"
      }
  }
  ...
}

It is also possible to compare one value in the context model to another value in the same model. This can be done by specifying the compared value as a path in the form of {{path}}. The following snippet shows a condition that compares two values in the payload

{
  ...

  "condition" : {
    "compare" : {
      "ctx.payload.aggregations.status.buckets.error.doc_count" : {
        "not_eq" : "{{ctx.payload.aggregations.handled.buckets.true.doc_count}}"
      }
  }
  ...
}

Array Compare Condition

edit

A watch condition that compares an array of values in the Watch Execution Context Model to a given value. The values in the model are identified by a path within that model.

Using an Array Compare Condition

edit

The following snippet configures an array_compare condition that returns true if there is at least one bucket in the aggregations buckets that has a doc_count higher than or equal to 25:

{
  ...

  "condition": {
    "array_compare": {
      "ctx.payload.aggregations.top_tweeters.buckets" : { 
        "path": "doc_count", 
        "gte": { 
          "value": 25, 
          "quantifier": "some" 
        }
      }
    }
  }
  ...
}

	The field name is the path to the array (array path) in the execution context model
	The value of the field `path` (here `doc_count`) is the path to the value for each element of the array that the comparison operator will be applied to
	The field name (here `gte`) is the name of the comparison operator
	The value of the field `value` in the comparison operator object is the comparison value
	The value of the field `quantifier` (`all` or `some`) specifies whether the comparison must be true for all or for at least one of the values to evaluate the comparison to true

The path element is optional and will default to "" if not specified.

The quantifier element is optional and will default to "some" if not specified.

The array path is a "dot-notation" expression that can reference the following variables in the watch context:

Name	Description
`ctx.metadata.*`	Any metadata associated with the watch.
`ctx.payload.*`	The payload data loaded by the watch’s input.

This array path must resolve to an array.

The comparison operator can be any one of the operators supported by the Compare Condition.

The quantifier operator can be any one of the following:

Name	Description
`all`	Returns `true` when the resolved value compares `true` according to the comparison operator for all the elements in the array
`some`	Returns `true` when the resolved value compares `true` according to the comparison operator for at least one element in the array

If the array is empty, all causes the comparison operator to evaluate to true and some causes the comparison operator to evaluate to false.

It is also possible to use date math expressions and values in the context model as in the Compare Condition.

« Trigger Actions »