Commit 9abf5b30 authored by Jochen Kressin's avatar Jochen Kressin
Browse files

introduced overview pages for Signals

parent 58a0f9c7
......@@ -7,6 +7,7 @@ subcategory: actions
order: 700
layout: docs
edition: beta
canonical: elasticsearch-alerting-actions-overview
description:
---
......
---
title: Actions Overview
html_title: Creating Actions for Signals Alerting
slug: elasticsearch-alerting-actions-overview
category: actions
order: 0
layout: docs
edition: beta
description:
---
<!--- Copyright 2019 floragunn GmbH -->
# 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](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.
A watch can have several actions; either for sending notifications via different media, or for acting differently depending on the situation.
## Invoking actions
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 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.
**Note:** By using the severity feature, you can configure actions to be executed only if a certain problem severity was determined before. Also, you can configure resolve actions which get executed if the problem severity decreased. See [Severity](severity.md) for details.
## Action Types
These actions are available at the moment:
**[Index Action](actions_index.md):** Writes data to an Elasticsearch index.
**[E-Mail Action](actions_email.md):** Sends e-mails to configurable recipients. Mail content can be defined using templating.
**[Webhook Actions](actions_webhook.md):** Sends HTTP requests to external services.
**[Slack Action](actions_slack.md):** Sends Slack messages to configurable recipients. Message content is templateable as well.
**[PagerDuty Actions](actions_pagerduty.md):** Sends notifications to PagerDuty (Enterprise Feature).
**[JIRA Actions](actions_jira.md):** Sends notifications to JIRA, for example to create a new issue (Enterprise Feature).
## Action Throttling
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.
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.
Throttle periods can be either constant time values like `1h` (1 hour) or `10m` (10 minutes). Alternatively, you can specify throttle periods which increase while the situation recognized by the watch persists. These throttle periods are called exponential periods. You also use the `throttle_period` attribute for configuring exponential periods. The initial throttling and the increase is configured using a special syntax of the value. The syntax is `duration ** basis of exponentiation | maximum duration`. For example, the value `1m**2|1h` would pause notifications after the initial notification for these durations: 1 minute, 2 minutes, 4 minutes, 8 minutes, 16 minutes, 32 minutes, 60 minutes. Afterwards, notifications are repeated every 60 minutes until the situation which causes the action is resolved. The specification of a maximum duration is optional, so you can also just write `1m**2`. The maximum duration then defaults to one day.
Supported units for simple throttle periods and exponential throttle periods are m (minutes), h (hours), d (days), w (weeks).
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. This default can be adjusted using the Signals settings. See the section on [Administration](administration.md) for details.
## 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.
## Processing Collections of Objects in Actions
Some types of watches can produce several objects at once which then need to be processed by actions.
There are at least two ways of achieving this task:
* Executing an action once which condenses the object collection using scripts or templates
* Executing an action for each object from the collection.
Especially for notification actions, the first approach is strongly recommended. It is not feasible to have a potentially unbounded number of notifications being sent by one watch.
For achieving this, you can use for example loops in Mustache templates. This might look like this:
<!-- {% raw %} -->
```json
{
"checks": [
{
"type": "search",
"name": "errors",
"target": "errors",
"request": {
"indices": ["errors"],
"body": {}
}
}
],
"actions": [
{
"type": "slack",
"name": "slack_info",
"channel": "#notifications",
"text": "Found errors:\n{{#data.errors.hits.hits}}\n* {{_source.message}} {{/data.errors.hits.hits}}"
}
]
}
```
<!-- {% endraw %} -->
In some cases, however, it will get necessary to execute the action for each element of a collection. This can be achieved by setting the `foreach` attribute of an action to a Painless expression producing a collection. The action will be then executed for each element of that collection. To access the current element of the collection, use the property called `item`. The `data` property is still providing a view of the complete runtime data.
In order to avoid actions being accidentially executed on very large collections, the amount of iterations is limited. By default, an action is only executed for the first 100 elements of a collection. This limit can be changed by setting the `foreach_limit` property of an action.
A watch using the `foreach` property might look like this:
<!-- {% raw %} -->
```json
{
"checks": [
{
"type": "search",
"name": "errors",
"target": "errors",
"request": {
"indices": ["errors"],
"body": {}
}
}
],
"actions": [
{
"type": "webhook",
"name": "post_error_to_webhook",
"foreach": "data.errors.hits.hits",
"throttle_period": "10m",
"request": {
"method": "POST",
"url": "https://my.test.web.hook/endpoint",
"body": "{{item._source.message}}"
}
}
]
}
```
<!-- {% endraw %} -->
## 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.
**foreach:** Executes the action for each element of a collection. The collection to use is identified by the Painless expression specified for this attribute. Optional see [Processing Collections of Objects in Actions](#Processing Collections of Objects in Actions) for details.
**foreach_limit:** Specifies the maximum allowed number of iterations performed when using `foreach`. Optional. Defaults to 100.
Alert actions (i.e., non-resolve actions) additionally support these properties:
**throttle_period:** The throttle period. Optional. Specify the time duration using an *amount*, followed by its *unit*. Alternatively, specify an exponential throttle period using the syntax *duration*`**`*basis of exponentiation*`|` *maximum duration*. Supported units are m (minutes), h (hours), d (days), w (weeks). For example, `1h` means one hour.
**severity:** Selects the severity levels in which this action shall be executed. Optional. An array of `info`, `warning`, `error`, `fatal`. See the section on [Severity](severity.md) for details.
Resolve actions additionally support these properties:
**resolves_severity:** Selects the severity levels which need to be resolved in order to execute this action. Mandatory. An array of `info`, `warning`, `error`, `fatal`. See the section on [Severity](severity.md) for details.
......@@ -7,6 +7,7 @@ subcategory: conditions
order: 600
layout: docs
edition: beta
canonical: elasticsearch-alerting-conditions-overview
description:
---
......@@ -15,8 +16,6 @@ description:
# Conditions
{: .no_toc}
{% include toc.md %}
Conditions are used to control the execution flow. A condition can be used anywhere in the execution chain for watches and actions.
A condition must return a boolean value. If the condition returns true, the execution continues. If the condition returns false, the execution is stopped.
......
---
title: Conditions Overview
html_title: Creating Conditions for Signals Alerting
slug: elasticsearch-alerting-conditions-overview
category: conditions
order: 0
layout: docs
edition: beta
description:
---
<!--- Copyright 2019 floragunn GmbH -->
# Conditions Overview
{: .no_toc}
Conditions are used to control the execution flow. A condition can be used anywhere in the execution chain for watches and actions.
A condition must return a boolean value. If the condition returns true, the execution continues. If the condition returns false, the execution is stopped.
In watches, a condition controls whether a certain value or threshold is reached, to decide whether the watch should continue execution.
In actions, conditions can be used to control if a certain action should be executed. For example, you can decide to send an email to an administrator if the error level in your log files is too high. In addition, if the error level stays high for a certain amount of time, you can send another email, escalating the issue to another person.
Currently, the following condition types are supported
* [condition.script](conditions_script.md)
* a condition that uses a Painless script
\ No newline at end of file
......@@ -7,6 +7,7 @@ subcategory: inputs
order: 400
layout: docs
edition: beta
canonical: elasticsearch-alerting-inputs-overview
description:
---
......
---
title: Elasticsearch
title: Elasticsearch Input
html_title: Creating Elasticsearch inputs for Signals Alerting
slug: elasticsearch-alerting-inputs-elasticsearch
category: inputs
......
---
title: HTTP
html_title: Creating HTTPP inputs for Signals Alerting
title: HTTP Input
html_title: Creating HTTP inputs for Signals Alerting
slug: elasticsearch-alerting-inputs-http
category: inputs
order: 300
......
---
title: Inputs Overview
html_title: Creating inputs for Signals Alerting Overview
slug: elasticsearch-alerting-inputs-overview
category: inputs
order: 0
layout: docs
edition: beta
description:
---
<!--- Copyright 2019 floragunn GmbH -->
# Inputs
{: .no_toc}
Each watch can have one or more inputs. Inputs can be freely defined anywhere in the execution chain.
Each input will fetch data from a data source, and place it in the runtime data context under a configurable key for later usage.
At the moment, Signals supports the following input types:
* [Static](inputs_static.md)
* Define constants you can then use at multiple places in the execution chain
* [Elasticsearch](inputs_elasticsearch.md)
* Use the full power of Elasticsearch queries and aggregations
* [HTTP](inputs_http.md)
* Pull in data from a REST endpoint
All data from all inputs can be combined by using [Transformation](transformations_transformations.md) and [Calculations](transformations_calculations.md), used in [Conditions](conditions.md) and pushed to [action endpoints](actions.md).
---
title: Static
title: Static Input
html_title: Creating static inputs for Signals Alerting
slug: elasticsearch-alerting-inputs-static
category: inputs
......
......@@ -7,6 +7,7 @@ subcategory: signals-rest
order: 900
layout: docs
edition: beta
canonical: elasticsearch-alerting-rest-api-overview
description:
---
......
---
title: REST API Overview
html_title: Managing Signals Alerting with the REST API
slug: elasticsearch-alerting-rest-api-overview
category: signals-rest
order: 0
layout: docs
edition: beta
description:
---
<!--- Copyright 2019 floragunn GmbH -->
# REST API
{: .no_toc}
{% include toc.md %}
Signals can be configured by using the Signals REST API. To use the API, make sure that the user has [sufficient permissions](security_permissions.md).
For a quick start, you can either use the Search Guard [admin demo user](demo-users-roles#demo-users), or assign the `SGS_SIGNALS_ALL` action group on cluster- and tenant-level to a Search Guard role, e.g.:
```
sg_signals_all:
cluster_permissions:
- 'GS_SIGNALS_ALL
index_permissions:
- index_patterns:
- 'signal*'
allowed_actions:
- '*'
tenant_permissions:
- tenant_patterns:
- '*'
allowed_actions:
- 'SGS_SIGNALS_ALL'
```
This will give this role complete access to all Signals features and indices.
## Watches APIs
* [Get Watch](rest_api_watch_get.md)
* [Search Watch](rest_api_watch_search.md)
* [Put Watch](rest_api_watch_put.md)
* [Delete Watch](rest_api_watch_delete.md)
* [Activate and Deactivate Watch](rest_api_watch_activate.md)
* [Execute Watch](rest_api_watch_execute.md)
* [Acknowledge Watch](rest_api_watch_acknowledge.md)
* [Un-Acknowledge Watch](rest_api_watch_unacknowledge.md)
* [Convert Watch](rest_api_convert_es.md)
## Watch State APIs
* [Get Watch State](rest_api_watch_state.md)
* [Search Watch State](rest_api_watch_state_search.md)
## Accounts APIs
* [Get Account](rest_api_watch_get.md)
* [Search Account](rest_api_account_search.md)
* [Put Account](rest_api_account_put.md)
* [Delete Account](rest_api_account_delete.md)
## Settings APIs
* [Get Settings](rest_api_settings_get.md)
* [Put Settings](rest_api_settings_put.md)
......@@ -7,6 +7,7 @@ subcategory: security
order: 950
layout: docs
edition: beta
canonical: elasticsearch-alerting-security-overview
description:
---
......
---
title: Security Integration Overview
html_title: How Signals Alerting integrates with Search Guard
slug: elasticsearch-alerting-security-overview
category: security
order: 0
layout: docs
edition: beta
description:
---
<!--- Copyright 2019 floragunn GmbH -->
# Security Integration Overview
{: .no_toc}
{% include toc.md %}
Signals is integrated with all security related features of Search Guard. This means that access to watches and also the underlying Elasticsearch indices is governed by Search Guard roles.
## Signals Indices
The [Signals configuration index](security_indices.md) may store sensitive data and is only accessible by using the Signals API. Direct access is not possible.
## API Access
Access to the API to create, update, execute and delete watches and accounts is controlled by a user's Search Guard roles and permissions.
Signals ships with [pre-defined action groups](security_permissions.md) that you can use when defining Signals roles.
## Security execution context
Each watch is executed in a security context that governs access to the Elasticsearch indices. A watch is always executed with the set of permissions the user that created or updated the watch has at the time of creation / update.
## Multi tenancy
Signals is multi-tenancy aware. If you are using Search Guard multi tenancy, you can separate access to watches based on a user's available tenants.
If you do not use multi tenancy, all watches are stored in the `SGS_GLOBAL_TENANT` and available for all Signals users that have at least READ permission for watches.
......@@ -7,6 +7,7 @@ subcategory: transformations
order: 500
layout: docs
edition: beta
canonical: elasticsearch-alerting-transformations-calculations-overview
description:
---
......@@ -15,8 +16,6 @@ description:
# Transformations and Calculations
{: .no_toc}
{% include toc.md %}
In many cases, you will want to run transformations and calculations on the raw data pulled in by [inputs](inputs.md).
For example, you may want to calculate an average value over some fields, or clean up data before [storing it back to Elasticsearch](actions_index.md).
......
---
title: Transformations Overview
html_title: Creating Transformations and Calculations for Signals Alerting
slug: elasticsearch-alerting-transformations-calculations-overview
category: transformations
order: 0
layout: docs
edition: beta
description:
---
<!--- Copyright 2019 floragunn GmbH -->
# Transformations and Calculations
{: .no_toc}
In many cases, you will want to run transformations and calculations on the raw data pulled in by [inputs](elasticsearch-alerting-inputs-overview).
For example, you may want to calculate an average value over some fields, or clean up data before [storing it back to Elasticsearch](actions_index.md).
You can use painless scripts to either
* [transform](transformations_transformations.md) your data in any execution context
* [calculate](transformations_calculations.md) values and store them in a new execution context
Both transformations and calculations are implemented as inline or stored painless scripts that operate on the execution runtime data. You can use the full power of painless to massage the data any way you want.
\ No newline at end of file
......@@ -7,6 +7,7 @@ subcategory: triggers
order: 300
layout: docs
edition: beta
canonical: triggers-overview
description:
---
......
---
title: Triggers Overview
html_title: Triggers for Signals Alerting Overview
slug: elasticsearch-alerting-triggers-overview
category: triggers
order: 0
layout: docs
edition: beta
description:
---
<!--- Copyright 2019 floragunn GmbH -->
# Triggers overview
{: .no_toc}
{% include toc.md %}
## What is a trigger
Every watch has to define a trigger. A trigger specifies when a watch gets executed ("triggered"). Currently the following trigger types are supported:
* Date and time
* for example, every Wednesday at 2pm
* Interval
* for example, every 10 minutes
* cron
* gives you the full power of cron expressions
Example:
```json
{
"trigger": {
"schedule": {
"weekly": {
"on": "thursday",
"at": "14:40:45"
}
}
},
"checks": [ ... ],
"actions": [ ... ]
}
```
## Trigger execution
Each trigger gets registered with the Trigger Execution Engine. The execution engine makes sure that
* Each trigger is executed on exactly one node at a time
* You can specify node filters to define on which nodes Signals Alerting should run
* Triggers created in different tenants will not interfere whith each other
* This applies only when you are using [Multi Tenancy](elasticsearch-alerting-security-multi-tenancy).
## Time zones
Signals supports different [time zones](triggers_timezones.md). If no time zone is specified, the default JVM time zone is used.
......@@ -47,7 +47,11 @@
<link rel="icon" href="img/logos/SG_Fav-32px.png" sizes="32x32" />
<link rel="icon" href="img/logos/SG_Fav-144px.png" sizes="144x144" />
{%if page.canonical == null %}
<link rel="canonical" href="https://docs.search-guard.com{{site.baseurl}}{{page.url}}">
{% else %}
<link rel="canonical" href="https://docs.search-guard.com{{site.baseurl}}/{{page.canonical}}">
{% endif %}
{%if site.searchguard.islatestversion == true && item.subcategory == null %}
<meta name="robots" content="index, follow">
......
Markdown is supported
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