Conditions
editConditions
editWhen 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
editA 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
editThere 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
editA 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
editThere 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
editA 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.
To enable groovy scripting for watches only, you can set
script.engine.groovy.inline.elasticsearch-watcher_watch: on
Using a Script Condition
editThe 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
editInline 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
editFile 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
editIndexed 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
editA 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" : { "inline" : "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 |
---|---|
|
The id of the watch that is currently executing. |
|
The time execution of this watch started. |
|
The time this watch was triggered. |
|
The time this watch was supposed to be triggered. |
|
Any metadata associated with the watch. |
|
The payload data loaded by the watch’s input. |
Compare Condition
editA 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
editThe 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:
The field name is the path to the execution context model |
|
The field name (here |
The path is a "dot-notation" expression that can reference the following variables in the watch context:
Name | Description |
---|---|
|
The id of the watch that is currently executing. |
|
The time execution of this watch started. |
|
The time this watch was triggered. |
|
The time this watch was supposed to be triggered. |
|
Any metadata associated with the watch. |
|
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 |
---|---|
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
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
editA 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
editThe 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 |
|
The field name (here |
|
The value of the field |
|
The value of the field |
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 |
---|---|
|
Any metadata associated with the watch. |
|
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 |
---|---|
|
Returns |
|
Returns |
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.