Defining alertsedit

Kibana alerts can be created in a variety of apps including APM, Metrics, Security, Uptime and from Management UI. While alerting details may differ from app to app, they share a common interface for defining and configuring alerts that this section describes in more detail.

Alert flyoutedit

When an alert is created in an app, the app will display a flyout panel with three main sections to configure:

The three sections of an alert definition

General alert detailsedit

All alert share the following four properties in common:

All alerts have name, tags, check every, and notify every properties in common
The name of the alert. While this name does not have to be unique, the name can be referenced in actions and also appears in the searchable alert listing in the management UI. A distinctive name can help identify and find an alert.
A list of tag names that can be applied to an alert. Tags can help you organize and find alerts, because tags appear in the alert listing in the management UI which is searchable by tag.
Check every
This value determines how frequently the alert conditions below are checked. Note that the timing of background alert checks are not guaranteed, particularly for intervals of less than 10 seconds. See Production considerations for more information.
Notify every
This value limits how often actions are repeated when an alert instance remains active across alert checks. See Suppressing duplicate notifications for more information.

Alert type and conditionsedit

Depending upon the Kibana app and context, you may be prompted to choose the type of alert you wish to create. Some apps will pre-select the type of alert for you.

Choosing the type of alert to create

Each alert type provides its own way of defining the conditions to detect, but an expression formed by a series of clauses is a common pattern. Each clause has a UI control that allows you to define the clause. For example, in an index threshold alert the WHEN clause allows you to select an aggregation operation to apply to a numeric field.

UI for defining alert conditions on an index threshold alert

Action type and action detailsedit

To add an action to an alert, you first select the type of action:

UI for selecting an action type

Each action must specify a connector instance. If no connectors exist for that action type, click "Add new" to create one.

Each action type exposes different properties. For example an email action allows you to set the recipients, the subject, and a message body in markdown format. See Action and connector types for details on the types of actions provided by Kibana and their properties.

UI for defining an email action

Using the Mustache template syntax {{variable name}}, you can pass alert values at the time a condition is detected to an action. Available variables differ by alert type, and the list of available variables can be accessed using the "add variable" button.

Passing alert values to an action

Some cases exist where the variable values will be "escaped", when used in a context where escaping is needed:

  • For the Email connector, the message action configuration property escapes any characters that would be interpreted as Markdown.
  • For the Slack connector, the message action configuration property escapes any characters that would be interpreted as Slack Markdown.
  • For the Webhook connector, the body action configuration property escapes any characters that are invalid in JSON string values.

Mustache also supports "triple braces" of the form {{{variable name}}}, which indicates no escaping should be done at all. Care should be used when using this form, as it could end up rendering the variable content in such a way as to make the resulting parameter invalid or formatted incorrectly.

You can attach more than one action. Clicking the "Add action" button will prompt you to select another alert type and repeat the above steps again.

You can add multiple actions on an alert

Actions are not required on alerts. In some cases you may want to run an alert without actions first to understand its behavior, and configure actions later.

Global actions configurationedit

Some actions configuration options apply to all actions. If you are using an on-prem Elastic Stack deployment, you can set these in the kibana.yml file. If you are using a cloud deployment, you can set these via the console.

Here’s a list of the available global configuration options and an explanation of what each one does:

  • xpack.actions.allowedHosts: Specifies an array of host names which actions such as email, Slack, PagerDuty, and webhook can connect to. An element of * indicates any host can be connected to. An empty array indicates no hosts can be connected to. Default: [ * ]
  • xpack.actions.enabledActionTypes: Specifies to an array of action types that are enabled. An * indicates all action types registered are enabled. The action types that Kibana provides are: .server-log, .slack, .email, .index, .pagerduty, .webhook. Default: [ * ]
  • xpack.actions.proxyUrl: Specifies the proxy URL to use, if using a proxy for actions.
  • xpack.actions.proxyHeader: Specifies HTTP headers for proxy, if using a proxy for actions.
  • xpack.actions.proxyRejectUnauthorizedCertificates: Set to false to bypass certificate validation for proxy, if using a proxy for actions.
  • xpack.actions.rejectUnauthorized: Set to false to bypass certificate validation for actions.

NOTE: As an alternative to both xpack.actions.proxyRejectUnauthorizedCertificates and xpack.actions.rejectUnauthorized, the OS level environment variable NODE_EXTRA_CA_CERTS can be set to point to a file that contains the root CA(s) needed for certificates to be trusted.

Managing alertsedit

To modify an alert after it was created, including muting or disabling it, use the alert listing in the Management UI.