actions.md 4.98 KB
Newer Older
1
2
3
4
5
6
7
8
---
title: Actions
html_title: Creating Actions for Signals Alerting
slug: elasticsearch-alerting-actions
category: signals
subcategory: actions
order: 700
layout: docs
9
edition: community
10
11
12
13
14
description: 
---

<!--- Copyright 2019 floragunn GmbH -->

Nils Bandener's avatar
Nils Bandener committed
15
# Actions
16
17
18
19
{: .no_toc}

{% include toc.md %}

Nils Bandener's avatar
Nils Bandener committed
20
21
22
23
## 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.

Jochen Kressin's avatar
Jochen Kressin committed
24
Actions can be used to send notifications by e-mail or other messaging services such as [Slack](actions_slack.md). Also, actions allow to write data to [Elasticsearch indices](actions_index.md). A general purpose mechanism to invoke external services is the [webhook action](actions_webhook.md) which allows making HTTP requests to configurable endpoints.
Nils Bandener's avatar
Nils Bandener committed
25
26
27

A watch can have several actions; either for sending notifications via different media, or for acting differently depending on the situation.

Jochen Kressin's avatar
Jochen Kressin committed
28
## Invoking actions
Nils Bandener's avatar
Nils Bandener committed
29

Jochen Kressin's avatar
Jochen Kressin committed
30
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.
Nils Bandener's avatar
Nils Bandener committed
31

Jochen Kressin's avatar
Jochen Kressin committed
32
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 only be triggered when certain 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.
Nils Bandener's avatar
Nils Bandener committed
33
34
35

## Action Types

Jochen Kressin's avatar
Jochen Kressin committed
36
These actions are available at the moment:
Nils Bandener's avatar
Nils Bandener committed
37

Jochen Kressin's avatar
Jochen Kressin committed
38
**[E-Mail Action](actions_email.md):** Sends e-mails to configurable recipients. Mail content can be defined using templating.
Nils Bandener's avatar
Nils Bandener committed
39

Jochen Kressin's avatar
Jochen Kressin committed
40
**[Slack Action](actions_slack.md):** Sends Slack messages to configurable recipients. Message content is templateable as well.
Nils Bandener's avatar
Nils Bandener committed
41

Jochen Kressin's avatar
Jochen Kressin committed
42
**[Webhook Actions](actions_webhook.md):** Sends HTTP requests to external services.
Nils Bandener's avatar
Nils Bandener committed
43

Jochen Kressin's avatar
Jochen Kressin committed
44
**[Index Action](actions_index.md):** Writes data to an Elasticsearch index.
Nils Bandener's avatar
Nils Bandener committed
45
46
47

## Action Throttling

Jochen Kressin's avatar
Jochen Kressin committed
48
49
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.

Nils Bandener's avatar
Nils Bandener committed
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
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
 {
Jochen Kressin's avatar
Jochen Kressin committed
70
71
     
    ...
Nils Bandener's avatar
Nils Bandener committed
72
73
74
75
76
77
78
79
80
81
82
	"actions": [
		{
			"type": "email",
			"name": "my_email_action",
			"checks": [ 
				{
					"type": "condition.script",
					"source": "data.bad_weather_flights.hits.total.value > 100"
				}
			],
			"throttle_period": "1h",
Jochen Kressin's avatar
Jochen Kressin committed
83
			...
Nils Bandener's avatar
Nils Bandener committed
84
85
86
87
88
89
90
		}
	]
}
```

The common configuration attributes are:

Jochen Kressin's avatar
Jochen Kressin committed
91
92
93
94
95
96
| Name | Description |
|---|---|
| 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. |