OpenSearch/watcher/docs/customizing-watches.asciidoc

[[customizing-watches]]
== Customizing Watches

Now that you've seen how to set up simple watches to <<watch-log-data, watch your log data>>
and <<watch-cluster-status, monitor your cluster health>>, let's take a closer look at how 
you can customize a watch by modifying its <<changing-inputs, inputs>>,
<<changing-conditions, conditions>>, <<using-transforms, transforms>>, and
<<customizing-actions, actions>>.

[[changing-inputs]]
=== Changing Inputs
Watcher supports three types of inputs <<loading-static-data, simple>>,
<<loading-search-results, search>>, and <<loading-http-data, http>>.

[[loading-static-data]]
==== Loading Static Data with the Simple Input

To load static data into the watch payload for testing purposes, you can use the
<<input-simple, simple>> input. For example, the following input stores three fields in the
payload:

[source,js]
-------------------------------------------------- 
"input" : { 
  "simple" : {
    "color"  : "red",
    "status" : "error",
    "count"  : 3
  } 
}
--------------------------------------------------

[[loading-search-results]]
==== Loading Search Results with the Search Input

To load search results into the watch payload, you use the `search` input. In addition to simple
match queries like the one shown in the <<watch-log-data, Getting Started>> guide, you can use the
full Elasticsearch query language. 

A <<input-search, search>> input contains a `request` object that specifies the indices you want to
search, the {ref}/search-request-search-type.html[search type], and the search request body. The
`body` field of a search input is the same as the body of an Elasticsearch `_search` request.

NOTE:   The default search type is {ref}/search-request-search-type.html#count[`count`], which 
        differs from the Elasticsearch default of `query_then_fetch`. 

 
////////////
For example, the following search input searches the watch history indices for watch records whose execution_duration exceeded 2.5 seconds.

[source,js]
-------------------------------------------------- 
"input" : {
    "search": {
      "request": {
        "indices": [
          ".watch_history*"
        ],
        "body": {
          "size" : 0,
          "query" : {
            "filtered": {
              "query" : {
                "match_all" : { }
              },
              "filter": {
                "range": {
                  "result.execution_duration": {
                    "gt": 2500
                  }
                }
              }
            }
          }
        }
      }
    }
  },
--------------------------------------------------
////////////

[[loading-http-data]]
==== Loading a Webserver Response with the HTTP Input

To query a webserver and load the response into the watch payload, you use the `http` input. In
addition to calling Elasticsearch APIs as shown in the <<watch-cluster-status, Getting Started>>
guide, you can submit requests to any webserver that returns a response in JSON. 

////////////
For example, the following input gets excerpts for all of the questions posted to Stack Overflow
during the month of May, 2015 that were tagged with `elasticsearch`. 

[source,js]
-------------------------------------------------- 
"input" : { 
  "http" : {
    "request" : {
      "host" : "api.stackexchange.com",
      "port" : 80,
      "path" : "https://api.stackexchange.com/2.2/search/excerpts",
      "params" : { <1>
        "fromdate" : 1430438400,
        "todate" : 1433030400,
        "order" : "desc",
        "sort" : "activity",
        "tagged" : "elasticsearch",
        "site" : "stackoverflow"
      } 
    }
  } 
}
-------------------------------------------------- 
      
<1> The query string parameters are passed to the server using a `params` field, they are not
    included as part of the path.
////////////    

[[changing-conditions]]
=== Changing Conditions

Watcher supports four types of conditions <<condition-always, always>>, <<condition-never, never>>, 
<<condition-compare, compare>>,  and <<condition-script, script>>.

The first two are pretty self-explanatory--they are shortcuts for setting a watch's condition to
`true` or `false`. 

The `compare` condition enables you to perform simple comparisons against values in the Watch
payload. While you can also do this with a `script` condition, with `compare` you can define
inline comparisons without having to enable dynamic scripting. You can use the `script` condition 
to perform more complex evaluations of the data in the watch payload. 

For example, the following compare condition checks to see if the 'search' input returned any
hits:

[source,js]
-------------------------------------------------- 
"condition" : {
    "compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
  },
-------------------------------------------------- 

////////////
The following script condition checks Stack Overflow excerpts loaded by an 'http' input to see if
there are unanswered questions that have a question_score of 3 or higher.

[source,js]
-------------------------------------------------- 
"condition" : {
    "script" : "def items = ctx.payload.items; def createResult = {if (it.question_score.value >= 3 && it.has_accepted_answer.value == false) {return true}}; items.each(createResult)"
  }
-------------------------------------------------- 
////////////

[[using-transforms]]
=== Using Transforms

Watcher supports three types of transforms <<transform-search, search>>,
<<transform-script, script>> and <<transform-chain, chain>>. A `search` transform replaces the
existing payload with the results of a new search request. You can use `script` transforms to
modify the existing payload. A `chain` transform enables you to perform a series of `search` and
`script` transforms.

////////////

For example, the following chain transform performs a 'query_then_fetch' search to load the source
of the watch records that have an 'execution_duration' of more than 2.5 seconds. A script transform
then extracts selected information from the search results and updates the watch payload.

[source,js]
-------------------------------------------------- 
"transform" : {
  "chain" : [ 
    {
      "search" : {  
        "search_type" : "query_then_fetch",
        "indices" : [ ".watch_history*" ],
        "body" : {
          "query" : {
            "filtered": {
              "query" : {
                "match_all" : { }
              },
              "filter": {
              "range": {
                "result.execution_duration": {
                  "gt": 2500
                  }
                }
              }
            }
          }
        }
      }
    },
    {
      "script" : "def records = ctx.payload.hits.hits; def result = [ ]; def createResult = {if (!it) { result = '0'} else {result << it._source.result.execution_duration.value}}; records.each(createResult); return result"  
    }
  ]
},
-------------------------------------------------- 

////////////

[[customizing-actions]]
=== Customizing Actions

Watcher supports four types of actions <<actions-email, email>>, 
<<actions-index, index>>, <<actions-logging, logging>>, and <<actions-webhook, webhook>>. 

To use the `email` action, you need to <<email-services, configure an email account>> in 
`elasticsearch.yml` that Watcher can use to send email. Your custom email messages can be
plain text or styled using HTML. You can include information from the watch payload using
<<templates, templates>>, as well as attach the entire watch payload to the message. For example,
the following email action uses a template in the subject line and attaches the payload data to the 
message.

[source,js]
-------------------------------------------------- 
"actions" : {
  "send_email" : {
    "email" : {
      "to" : "<username>@<domainname>",
      "subject" : "Watcher Notification",
      "body" : "{{ctx.payload.hits.total}} watches took more than 2.5 seconds to execute.",
      "attach_data" : true
    }
  }
}
-------------------------------------------------- 

The `index` action enables you to load data from the watch payload into an Elasticsearch index. The
entire payload can be indexed as a single document, or you can use a transform to populate a 
`_doc` field with an array of objects that are indexed as separate documents. 

////////////
For example, 
the following index action indexes each of the excerpts extracted from Stack Overflow as a separate 
document.

[source,js]
-------------------------------------------------- 
"actions" : {
  "index_payload" : { 
    "transform": { 
      ...
     },
    "index" : {
      "index" : "questions", 
      "doc_type" : "stackoverflow-excerpt" 
    }
  }
}
-------------------------------------------------- 

////////////

The `logging` action enables you to add entries to the Elasticsearch logs, which is useful
during development and testing. For example, the following logging action logs the number
of watches that took longer than 2.5 seconds to run.

[source,js]
-------------------------------------------------- 
"actions" : {
  "log" : { 
    "logging" : {
      "text" : "{{ctx.payload.hits.total}} watches took more than 2.5 seconds to execute" 
    }
  }
}
--------------------------------------------------

The `webhook` action enables you to submit a request to any external webservice. For example,
the following webhook action creates a Pagerduty trigger event.

[source,js]
-------------------------------------------------- 
"actions" : {
  "send_trigger" : { 
    "throttle_period" : "5m", 
    "webhook" : {
      "method" : "POST", 
      "host" : "https://events.pagerduty.com", 
      "port" : 443, 
      "path": ":/generic/2010-04-15/create_event.json}", 
      "body" : "{    
        \"service_key\": \"e93facc04764012d7bfb002500d5d1a6\",
        \"incident_key\": \"long_watches\",
        \"event_type\": \"trigger\",
        \"description\": \"{{ctx.payload.hits.total}} watches took more than 2.5 seconds to execute\",
        \"client\": \"Watcher\"      
      }" 
      "headers": {"Content-type": "application/json"}
    }
  }
}
--------------------------------------------------