Commit fd675feb authored by Nils Bandener's avatar Nils Bandener
Browse files

Documentation for actions

parent e66789a1
......@@ -12,8 +12,85 @@ description:
<!--- Copyright 2019 floragunn GmbH -->
# Creating Actions
# Actions
{: .no_toc}
{% include toc.md %}
## Basics
When the checks configured in a watch found a situation to be noteworthy, it's time to take action. This is done using the equally named watch building block: Actions.
Actions can be used to send notifications by e-mail or other messaging services such as Slack. Also, actions allow to write data to Elasticsearch indexes. A general purpose mechanism to invoke external services is the webhook action which allows making HTTP requests to configurable endpoints.
A watch can have several actions; either for sending notifications via different media, or for acting differently depending on the situation.
Actions are generally invoked if all checks configured for a watch ran with a positive result. Thus, if a condition configured in the checks evaluates to false, watch execution is aborted an no actions are invoked. The actions operate on the runtime data collected by these checks.
Still, it is possible to configure further action-specific checks. This way, it is for example possible to configure different escalation levels: Certain actions will be only triggered when deemed values exceed a further threshold. Also, action-specific checks can be used to prepare further runtime data for the action. Modifications of the runtime data done by action-specific checks are always scoped to this action and are invisible to other actions.
In order to avoid getting spammed or flooded by automatic notifications caused by actions, Signals provides two mechanisms: Throttling automatically suppresses the repeated execution of actions for a configurable amount of time. Furthermore, users can acknowledge actions which suppresses action execution until the checks of a watch change their state.
## Action Types
These actions are available right now:
**E-Mail Action:** Sends e-mails to configurable recipients. Mail content can be defined using templating.
**Slack Action:** Sends Slack messages to configurable recipients. Message content is templateable as well.
**Webhook Actions:** Sends HTTP requests to external services.
**Index Action:** Writes data to an Elasticsearch index.
## Action Throttling
For each action, a throttle period can be configured. Throttle periods are time durations during which execution of the particular action will be suppressed after the it was executed. This way, a watch can be configured to be run very frequently in order to get quickly notified about newly commencing situations. Yet, actions would be triggered less frequently – in the frequency configured by the throttle period.
If actions are throttled, the watches are still executed. The watch log will contain information about the execution and list the respective actions as throttled.
A throttle period can be also specified on the level of a watch. This then serves as a default throttle period for all actions. Actions can still define specific throttle periods, though.
If no explicit throttle period is configured, a default throttle period of 10 seconds is used.
## Acknowledging Actions
A manual way of suppressing the execution of actions is acknowledging actions.
If an action is acknowledged, its execution is suppressed for an indefinite amount of time. Still, the watch continues to be executed on its normal schedule. During each watch execution, the conditions that would lead to the execution of the action are checked. If the conditions remain the same, the action remains acknowledged and thus execution is suppressed. Only if the conditions go away, the acknowledge state of the action is reset. Thus, if the conditions change back again so the action would be executed, the action would be actually executed again.
## Common Action Properties
All action types share a set of common configuration properties. Consider the following example action:
```json
{
/* ... */
"actions": [
{
"type": "email",
"name": "my_email_action",
"checks": [
{
"type": "condition.script",
"source": "data.bad_weather_flights.hits.total.value > 100"
}
],
"throttle_period": "1h",
/* ... */
}
]
}
```
The common configuration attributes are:
**type:** The type of the action. Required. Can be index, email, slack or webhook right now.
**name:** A name identifying this action. Required.
**checks:** Further checks which can gather or transform data and decide whether to execute the actual action. Optional.
**throttle_period:** The throttle period. Optional. Specify the time duration using an *amount*, followed by its *unit*. Supported units are m (minutes), h (hours), d (days), w (weeks). For example, `1h` means one hour.
......@@ -11,8 +11,60 @@ description:
<!--- Copyright 2019 floragunn GmbH -->
# Email Actions
# Email Action
{: .no_toc}
{% include toc.md %}
Use e-mail actions to send e-mail notifications from watches. You can use Mustache templates to define dynamic content for mail subject and content.
% LATER: attachments
## Prerequisites
In order to use e-mail actions, you need to configure an SMTP server using the accounts configuration of Signals.
## Basic Functionality
A basic e-mail action looks like this:
```json
{
/* ... */
"actions": [
{
"type": "email",
"name": "my_email_action",
"throttle_period": "1h",
"account": "internal_mail",
"to": "notify@example.com",
"subject": "Bad destination weather for {{data.bad_weather_flights.hits.total.value}} flights over last {{data.constants.window}}!",
"text_body": "Flight Number: {{data.source.FlightNum}}\n Route: {{data.source.OriginAirportID}} -> {{data.source.DestAirportID}}"
}
]
}
```
The basic configuration attributes are:
**name:** A name identifying this action. Required.
**checks:** Further checks which can gather or transform data and decide whether to execute the actual action. Optional.
**throttle_period:** The throttle period. Optional. Specify the time duration using an *amount*, followed by its *unit*. Supported units are m (minutes), h (hours), d (days), w (weeks). For example, `1h` means one hour.
**account:** Identifies the SMTP server and account which shall be used for sending the email. See TODO
**to:** Specifies the e-mail address of the recipient of the mail. Multiple recipients can be specified by using an array. Optional. Falls backs to defaults set in the account configuration.
**cc, bcc:** Further recipient email addresses can be specified using the attributes `cc` and `bcc`. Optional. Falls backs to defaults set in the account configuration.
**from:** Specifies the *from* address of the e-mail. Optional. Falls backs to defaults set in the account configuration.
**subject:** Defines the subject of the mail. Mustache templates can be used to render attributes from the watch runtime data. Required.
**text_body:** Defines the content of the mail. Mustache templates can be used to render attributes from the watch runtime data. Optional.
Note that HTML mails are not supported right now.
......@@ -11,8 +11,80 @@ description:
<!--- Copyright 2019 floragunn GmbH -->
# Index Actions
# Index Action
{: .no_toc}
{% include toc.md %}
Use index actions to store data in an Elasticsearch index.
% LATER: attachments
## Basic Functionality
A typical index action looks like this:
```json
{
/* ... */
"actions": [
{
"type": "index",
"checks": [
{
"type": "transform",
"source": "['flight_num': data.source.FlightNum, 'dest': data.source.DestAirportID]"
}
]
"index": "testindex"
}
]
}
```
Index actions write a complete snapshot of the current runtime data as one JSON document into the specified index.
Therefore, as shown in the example above, index actions are typically accompanied by transforms which can explicitly define the data to be indexed using Painless scripts - or any other installed script engine. The script should return a map which will converted to a JSON document by the action.
## Specifying the Document ID
Normally, documents will be indexed with an automatically generated ID. You can however also explicitly define the ID of the document by providing an additional attribute in the runtime data called `_id`.
## Indexing Multiple Documents
If you want to index multiple documents by one action execution, you need to prepare the runtime data in a special way: Store the documents to be indexed in an array and store this array in an attribute called `_doc` at the top level of the runtime data. The following example stores two documents:
```json
{
/* ... */
"actions": [
{
"type": "index",
"checks": [
{
"type": "transform",
"source": "['_doc': [ [ 'x': 1 ], [ 'x': 2 ] ] ]"
}
]
"index": "testindex"
}
]
}
```
## Authorization
The index operation will be executed with the privileges the user had when creating or updating the watch. So, you must make sure to have all the privileges necessary to write to the respective indexes when creating or updating a watch.
## Advanced Attributes
Further configuration attributes are:
**refresh:** The Elasticsearch index [refresh policy](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-refresh.html). One of `false`, `true` or `wait_for`. Optional; default is `false`.
**timeout:** If the index operation does not complete in the specified time (in seconds), it will be aborted. Optional; default is 60 seconds.
......@@ -11,8 +11,48 @@ description:
<!--- Copyright 2019 floragunn GmbH -->
# Slack Actions
# Slack Action
{: .no_toc}
{% include toc.md %}
Use Slack actions to send notifications via Slack. You can use Mustache templates to define dynamic content for the Slack message.
## Prerequisites
In order to use Slack actions, you need to configure a Slack webhook using the accounts configuration of Signals. See TODO for more on that.
## Basic Functionality
A basic Slack action looks like this:
```json
{
/* ... */
"actions": [
{
"type": "slack",
"name": "my_slack_action",
"throttle_period": "1h",
"account": "internal_slack",
"text": ":warning:\n**Bad destination weather** for {{data.bad_weather_flights.hits.total.value}} flights over last {{data.constants.window}}"
}
]
}
```
The basic configuration attributes are:
**name:** A name identifying this action. Required.
**throttle_period:** The throttle period. Optional. Specify the time duration using an *amount*, followed by its *unit*. Supported units are m (minutes), h (hours), d (days), w (weeks). For example, `1h` means one hour.
**checks:** Further checks which can gather or transform data and decide whether to execute the actual action. Optional.
**account:** Identifies the Slack application which shall be used for sending the message. See TODO
**text:** Defines the content of the message. Mustache templates can be used to render attributes from the watch runtime data. Optional. See the [Slack documentation](https://api.slack.com/messaging/composing/formatting) for details on how to format the message.
*Slack blocks or attachments are not yet supported, but will be coming up soon.*
......@@ -11,8 +11,116 @@ description:
<!--- Copyright 2019 floragunn GmbH -->
# Webhook Actions
# Webhook Action
{: .no_toc}
{% include toc.md %}
Use webhook actions to call arbitrary HTTP endpoints from watches. You can use Mustache templates to define parts of the URI and the request body.
## Basic Functionality
A basic webhook action looks like this:
```json
{
/* ... */
"actions": [
{
"type": "webhook",
"name": "my_webhook_action",
"throttle_period": "10m",
"request": {
"method": "POST",
"url": "https://my.test.web.hook/endpoint",
"body": "{\"flight_number\": \"{{data.source.FlightNum}}\"}",
"headers": {
"Content-Type": "application/json"
}
}
}
]
}
```
The basic configuration attributes are:
**name:** A name identifying this action. Required.
**checks:** Further checks which can gather or transform data and decide whether to execute the actual action. Optional.
**throttle_period:** The throttle period. Optional. Specify the time duration using an *amount*, followed by its *unit*. Supported units are m (minutes), h (hours), d (days), w (weeks). For example, `1h` means one hour.
**request.method:** Specifies the HTTP request method. Required. One of `GET`, `POST`, `PUT` or `DELETE`.
**request.url:** The URL of the HTTP endpoint. Required.
**request.body:** The body of the HTTP request. Optional. Mustache templates can be used to render attributes from the watch runtime data.
**request.headers:** Specifies HTTP headers to be sent along the request. Optional.
## Dynamic Endpoints
The HTTP endpoint in the `request.url` attribute cannot be changed dynamically directly. However, you can use the configuration attributes `request.path` and `request.query_params` to define the respective parts of the URL using Mustache templates. The resulting path and/or query parameters then override the respective parts of the URL defined in `request.url`.
```json
{
/* ... */
"actions": [
{
"type": "webhook",
"name": "my_webhook_action",
"throttle_period": "10m",
"request": {
"method": "POST",
"url": "https://my.test.web.hook/",
"path": "fight/{{data.source.FlightNum}}"
}
}
]
}
```
## Authentication
You can use the `auth` attribute to specify HTTP basic auth data.
```json
{
/* ... */
"actions": [
{
"type": "webhook",
"name": "my_webhook_action",
"throttle_period": "10m",
"request": {
"method": "POST",
"url": "https://my.test.web.hook/",
"auth": {
"type": "basic",
"username": "test",
"password": "test"
}
}
}
]
}
```
**Note:** In the current version of the tech preview, the password is stored unencrypted and returned in verbatim when the watch is retrieved using the REST API. Future versions will provide a more secure way of storing authentication data.
## Advanced Functionality
Furthermore, webhook actions provide these configuration options:
**connection_timeout:** Specifies the time after which the try to create an connection shall time out. Optional. Specified in seconds.
**read_timeout:** Specifies the timeout for reading the response data after a connection has been already established. Optional. Specified in seconds.
## Security Considerations
Keep in mind that webhook actions allow to send arbitrary HTTP requests from Elasticsearch nodes. We are still working on mechanisms to define restrictions on the use of webhook actions and the allowed endpoints.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment