mirror of
https://github.com/elastic/kibana.git
synced 2025-04-23 01:13:23 -04:00
[Alerting][Docs] Adding template for documenting alert and action types (#92830)
* Alert type template * Action type template * Cleanup * Cleanup * Removing callout list * Cleanup * Apply suggestions from code review Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Adding title to actions page * PR fixes * PR fixes * PR fixes * PR fixes Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com> Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>
This commit is contained in:
ymao1
GitHub
parent
3b6643144d
commit
fda67adb9f
19 changed files with 338 additions and 380 deletions
73
docs/action-type-template.asciidoc
Normal file
73
docs/action-type-template.asciidoc
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
[[<ACTION-TYPE>-action-type]]
|
||||
=== <ACTION-TYPE> action
|
||||
++++
|
||||
<titleabbrev><ACTION-TYPE></titleabbrev>
|
||||
++++
|
||||
|
||||
Include a short description of the action type.
|
||||
|
||||
[float]
|
||||
[[<ACTION-TYPE>-connector-configuration]]
|
||||
==== Connector configuration
|
||||
|
||||
<ACTION-TYPE> connectors have the following configuration properties.
|
||||
|
||||
////
|
||||
List of user-facing connector configurations. This should align with the fields available in the Create connector flyout form for this action type.
|
||||
////
|
||||
|
||||
Property1:: A short description of this property.
|
||||
Property2:: A short description of this property with format hints. This can be specified in `this specific format`.
|
||||
|
||||
[float]
|
||||
[[Preconfigured-<ACTION-TYPE>-configuration]]
|
||||
==== Preconfigured action type
|
||||
|
||||
////
|
||||
Example preconfigured format for this action type
|
||||
////
|
||||
|
||||
[source,text]
|
||||
--
|
||||
my-<ACTION-TYPE>:
|
||||
name: preconfigured-<ACTION-TYPE>-action-type
|
||||
actionTypeId: .<ACTION-TYPE>
|
||||
config:
|
||||
property1: value1
|
||||
property2: value2
|
||||
secrets:
|
||||
property3: value3
|
||||
--
|
||||
|
||||
[float]
|
||||
[[<ACTION-TYPE>-connector-config-properties]]
|
||||
////
|
||||
List of properties from the ConfigSchema and SecretsSchema for this action type.
|
||||
////
|
||||
Config defines information for the action type.
|
||||
|
||||
`property1`:: A short description of this property.
|
||||
`property2`:: A short descriptionn of this property.
|
||||
|
||||
Secrets defines sensitive information for the action type.
|
||||
|
||||
`property3`:: A short descriptionn of this property.
|
||||
|
||||
[float]
|
||||
[[<ACTION-TYPE>-action-configuration]]
|
||||
==== Action configuration
|
||||
|
||||
<ACTION-TYPE> actions have the following configuration properties.
|
||||
|
||||
////
|
||||
List of user-facing action configurations. This should align with the fields available in the Action section of the Create/Update alert flyout.
|
||||
////
|
||||
|
||||
Property1:: A short description of this property.
|
||||
Property2:: A short description of this property with format hints. This can be specified in `this specific format`.
|
||||
|
||||
////
|
||||
Optional - additional configuration details here
|
||||
[[configuring-<ACTION-TYPE>]]
|
||||
==== Configure <ACTION-TYPE>
|
||||
////
|
||||
39
docs/alert-type-template.asciidoc
Normal file
39
docs/alert-type-template.asciidoc
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
[[alert-type-<ALERT TYPE>]]
|
||||
=== <ALERT TYPE>
|
||||
|
||||
Include a short description of the alert type.
|
||||
|
||||
[float]
|
||||
==== Create the alert
|
||||
|
||||
Fill in the <<defining-alerts-general-details, alert details>>, then select *<ALERT TYPE>*.
|
||||
|
||||
[float]
|
||||
==== Define the conditions
|
||||
|
||||
Define properties to detect the condition.
|
||||
|
||||
////
|
||||
Optional, include a screenshot
|
||||
[role="screenshot"]
|
||||
image::user/alerting/images/alert-types-<ALERT TYPE>-conditions.png[Conditions for <ALERT TYPE> alert type]
|
||||
////
|
||||
|
||||
Condition1:: This is a condition the user must define.
|
||||
Condition2:: This is another condition the user must define.
|
||||
|
||||
[float]
|
||||
==== Add action variables
|
||||
|
||||
<<defining-alerts-actions-details, Add an action>> to run when the alert condition is met. The following variables are specific to the <ALERT TYPE> alert. You can also specify <<defining-alerts-actions-variables, variables common to all alerts>>.
|
||||
|
||||
`context.variableA`:: A short description of the context variable defined by the alert type.
|
||||
`context.variableB`:: A short description of the context variable defined by the alert type with an example. Example: `this is what variableB outputs`.
|
||||
|
||||
////
|
||||
Optional, include a step-by-step example for creating this alert
|
||||
[float]
|
||||
==== Example
|
||||
|
||||
In this section, you will use the {kib} <<add-sample-data, weblog sample dataset>> to setup and tune the conditions on an <ALERT TYPE> alert. For this example, we want to detect when <DESCRIBE THE CONDITIONS>.
|
||||
////
|
||||
|
|
@ -1,6 +1,9 @@
|
|||
[role="xpack"]
|
||||
[[email-action-type]]
|
||||
=== Email action
|
||||
++++
|
||||
<titleabbrev>Email</titleabbrev>
|
||||
++++
|
||||
|
||||
The email action type uses the SMTP protocol to send mail message, using an integration of https://nodemailer.com/[Nodemailer]. Email message text is sent as both plain text and html text.
|
||||
|
||||
|
|
@ -10,14 +13,15 @@ NOTE: For emails to have a footer with a link back to {kib}, set the <<server-pu
|
|||
[[email-connector-configuration]]
|
||||
==== Connector configuration
|
||||
|
||||
Email connectors have the following configuration properties:
|
||||
Email connectors have the following configuration properties.
|
||||
|
||||
Name:: The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action.
|
||||
Sender:: The from address for all emails sent with this connector. This can be specified in `user@host-name` format or as `"human name <user@host-name>"` format. See the https://nodemailer.com/message/addresses/[Nodemailer address documentation] for more information.
|
||||
Host:: Host name of the service provider. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure this hostname is added to the allowed hosts.
|
||||
Port:: The port to connect to on the service provider.
|
||||
Secure:: If true, the connection will use TLS when connecting to the service provider. Refer to the https://nodemailer.com/smtp/#tls-options[Nodemailer TLS documentation] for more information. If not true, the connection will initially connect over TCP, then attempt to switch to TLS via the SMTP STARTTLS command.
|
||||
User:: Username for login type authentication.
|
||||
Require authentication:: If true, a username and password for login type authentication must be provided.
|
||||
Username:: Username for login type authentication.
|
||||
Password:: Password for login type authentication.
|
||||
|
||||
[float]
|
||||
|
|
@ -39,56 +43,33 @@ Password:: Password for login type authentication.
|
|||
password: passwordkeystorevalue
|
||||
--
|
||||
|
||||
[[email-connector-config-properties]]
|
||||
**`config`** defines the action type specific to the configuration and contains the following properties:
|
||||
Config defines information for the action type.
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
`service`:: The name of a https://nodemailer.com/smtp/well-known/[well-known email service provider]. If `service` is provided, `host`, `port`, and `secure` properties are ignored. For more information on the `gmail` service value, see the https://nodemailer.com/usage/using-gmail/[Nodemailer Gmail documentation].
|
||||
`from`:: An email address that corresponds to *Sender*.
|
||||
`host`:: A string that corresponds to *Host*.
|
||||
`port`:: A number that corresponds to *Port*.
|
||||
`secure`:: A boolean that corresponds to *Secure*.
|
||||
`hasAuth`:: A boolean that corresponds to *Requires authentication*. If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.
|
||||
|
||||
| `service`
|
||||
| The name of a https://nodemailer.com/smtp/well-known/[well-known email service provider]. If `service` is provided, `host`, `port`, and `secure` properties are ignored. For more information on the `gmail` service value, see the (https://nodemailer.com/usage/using-gmail/)[Nodemailer Gmail documentation].
|
||||
Secrets defines sensitive information for the action type.
|
||||
|
||||
| `from`
|
||||
| An email address that corresponds to *Sender*.
|
||||
`user`:: A string that corresponds to *Username*. Required if `hasAuth` is set to `true`.
|
||||
`password`:: A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>. Required if `hasAuth` is set to `true`.
|
||||
|
||||
| `host`
|
||||
| A string that corresponds to *Host*.
|
||||
|
||||
| `port`
|
||||
| A number that corresponds to *Port*.
|
||||
|
||||
| `secure`
|
||||
| A boolean that corresponds to *Secure*.
|
||||
|
||||
| `hasAuth`
|
||||
| If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.
|
||||
|
||||
|===
|
||||
|
||||
**`secrets`** defines sensitive information for the action type and contains the following properties:
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
|
||||
| `user`
|
||||
| A string that corresponds to *User*. Required if `hasAuth` is set to `true`.
|
||||
|
||||
| `password`
|
||||
| A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>. Required if `hasAuth` is set to `true`.
|
||||
|
||||
|===
|
||||
|
||||
[float]
|
||||
[[email-action-configuration]]
|
||||
==== Action configuration
|
||||
|
||||
Email actions have the following configuration properties:
|
||||
Email actions have the following configuration properties.
|
||||
|
||||
To, CC, BCC:: Each is a list of addresses. Addresses can be specified in `user@host-name` format, or in `name <user@host-name>` format. One of To, CC, or BCC must contain an entry.
|
||||
To, CC, BCC:: Each item is a list of addresses. Addresses can be specified in `user@host-name` format, or in `name <user@host-name>` format. One of To, CC, or BCC must contain an entry.
|
||||
Subject:: The subject line of the email.
|
||||
Message:: The message text of the email. Markdown format is supported.
|
||||
|
||||
[[configuring-email]]
|
||||
==== Configuring email accounts
|
||||
==== Configuring email accounts for well-known services
|
||||
|
||||
The email action can send email using many popular SMTP email services.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,9 @@
|
|||
[role="xpack"]
|
||||
[[index-action-type]]
|
||||
=== Index action
|
||||
++++
|
||||
<titleabbrev>Index</titleabbrev>
|
||||
++++
|
||||
|
||||
The index action type will index a document into {es}. See also the {ref}/indices-create-index.html[create index API].
|
||||
|
||||
|
|
@ -8,7 +11,7 @@ The index action type will index a document into {es}. See also the {ref}/indice
|
|||
[[index-connector-configuration]]
|
||||
==== Connector configuration
|
||||
|
||||
Index connectors have the following configuration properties:
|
||||
Index connectors have the following configuration properties.
|
||||
|
||||
Name:: The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action.
|
||||
Index:: The {es} index to be written to.
|
||||
|
|
@ -30,32 +33,24 @@ Execution time field:: This field will be automatically set to the time the ale
|
|||
executionTimeField: somedate
|
||||
--
|
||||
|
||||
[[index-connector-config-properties]]
|
||||
**`config`** defines the action type specific to the configuration and contains the following properties:
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
|
||||
|`index`
|
||||
| A string that corresponds to *Index*.
|
||||
|
||||
|`refresh`
|
||||
| A boolean that corresponds to *Refresh*. Defaults to `false`.
|
||||
|
||||
|`executionTimeField`
|
||||
| A string that corresponds to *Execution time field*.
|
||||
|
||||
|===
|
||||
Config defines information for the action type.
|
||||
|
||||
`index`:: A string that corresponds to *Index*.
|
||||
`refresh`:: A boolean that corresponds to *Refresh*. Defaults to `false`.
|
||||
`executionTimeField`:: A string that corresponds to *Execution time field*.
|
||||
|
||||
[float]
|
||||
[[index-action-configuration]]
|
||||
==== Action configuration
|
||||
|
||||
Index actions have the following properties:
|
||||
Index actions have the following properties.
|
||||
|
||||
Document:: The document to index in JSON format.
|
||||
|
||||
[float]
|
||||
[[index-action-example]]
|
||||
==== Example
|
||||
|
||||
Example of the index document for Index Threshold alert:
|
||||
|
||||
[source,text]
|
||||
|
|
|
|||
|
|
@ -1,6 +1,9 @@
|
|||
[role="xpack"]
|
||||
[[jira-action-type]]
|
||||
=== Jira action
|
||||
++++
|
||||
<titleabbrev>Jira</titleabbrev>
|
||||
++++
|
||||
|
||||
The Jira action type uses the https://developer.atlassian.com/cloud/jira/platform/rest/v2/[REST API v2] to create Jira issues.
|
||||
|
||||
|
|
@ -8,7 +11,7 @@ The Jira action type uses the https://developer.atlassian.com/cloud/jira/platfor
|
|||
[[jira-connector-configuration]]
|
||||
==== Connector configuration
|
||||
|
||||
Jira connectors have the following configuration properties:
|
||||
Jira connectors have the following configuration properties.
|
||||
|
||||
Name:: The name of the connector. The name is used to identify a connector in the **Stack Management** UI connector listing, and in the connector list when configuring an action.
|
||||
URL:: Jira instance URL.
|
||||
|
|
@ -33,37 +36,21 @@ API token (or password):: Jira API authentication token (or password) for HTTP
|
|||
apiToken: tokenkeystorevalue
|
||||
--
|
||||
|
||||
[[jira-connector-config-properties]]
|
||||
**`config`** defines the action type specific to the configuration and contains the following properties:
|
||||
Config defines information for the action type.
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
`apiUrl`:: An address that corresponds to *URL*.
|
||||
`projectKey`:: A key that corresponds to *Project Key*.
|
||||
|
||||
| `apiUrl`
|
||||
| An address that corresponds to *URL*.
|
||||
Secrets defines sensitive information for the action type.
|
||||
|
||||
| `projectKey`
|
||||
| A key that corresponds to *Project Key*.
|
||||
|
||||
|===
|
||||
|
||||
**`secrets`** defines sensitive information for the action type and contains the following properties:
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
|
||||
| `email`
|
||||
| A string that corresponds to *Email*.
|
||||
|
||||
| `apiToken`
|
||||
| A string that corresponds to *API Token*. Should be stored in the <<creating-keystore, {kib} keystore>>.
|
||||
|
||||
|===
|
||||
`email`:: A string that corresponds to *Email*.
|
||||
`apiToken`:: A string that corresponds to *API Token*. Should be stored in the <<creating-keystore, {kib} keystore>>.
|
||||
|
||||
[float]
|
||||
[[jira-action-configuration]]
|
||||
==== Action configuration
|
||||
|
||||
Jira actions have the following configuration properties:
|
||||
Jira actions have the following configuration properties.
|
||||
|
||||
Issue type:: The type of the issue.
|
||||
Priority:: The priority of the incident.
|
||||
|
|
@ -74,6 +61,6 @@ Parent:: The ID or key of the parent issue. Only for `Subtask` issue types.
|
|||
Additional comments:: Additional information for the client, such as how to troubleshoot the issue.
|
||||
|
||||
[[configuring-jira]]
|
||||
==== Configuring and testing Jira
|
||||
==== Configure Jira
|
||||
|
||||
Jira offers free https://www.atlassian.com/software/jira/free[Instances], which you can use to test incidents.
|
||||
|
|
|
|||
|
|
@ -1,16 +1,66 @@
|
|||
[role="xpack"]
|
||||
[[pagerduty-action-type]]
|
||||
=== PagerDuty action
|
||||
++++
|
||||
<titleabbrev>PagerDuty</titleabbrev>
|
||||
++++
|
||||
|
||||
The PagerDuty action type uses the https://v2.developer.pagerduty.com/docs/events-api-v2[v2 Events API] to trigger, acknowledge, and resolve PagerDuty alerts.
|
||||
|
||||
* <<pagerduty-benefits, PagerDuty and Elastic integration benefits>>
|
||||
* <<pagerduty-connector-configuration, Connector configuration>>
|
||||
* <<pagerduty-action-configuration, Action configuration>>
|
||||
[float]
|
||||
[[pagerduty-connector-configuration]]
|
||||
==== Connector configuration
|
||||
|
||||
PagerDuty connectors have the following configuration properties.
|
||||
|
||||
Name:: The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action.
|
||||
API URL:: An optional PagerDuty event URL. Defaults to `https://events.pagerduty.com/v2/enqueue`. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts.
|
||||
Integration Key:: A 32 character PagerDuty Integration Key for an integration on a service, also referred to as the routing key.
|
||||
|
||||
[float]
|
||||
[[Preconfigured-pagerduty-configuration]]
|
||||
==== Preconfigured action type
|
||||
|
||||
[source,text]
|
||||
--
|
||||
my-pagerduty:
|
||||
name: preconfigured-pagerduty-action-type
|
||||
actionTypeId: .pagerduty
|
||||
config:
|
||||
apiUrl: https://test.host
|
||||
secrets:
|
||||
routingKey: testroutingkey
|
||||
--
|
||||
|
||||
Config defines information for the action type.
|
||||
|
||||
`apiURL`:: A URL string that corresponds to *API URL*.
|
||||
|
||||
Secrets defines sensitive information for the action type.
|
||||
|
||||
`routingKey`:: A string that corresponds to *Integration Key*.
|
||||
|
||||
[float]
|
||||
[[pagerduty-action-configuration]]
|
||||
==== Action configuration
|
||||
|
||||
PagerDuty actions have the following properties.
|
||||
|
||||
Severity:: The perceived severity of on the affected system. This can be one of `Critical`, `Error`, `Warning` or `Info`(default).
|
||||
Event action:: One of `Trigger` (default), `Resolve`, or `Acknowledge`. See https://v2.developer.pagerduty.com/docs/events-api-v2#event-action[event action] for more details.
|
||||
Dedup Key:: All actions sharing this key will be associated with the same PagerDuty alert. This value is used to correlate trigger and resolution. This value is *optional*, and if not set, defaults to `<alert ID>:<alert instance ID>`. The maximum length is *255* characters. See https://v2.developer.pagerduty.com/docs/events-api-v2#alert-de-duplication[alert deduplication] for details.
|
||||
Timestamp:: An *optional* https://v2.developer.pagerduty.com/v2/docs/types#datetime[ISO-8601 format date-time], indicating the time the event was detected or generated.
|
||||
Component:: An *optional* value indicating the component of the source machine that is responsible for the event, for example `mysql` or `eth0`.
|
||||
Group:: An *optional* value indicating the logical grouping of components of a service, for example `app-stack`.
|
||||
Source:: An *optional* value indicating the affected system, preferably a hostname or fully qualified domain name. Defaults to the {kib} saved object id of the action.
|
||||
Summary:: An *optional* text summary of the event, defaults to `No summary provided`. The maximum length is 1024 characters.
|
||||
Class:: An *optional* value indicating the class/type of the event, for example `ping failure` or `cpu load`.
|
||||
|
||||
For more details on these properties, see https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2[PagerDuty v2 event parameters].
|
||||
|
||||
[float]
|
||||
[[pagerduty-benefits]]
|
||||
==== PagerDuty + Elastic integration benefits
|
||||
==== Configure PagerDuty
|
||||
|
||||
By integrating PagerDuty with alerts, you can:
|
||||
|
||||
|
|
@ -18,33 +68,6 @@ By integrating PagerDuty with alerts, you can:
|
|||
* Automatically generate incidents of different types and severity based on each alert’s context.
|
||||
* Tailor the incident data to match your needs by easily passing the alerting context from Kibana to PagerDuty.
|
||||
|
||||
[float]
|
||||
[[pagerduty-how-it-works]]
|
||||
===== How it works
|
||||
|
||||
{kib} allows you to create alerts to notify you of a significant move
|
||||
in your dataset.
|
||||
You can create alerts for all your Observability, Security, and Elastic Stack use cases.
|
||||
Alerts will trigger a new incident on the corresponding PagerDuty service.
|
||||
|
||||
[float]
|
||||
===== Requirements
|
||||
|
||||
In the `kibana.yml` configuration file, you must add the <<general-alert-action-settings, saved objects encryption setting>>.
|
||||
This is required to encrypt parameters that must be secured, for example PagerDuty’s integration key.
|
||||
|
||||
If you have security enabled:
|
||||
|
||||
* You must have
|
||||
application privileges to access Metrics, APM, Uptime, or Security.
|
||||
* If you are using a self-managed deployment with security, you must have
|
||||
Transport Security Layer (TLS) enabled for communication <<configuring-tls-kib-es, between Elasticsearch and Kibana>>.
|
||||
Alerts uses API keys to secure background alert checks and actions,
|
||||
and API keys require {ref}/configuring-tls.html#tls-http[TLS on the HTTP interface].
|
||||
|
||||
Although not a requirement, to harden the integrations security you might want to
|
||||
review the <<action-settings, Actions settings>> that are available to you.
|
||||
|
||||
[float]
|
||||
[[pagerduty-support]]
|
||||
===== Support
|
||||
|
|
@ -111,80 +134,3 @@ To see the available context variables, click on the *Add alert variable* icon n
|
|||
to each corresponding field. For more details on these parameters, see the
|
||||
<<pagerduty-action-configuration, Actions Configuration>> and the PagerDuty
|
||||
https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2[API v2 documentation].
|
||||
|
||||
|
||||
[float]
|
||||
[[pagerduty-uninstall]]
|
||||
===== How to uninstall
|
||||
To remove a PagerDuty connector from an alert, simply remove it
|
||||
from the *Actions* section of that alert, using the remove (x) icon.
|
||||
This will disable the integration for the particular alert.
|
||||
|
||||
To delete the connector entirely, open the main menu, then click *Stack Management > Alerts and Actions*.
|
||||
Select the *Connectors* tab, and then click on the delete icon.
|
||||
This is an irreversible action and impacts all alerts that use this connector.
|
||||
|
||||
|
||||
[float]
|
||||
[[pagerduty-connector-configuration]]
|
||||
==== Connector configuration
|
||||
|
||||
PagerDuty connectors have the following configuration properties:
|
||||
|
||||
Name:: The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action.
|
||||
API URL:: An optional PagerDuty event URL. Defaults to `https://events.pagerduty.com/v2/enqueue`. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts.
|
||||
Integration Key:: A 32 character PagerDuty Integration Key for an integration on a service, also referred to as the routing key.
|
||||
|
||||
[float]
|
||||
[[Preconfigured-pagerduty-configuration]]
|
||||
==== Preconfigured action type
|
||||
|
||||
[source,text]
|
||||
--
|
||||
my-pagerduty:
|
||||
name: preconfigured-pagerduty-action-type
|
||||
actionTypeId: .pagerduty
|
||||
config:
|
||||
apiUrl: https://test.host
|
||||
secrets:
|
||||
routingKey: testroutingkey
|
||||
--
|
||||
|
||||
[[pagerduty-connector-config-properties]]
|
||||
**`config`** defines the action type specific to the configuration and contains the following properties:
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
|
||||
|`apiURL`
|
||||
| A URL string that corresponds to *API URL*.
|
||||
|
||||
|===
|
||||
|
||||
**`secrets`** defines sensitive information for the action type and contains the following properties:
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
|
||||
|`routingKey`
|
||||
| A string that corresponds to *Integration Key*.
|
||||
|
||||
|===
|
||||
|
||||
[float]
|
||||
[[pagerduty-action-configuration]]
|
||||
==== Action configuration
|
||||
|
||||
PagerDuty actions have the following properties:
|
||||
|
||||
Severity:: The perceived severity of on the affected system. This can be one of `Critical`, `Error`, `Warning` or `Info`(default).
|
||||
Event action:: One of `Trigger` (default), `Resolve`, or `Acknowledge`. See https://v2.developer.pagerduty.com/docs/events-api-v2#event-action[event action] for more details.
|
||||
Dedup Key:: All actions sharing this key will be associated with the same PagerDuty alert. This value is used to correlate trigger and resolution. This value is *optional*, and if not set, defaults to `<alert ID>:<alert instance ID>`. The maximum length is *255* characters. See https://v2.developer.pagerduty.com/docs/events-api-v2#alert-de-duplication[alert deduplication] for details.
|
||||
Timestamp:: An *optional* https://v2.developer.pagerduty.com/v2/docs/types#datetime[ISO-8601 format date-time], indicating the time the event was detected or generated.
|
||||
Component:: An *optional* value indicating the component of the source machine that is responsible for the event, for example `mysql` or `eth0`.
|
||||
Group:: An *optional* value indicating the logical grouping of components of a service, for example `app-stack`.
|
||||
Source:: An *optional* value indicating the affected system, preferably a hostname or fully qualified domain name. Defaults to the {kib} saved object id of the action.
|
||||
Summary:: An *optional* text summary of the event, defaults to `No summary provided`. The maximum length is 1024 characters.
|
||||
Class:: An *optional* value indicating the class/type of the event, for example `ping failure` or `cpu load`.
|
||||
|
||||
For more details on these properties, see https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2[PagerDuty v2 event parameters].
|
||||
|
|
|
|||
|
|
@ -1,6 +1,9 @@
|
|||
[role="xpack"]
|
||||
[[resilient-action-type]]
|
||||
=== IBM Resilient action
|
||||
++++
|
||||
<titleabbrev>IBM Resilient</titleabbrev>
|
||||
++++
|
||||
|
||||
The IBM Resilient action type uses the https://developer.ibm.com/security/resilient/rest/[RESILIENT REST v2] to create IBM Resilient incidents.
|
||||
|
||||
|
|
@ -8,7 +11,7 @@ The IBM Resilient action type uses the https://developer.ibm.com/security/resili
|
|||
[[resilient-connector-configuration]]
|
||||
==== Connector configuration
|
||||
|
||||
IBM Resilient connectors have the following configuration properties:
|
||||
IBM Resilient connectors have the following configuration properties.
|
||||
|
||||
Name:: The name of the connector. The name is used to identify a connector in the **Stack Management** UI connector listing, and in the connector list when configuring an action.
|
||||
URL:: IBM Resilient instance URL.
|
||||
|
|
@ -33,37 +36,21 @@ API key secret:: The authentication key secret for HTTP Basic authentication.
|
|||
apiKeySecret: tokenkeystorevalue
|
||||
--
|
||||
|
||||
[[resilient-connector-config-properties]]
|
||||
**`config`** defines the action type specific to the configuration and contains the following properties:
|
||||
Config defines information for the action type.
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
`apiUrl`:: An address that corresponds to *URL*.
|
||||
`orgId`:: An ID that corresponds to *Organization ID*.
|
||||
|
||||
| `apiUrl`
|
||||
| An address that corresponds to *URL*.
|
||||
Secrets defines sensitive information for the action type.
|
||||
|
||||
| `orgId`
|
||||
| An ID that corresponds to *Organization ID*.
|
||||
|
||||
|===
|
||||
|
||||
**`secrets`** defines sensitive information for the action type and contains the following properties:
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
|
||||
| `apiKeyId`
|
||||
| A string that corresponds to *API key ID*.
|
||||
|
||||
| `apiKeySecret`
|
||||
| A string that corresponds to *API Key secret*. Should be stored in the <<creating-keystore, {kib} keystore>>.
|
||||
|
||||
|===
|
||||
`apiKeyId`:: A string that corresponds to *API key ID*.
|
||||
`apiKeySecret`:: A string that corresponds to *API Key secret*. Should be stored in the <<creating-keystore, {kib} keystore>>.
|
||||
|
||||
[float]
|
||||
[[resilient-action-configuration]]
|
||||
==== Action configuration
|
||||
|
||||
IBM Resilient actions have the following configuration properties:
|
||||
IBM Resilient actions have the following configuration properties.
|
||||
|
||||
Incident types:: The type of the incident.
|
||||
Severity code:: The severity of the incident.
|
||||
|
|
@ -72,6 +59,6 @@ Description:: The details about the incident.
|
|||
Additional comments:: Additional information for the client, such as how to troubleshoot the issue.
|
||||
|
||||
[[configuring-resilient]]
|
||||
==== Configuring and testing IBM Resilient
|
||||
==== Configure IBM Resilient
|
||||
|
||||
IBM Resilient offers https://www.ibm.com/security/intelligent-orchestration/resilient[Instances], which you can use to test incidents.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,9 @@
|
|||
[role="xpack"]
|
||||
[[server-log-action-type]]
|
||||
=== Server log action
|
||||
++++
|
||||
<titleabbrev>Server log</titleabbrev>
|
||||
++++
|
||||
|
||||
This action type writes an entry to the {kib} server log.
|
||||
|
||||
|
|
@ -8,7 +11,7 @@ This action type writes an entry to the {kib} server log.
|
|||
[[server-log-connector-configuration]]
|
||||
==== Connector configuration
|
||||
|
||||
Server log connectors have the following configuration properties:
|
||||
Server log connectors have the following configuration properties.
|
||||
|
||||
Name:: The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action.
|
||||
|
||||
|
|
@ -27,7 +30,7 @@ Name:: The name of the connector. The name is used to identify a connector
|
|||
[[server-log-action-configuration]]
|
||||
==== Action configuration
|
||||
|
||||
Server log actions have the following properties:
|
||||
Server log actions have the following properties.
|
||||
|
||||
Message:: The message to log.
|
||||
Level:: The log level of the message: `trace`, `debug`, `info`, `warn`, `error` or `fatal`. Defaults to `info`.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,9 @@
|
|||
[role="xpack"]
|
||||
[[servicenow-action-type]]
|
||||
=== ServiceNow action
|
||||
++++
|
||||
<titleabbrev>ServiceNow</titleabbrev>
|
||||
++++
|
||||
|
||||
The ServiceNow action type uses the https://developer.servicenow.com/app.do#!/rest_api_doc?v=orlando&id=c_TableAPI[V2 Table API] to create ServiceNow incidents.
|
||||
|
||||
|
|
@ -8,7 +11,7 @@ The ServiceNow action type uses the https://developer.servicenow.com/app.do#!/re
|
|||
[[servicenow-connector-configuration]]
|
||||
==== Connector configuration
|
||||
|
||||
ServiceNow connectors have the following configuration properties:
|
||||
ServiceNow connectors have the following configuration properties.
|
||||
|
||||
Name:: The name of the connector. The name is used to identify a connector in the **Stack Management** UI connector listing, and in the connector list when configuring an action.
|
||||
URL:: ServiceNow instance URL.
|
||||
|
|
@ -31,34 +34,20 @@ Password:: Password for HTTP Basic authentication.
|
|||
password: passwordkeystorevalue
|
||||
--
|
||||
|
||||
[[servicenow-connector-config-properties]]
|
||||
**`config`** defines the action type specific to the configuration and contains the following properties:
|
||||
Config defines information for the action type.
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
`apiUrl`:: An address that corresponds to *URL*.
|
||||
|
||||
| `apiUrl`
|
||||
| An address that corresponds to *URL*.
|
||||
Secrets defines sensitive information for the action type.
|
||||
|
||||
|===
|
||||
|
||||
**`secrets`** defines sensitive information for the action type and contains the following properties:
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
|
||||
| `username`
|
||||
| A string that corresponds to *Username*.
|
||||
|
||||
| `password`
|
||||
| A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>.
|
||||
|
||||
|===
|
||||
`username`:: A string that corresponds to *Username*.
|
||||
`password`:: A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>.
|
||||
|
||||
[float]
|
||||
[[servicenow-action-configuration]]
|
||||
==== Action configuration
|
||||
|
||||
ServiceNow actions have the following configuration properties:
|
||||
ServiceNow actions have the following configuration properties.
|
||||
|
||||
Urgency:: The extent to which the incident resolution can delay.
|
||||
Severity:: The severity of the incident.
|
||||
|
|
@ -68,6 +57,6 @@ Description:: The details about the incident.
|
|||
Additional comments:: Additional information for the client, such as how to troubleshoot the issue.
|
||||
|
||||
[[configuring-servicenow]]
|
||||
==== Configuring and testing ServiceNow
|
||||
==== Configure ServiceNow
|
||||
|
||||
ServiceNow offers free https://developer.servicenow.com/dev.do#!/guides/madrid/now-platform/pdi-guide/obtaining-a-pdi[Personal Developer Instances], which you can use to test incidents.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,9 @@
|
|||
[role="xpack"]
|
||||
[[slack-action-type]]
|
||||
=== Slack action
|
||||
++++
|
||||
<titleabbrev>Slack</titleabbrev>
|
||||
++++
|
||||
|
||||
The Slack action type uses https://api.slack.com/incoming-webhooks[Slack Incoming Webhooks].
|
||||
|
||||
|
|
@ -8,7 +11,7 @@ The Slack action type uses https://api.slack.com/incoming-webhooks[Slack Incomin
|
|||
[[slack-connector-configuration]]
|
||||
==== Connector configuration
|
||||
|
||||
Slack connectors have the following configuration properties:
|
||||
Slack connectors have the following configuration properties.
|
||||
|
||||
Name:: The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action.
|
||||
Webhook URL:: The URL of the incoming webhook. See https://api.slack.com/messaging/webhooks#getting_started[Slack Incoming Webhooks] for instructions on generating this URL. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts.
|
||||
|
|
@ -26,29 +29,20 @@ Webhook URL:: The URL of the incoming webhook. See https://api.slack.com/messa
|
|||
webhookUrl: 'https://hooks.slack.com/services/abcd/efgh/ijklmnopqrstuvwxyz'
|
||||
--
|
||||
|
||||
**`secrets`** defines sensitive information for the action type and contains the following properties:
|
||||
Secrets defines sensitive information for the action type.
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
|
||||
| `webhookUrl`
|
||||
| A string that corresponds to *Webhook URL*.
|
||||
|
||||
|===
|
||||
`webhookUrl`:: A string that corresponds to *Webhook URL*.
|
||||
|
||||
[float]
|
||||
[[slack-action-configuration]]
|
||||
==== Action configuration
|
||||
|
||||
Slack actions have the following properties:
|
||||
Slack actions have the following properties.
|
||||
|
||||
Message:: The message text, converted to the `text` field in the Webhook JSON payload. Currently only the text field is supported. Markdown, images, and other advanced formatting are not yet supported.
|
||||
|
||||
[[configuring-slack]]
|
||||
==== Configuring Slack Accounts
|
||||
|
||||
You configure the accounts Slack action type can use to communicate with Slack in the
|
||||
connector form.
|
||||
==== Configure a Slack account
|
||||
|
||||
You need a https://api.slack.com/incoming-webhooks[Slack webhook URL] to
|
||||
configure a Slack account. To create a webhook
|
||||
|
|
|
|||
|
|
@ -1,6 +1,9 @@
|
|||
[role="xpack"]
|
||||
[[teams-action-type]]
|
||||
=== Microsoft Teams action
|
||||
++++
|
||||
<titleabbrev>Microsoft Teams</titleabbrev>
|
||||
++++
|
||||
|
||||
The Microsoft Teams action type uses https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook[Incoming Webhooks].
|
||||
|
||||
|
|
@ -8,7 +11,7 @@ The Microsoft Teams action type uses https://docs.microsoft.com/en-us/microsoftt
|
|||
[[teams-connector-configuration]]
|
||||
==== Connector configuration
|
||||
|
||||
Microsoft Teams connectors have the following configuration properties:
|
||||
Microsoft Teams connectors have the following configuration properties.
|
||||
|
||||
Name:: The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action.
|
||||
Webhook URL:: The URL of the incoming webhook. See https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook#add-an-incoming-webhook-to-a-teams-channel[Add Incoming Webhooks] for instructions on generating this URL. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts.
|
||||
|
|
@ -26,28 +29,20 @@ Webhook URL:: The URL of the incoming webhook. See https://docs.microsoft.com/
|
|||
webhookUrl: 'https://outlook.office.com/webhook/abcd@0123456/IncomingWebhook/abcdefgh/ijklmnopqrstuvwxyz'
|
||||
--
|
||||
|
||||
[[teams-connector-config-properties]]
|
||||
**`secrets`** defines sensitive information for the action type and contains the following properties:
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
|
||||
| `webhookUrl`
|
||||
| A string that corresponds to *Webhook URL*.
|
||||
|
||||
|===
|
||||
Secrets defines sensitive information for the action type.
|
||||
|
||||
`webhookUrl`:: A string that corresponds to *Webhook URL*.
|
||||
|
||||
[float]
|
||||
[[teams-action-configuration]]
|
||||
==== Action configuration
|
||||
|
||||
Microsoft Teams actions have the following properties:
|
||||
Microsoft Teams actions have the following properties.
|
||||
|
||||
Message:: The message text, converted to the `text` field in the Webhook JSON payload. Currently only the text field is supported. Markdown, images, and other advanced formatting are not yet supported.
|
||||
|
||||
[[configuring-teams]]
|
||||
==== Configuring Microsoft Teams Accounts
|
||||
==== Configure a Microsoft Teams account
|
||||
|
||||
You need a https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook[Microsoft Teams webhook URL] to
|
||||
configure a Microsoft Teams action. To create a webhook
|
||||
|
|
|
|||
|
|
@ -1,6 +1,9 @@
|
|||
[role="xpack"]
|
||||
[[webhook-action-type]]
|
||||
=== Webhook action
|
||||
++++
|
||||
<titleabbrev>Webhook</titleabbrev>
|
||||
++++
|
||||
|
||||
The Webhook action type uses https://github.com/axios/axios[axios] to send a POST or PUT request to a web service.
|
||||
|
||||
|
|
@ -8,13 +11,14 @@ The Webhook action type uses https://github.com/axios/axios[axios] to send a POS
|
|||
[[webhook-connector-configuration]]
|
||||
==== Connector configuration
|
||||
|
||||
Webhook connectors have the following configuration properties:
|
||||
Webhook connectors have the following configuration properties.
|
||||
|
||||
Name:: The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action.
|
||||
URL:: The request URL. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts.
|
||||
Method:: HTTP request method, either `POST`(default) or `PUT`.
|
||||
Headers:: A set of key-value pairs sent as headers with the request
|
||||
User:: Username for HTTP basic authentication.
|
||||
Require authentication:: If true, a username and password for login type authentication must be provided.
|
||||
Username:: Username for HTTP basic authentication.
|
||||
Password:: Password for HTTP basic authentication.
|
||||
|
||||
[float]
|
||||
|
|
@ -36,45 +40,23 @@ Password:: Password for HTTP basic authentication.
|
|||
password: passwordkeystorevalue
|
||||
--
|
||||
|
||||
[[webhook-connector-config-properties]]
|
||||
**`config`** defines the action type specific to the configuration and contains the following properties:
|
||||
Config defines information for the action type.
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
`url`:: A URL string that corresponds to *URL*.
|
||||
`method`:: A string that corresponds to *Method*.
|
||||
`headers`:: A record<string, string> that corresponds to *Headers*.
|
||||
`hasAuth`:: A boolean that corresponds to *Requires authentication*. If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.
|
||||
|
||||
|`url`
|
||||
| A URL string that corresponds to *URL*.
|
||||
|
||||
|`method`
|
||||
| A string that corresponds to *Method*.
|
||||
|
||||
|`headers`
|
||||
|A record<string, string> that corresponds to *Headers*.
|
||||
|
||||
| `hasAuth`
|
||||
| If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.
|
||||
|
||||
|===
|
||||
|
||||
**`secrets`** defines sensitive information for the action type and contains the following properties:
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
|
||||
|`user`
|
||||
|A string that corresponds to *User*. Required if `hasAuth` is set to `true`.
|
||||
|
||||
|`password`
|
||||
|A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>. Required if `hasAuth` is set to `true`.
|
||||
|
||||
|===
|
||||
Secrets defines sensitive information for the action type.
|
||||
|
||||
`user`:: A string that corresponds to *User*. Required if `hasAuth` is set to `true`.
|
||||
`password`:: A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>. Required if `hasAuth` is set to `true`.
|
||||
|
||||
[float]
|
||||
[[webhook-action-configuration]]
|
||||
==== Action configuration
|
||||
|
||||
Webhook actions have the following properties:
|
||||
Webhook actions have the following properties.
|
||||
|
||||
Body:: A JSON payload sent to the request URL. For example:
|
||||
+
|
||||
|
|
|
|||
|
|
@ -10,14 +10,13 @@ Kibana provides two types of alerts:
|
|||
[float]
|
||||
==== Standard stack alerts
|
||||
|
||||
Users require the `all` privilege to access to the *Stack Alerts* feature and create and edit alerts. .
|
||||
See <<kibana-feature-privileges, feature privileges>> for more information.
|
||||
|
||||
{kib} provides two stack alerts:
|
||||
|
||||
* <<alert-type-index-threshold>>
|
||||
* <<alert-type-es-query>>
|
||||
|
||||
Users require the `all` privilege to access the *Stack Alerts* feature and create and edit alerts.
|
||||
See <<kibana-feature-privileges, feature privileges>> for more information.
|
||||
|
||||
[float]
|
||||
==== Domain-specific alerts
|
||||
|
|
|
|||
|
|
@ -5,9 +5,9 @@
|
|||
{kib} alerts can be created in a variety of apps including <<xpack-apm,*APM*>>, <<xpack-ml,*{ml-app}*>>, <<metrics-app,*Metrics*>>, <<xpack-siem,*Security*>>, <<uptime-app,*Uptime*>> and from <<management,*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.
|
||||
|
||||
[float]
|
||||
=== Alert flyout
|
||||
=== Create an alert
|
||||
|
||||
When an alert is created in an app, the app will display a flyout panel with three main sections to configure:
|
||||
When you create an alert, you must define the alert details, conditions, and actions.
|
||||
|
||||
. <<defining-alerts-general-details, General alert details>>
|
||||
. <<defining-alerts-type-conditions, Alert type and conditions>>
|
||||
|
|
@ -19,7 +19,7 @@ image::images/alert-flyout-sections.png[The three sections of an alert definitio
|
|||
[[defining-alerts-general-details]]
|
||||
=== General alert details
|
||||
|
||||
All alerts share the following four properties in common:
|
||||
All alerts share the following four properties.
|
||||
|
||||
[role="screenshot"]
|
||||
image::images/alert-flyout-general-details.png[alt='All alerts have name, tags, check every, and notify properties in common']
|
||||
|
|
@ -69,6 +69,7 @@ Each action type exposes different properties. For example an email action allow
|
|||
image::images/alert-flyout-action-details.png[UI for defining an email action]
|
||||
|
||||
[float]
|
||||
[[defining-alerts-actions-variables]]
|
||||
==== Action variables
|
||||
Using the https://mustache.github.io/[Mustache] template syntax `{{variable name}}`, you can pass alert values at the time a condition is detected to an action. You can access the list of available variables using the "add variable" button. Although available variables differ by alert type, all alert types pass the following variables:
|
||||
|
||||
|
|
@ -105,6 +106,6 @@ Actions are not required on alerts. You can run an alert without actions to unde
|
|||
==============================================
|
||||
|
||||
[float]
|
||||
=== Managing alerts
|
||||
=== Manage alerts
|
||||
|
||||
To modify an alert after it was created, including muting or disabling it, use the <<alert-management, alert listing in the Management UI>>.
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 41 KiB After Width: | Height: | Size: 21 KiB |
|
|
@ -2,24 +2,20 @@
|
|||
[[alert-type-es-query]]
|
||||
=== ES query
|
||||
|
||||
The ES query alert type is designed to run a user-configured {es} query over indices, compare the number of matches to a configured threshold, and schedule
|
||||
actions to run when the threshold condition is met.
|
||||
The ES query alert type runs a user-configured {es} query, compares the number of matches to a configured threshold, and schedules actions to run when the threshold condition is met.
|
||||
|
||||
[float]
|
||||
==== Creating the alert
|
||||
==== Create the alert
|
||||
|
||||
An ES query alert can be created from the *Create* button in the <<alert-management, alert management UI>>. Fill in the <<defining-alerts-general-details, general alert details>>, then select *ES query*.
|
||||
|
||||
[role="screenshot"]
|
||||
image::user/alerting/images/alert-types-es-query-select.png[Choosing an ES query alert type]
|
||||
Fill in the <<defining-alerts-general-details, alert details>>, then select *ES query*.
|
||||
|
||||
[float]
|
||||
==== Defining the conditions
|
||||
==== Define the conditions
|
||||
|
||||
The ES query alert has 5 clauses that define the condition to detect.
|
||||
Define properties to detect the condition.
|
||||
|
||||
[role="screenshot"]
|
||||
image::user/alerting/images/alert-types-es-query-conditions.png[Four clauses define the condition to detect]
|
||||
image::user/alerting/images/alert-types-es-query-conditions.png[Five clauses define the condition to detect]
|
||||
|
||||
Index:: This clause requires an *index or index pattern* and a *time field* that will be used for the *time window*.
|
||||
Size:: This clause specifies the number of documents to pass to the configured actions when the the threshold condition is met.
|
||||
|
|
@ -29,9 +25,9 @@ Threshold:: This clause defines a threshold value and a comparison operator (`i
|
|||
Time window:: This clause determines how far back to search for documents, using the *time field* set in the *index* clause. Generally this value should be set to a value higher than the *check every* value in the <<defining-alerts-general-details, general alert details>>, to avoid gaps in detection.
|
||||
|
||||
[float]
|
||||
==== Action variables
|
||||
==== Add action variables
|
||||
|
||||
When the ES query alert condition is met, the following variables are available to use inside each action:
|
||||
<<defining-alerts-actions-details, Add an action>> to run when the alert condition is met. The following variables are specific to the ES query alert. You can also specify <<defining-alerts-actions-variables, variables common to all alerts>>.
|
||||
|
||||
`context.title`:: A preconstructed title for the alert. Example: `alert term match alert query matched`.
|
||||
`context.message`:: A preconstructed message for the alert. Example: +
|
||||
|
|
@ -45,22 +41,23 @@ When the ES query alert condition is met, the following variables are available
|
|||
`context.value`:: The value of the alert that met the condition.
|
||||
`context.conditions`:: A description of the condition. Example: `count greater than 4`.
|
||||
`context.hits`:: The most recent ES documents that matched the query. Using the https://mustache.github.io/[Mustache] template array syntax, you can iterate over these hits to get values from the ES documents into your actions.
|
||||
|
||||
+
|
||||
[role="screenshot"]
|
||||
image::images/alert-types-es-query-example-action-variable.png[Iterate over hits using Mustache template syntax]
|
||||
|
||||
|
||||
[float]
|
||||
==== Testing your query
|
||||
==== Test your query
|
||||
|
||||
Use the *Test query* feature to verify that your query DSL is valid.
|
||||
|
||||
When your query is valid:: Valid queries will be executed against the configured *index* using the configured *time window*. The number of documents that
|
||||
* Valid queries are executed against the configured *index* using the configured *time window*. The number of documents that
|
||||
match the query will be displayed.
|
||||
|
||||
+
|
||||
[role="screenshot"]
|
||||
image::user/alerting/images/alert-types-es-query-valid.png[Test ES query returns number of matches when valid]
|
||||
|
||||
When your query is invalid:: An error message is shown if the query is invalid.
|
||||
|
||||
* An error message is shown if the query is invalid.
|
||||
+
|
||||
[role="screenshot"]
|
||||
image::user/alerting/images/alert-types-es-query-invalid.png[Test ES query shows error when invalid]
|
||||
|
|
@ -2,20 +2,17 @@
|
|||
[[alert-type-index-threshold]]
|
||||
=== Index threshold
|
||||
|
||||
The index threshold alert type is designed to run an {es} query over indices, aggregating field values from documents, comparing them to threshold values, and scheduling actions to run when the thresholds are met.
|
||||
The index threshold alert type runs an {es} query. It aggregates field values from documents, compares them to threshold values, and schedules actions to run when the thresholds are met.
|
||||
|
||||
[float]
|
||||
==== Creating the alert
|
||||
==== Create the alert
|
||||
|
||||
An index threshold alert can be created from the *Create* button in the <<alert-management, alert management UI>>. Fill in the <<defining-alerts-general-details, general alert details>>, then select *Index Threshold*.
|
||||
|
||||
[role="screenshot"]
|
||||
image::user/alerting/images/alert-types-index-threshold-select.png[Choosing an index threshold alert type]
|
||||
Fill in the <<defining-alerts-general-details, alert details>>, then select *Index Threshold*.
|
||||
|
||||
[float]
|
||||
==== Defining the conditions
|
||||
==== Define the conditions
|
||||
|
||||
The index threshold has 5 clauses that define the condition to detect.
|
||||
Define properties to detect the condition.
|
||||
|
||||
[role="screenshot"]
|
||||
image::user/alerting/images/alert-types-index-threshold-conditions.png[Five clauses define the condition to detect]
|
||||
|
|
@ -32,9 +29,9 @@ If data is available and all clauses have been defined, a preview chart will ren
|
|||
image::user/alerting/images/alert-types-index-threshold-preview.png[Five clauses define the condition to detect]
|
||||
|
||||
[float]
|
||||
==== Action variables
|
||||
==== Add action variables
|
||||
|
||||
When the index threshold alert condition is met, the following variables are available to use inside each action:
|
||||
<<defining-alerts-actions-details, Add an action>> to run when the alert condition is met. The following variables are specific to the index threshold alert. You can also specify <<defining-alerts-actions-variables, variables common to all alerts>>.
|
||||
|
||||
`context.title`:: A preconstructed title for the alert. Example: `alert kibana sites - high egress met threshold`.
|
||||
`context.message`:: A preconstructed message for the alert. Example: +
|
||||
|
|
@ -51,68 +48,53 @@ When the index threshold alert condition is met, the following variables are ava
|
|||
[float]
|
||||
==== Example
|
||||
|
||||
In this section, you will use the {kib} <<add-sample-data, weblog sample dataset>> to setup and tune the conditions on an index threshold alert. For this example, we want to detect when any of our top three sites have served more than 420,000 bytes over a 24 hour period.
|
||||
In this example, you will use the {kib} <<add-sample-data, sample weblog dataset>> to set up and tune the conditions on an index threshold alert. For this example, you want to detect when any of the top four sites serve more than 420,000 bytes over a 24 hour period.
|
||||
|
||||
From the <<alert-management, alert management UI>>, create a new alert, and fill in the <<defining-alerts-general-details, general alert details>>. This alert will be checked every 4 hours, and will not execute actions more than once per day. Choose the index threshold alert type.
|
||||
. Open the main menu, then click **Stack Management > Alerts and Actions**.
|
||||
|
||||
. Create a new alert that is checked every four hours and executes actions when the alert status changes.
|
||||
+
|
||||
[role="screenshot"]
|
||||
image::user/alerting/images/alert-types-index-threshold-select.png[Choosing an index threshold alert type]
|
||||
|
||||
Click on each clause to open a control that helps you set the value:
|
||||
|
||||
[float]
|
||||
==== Index clause
|
||||
The index clause control will list and allow you to search for available indices. Choose *kibana_sample_data_logs*
|
||||
. Select the **Index threshold** alert type.
|
||||
|
||||
. Click *Index*, and set *Indices to query* to *kibana_sample_data_logs*.
|
||||
+
|
||||
[role="screenshot"]
|
||||
image::user/alerting/images/alert-types-index-threshold-example-index.png[Choosing an index]
|
||||
|
||||
Once an index is selected, the list of time fields for that index will be available to select. Choose *@timestamp*.
|
||||
|
||||
. Set the *Time field* to *@timestamp*.
|
||||
+
|
||||
[role="screenshot"]
|
||||
image::user/alerting/images/alert-types-index-threshold-example-timefield.png[Choosing a time field]
|
||||
|
||||
[float]
|
||||
==== When clause
|
||||
|
||||
We want to detect the number of bytes served during the time window, so we select `sum` as the aggregation, and `bytes` as the field to aggregate.
|
||||
|
||||
. To detect the number of bytes served during the time window, click *When* and select `sum` as the aggregation, and bytes as the field to aggregate.
|
||||
+
|
||||
[role="screenshot"]
|
||||
image::user/alerting/images/alert-types-index-threshold-example-aggregation.png[Choosing the aggregation]
|
||||
|
||||
[float]
|
||||
==== Over/Grouped over clause
|
||||
|
||||
We want to alert on the three sites that have the most traffic, so we'll group the sum of bytes by the `host.keyword` field and take the top 3 values.
|
||||
|
||||
. To detect the four sites that have the most traffic, click *Over* and select `top`, enter `4`, and select `host.keyword` as the field.
|
||||
+
|
||||
[role="screenshot"]
|
||||
image::user/alerting/images/alert-types-index-threshold-example-grouping.png[Choosing the groups]
|
||||
|
||||
[float]
|
||||
==== Threshold clause
|
||||
|
||||
We want to alert when any site exceeds 420,000 bytes over a 24 hour period, so we'll set the threshold to 420,000 and use the `is above` comparison.
|
||||
|
||||
. To alert when any of the top four sites exceeds 420,000 bytes over a 24 hour period, select `is above` and enter `420000`.
|
||||
+
|
||||
[role="screenshot"]
|
||||
image::user/alerting/images/alert-types-index-threshold-example-threshold.png[Setting the threshold]
|
||||
|
||||
[float]
|
||||
==== Time window clause
|
||||
|
||||
Finally, set the time window to 24 hours to complete the alert configuration.
|
||||
|
||||
. Finally, click *For the last*, enter `24` and select `hours` to complete the alert configuration.
|
||||
+
|
||||
[role="screenshot"]
|
||||
image::user/alerting/images/alert-types-index-threshold-example-window.png[Setting the time window]
|
||||
|
||||
The preview chart will render showing the 24 hour sum of bytes at 4 hours intervals (the *check every* interval) for the past 120 hours (the last 30 intervals).
|
||||
|
||||
. The preview chart will render showing the 24 hour sum of bytes at 4 hours intervals (the *check every* interval) for the past 120 hours (the last 30 intervals).
|
||||
+
|
||||
[role="screenshot"]
|
||||
image::user/alerting/images/alert-types-index-threshold-example-preview.png[Setting the time window]
|
||||
|
||||
[float]
|
||||
==== Comparing time windows
|
||||
|
||||
You can interactively change the time window and observe the effect it has on the chart. Compare a 24 window to a 12 hour window. Notice the variability in the sum of bytes, due to different traffic levels during the day compared to at night. This variability would result in noisy alerts, so the 24 hour window is better. The preview chart can help you find the right values for your alert.
|
||||
|
||||
. Change the time window and observe the effect it has on the chart. Compare a 24 window to a 12 hour window. Notice the variability in the sum of bytes, due to different traffic levels during the day compared to at night. This variability would result in noisy alerts, so the 24 hour window is better. The preview chart can help you find the right values for your alert.
|
||||
+
|
||||
[role="screenshot"]
|
||||
image::user/alerting/images/alert-types-index-threshold-example-comparison.png[Comparing two time windows]
|
||||
|
|
@ -434,7 +434,9 @@ Actions that take URLs or hostnames should check that those values are allowed.
|
|||
|
||||
## documentation
|
||||
|
||||
You should also create some asciidoc for the new action type. An entry should be made in the action type index - [`docs/user/alerting/action-types.asciidoc`](../../../docs/user/alerting/action-types.asciidoc) which points to a new document for the action type that should be in the directory [`docs/user/alerting/action-types`](../../../docs/user/alerting/action-types).
|
||||
You should create asciidoc for the new action type. Add an entry to the action type index - [`docs/user/alerting/action-types.asciidoc`](../../../docs/user/alerting/action-types.asciidoc), which points to a new document for the action type that should be in the directory [`docs/user/alerting/action-types`](../../../docs/user/alerting/action-types).
|
||||
|
||||
We suggest following the template provided in `docs/action-type-template.asciidoc`. The [Email action type](https://www.elastic.co/guide/en/kibana/master/email-action-type.html) is an example of documentation created following the template.
|
||||
|
||||
## tests
|
||||
|
||||
|
|
|
|||
|
|
@ -19,9 +19,10 @@ Table of Contents
|
|||
- [Alert types](#alert-types)
|
||||
- [Methods](#methods)
|
||||
- [Executor](#executor)
|
||||
- [Licensing](#licensing)
|
||||
- [Documentation](#documentation)
|
||||
- [Tests](#tests)
|
||||
- [Action variables](#action-variables)
|
||||
- [Licensing](#licensing)
|
||||
- [Documentation](#documentation)
|
||||
- [Tests](#tests)
|
||||
- [Example](#example)
|
||||
- [Role Based Access-Control](#role-based-access-control)
|
||||
- [Alert Navigation](#alert-navigation)
|
||||
|
|
@ -147,9 +148,9 @@ This is the primary function for an alert type. Whenever the alert needs to exec
|
|||
|createdBy|The userid that created this alert.|
|
||||
|updatedBy|The userid that last updated this alert.|
|
||||
|
||||
### The `actionVariables` property
|
||||
### Action Variables
|
||||
|
||||
This property should contain the **flattened** names of the state and context variables available when an executor calls `alertInstance.scheduleActions(actionGroup, context)`. These names are meant to be used in prompters in the alerting user interface, are used as text values for display, and can be inserted into to an action parameter text entry field via UI gesture (eg, clicking a menu item from a menu built with these names). They should be flattened, so if a state or context variable is an object with properties, these should be listed with the "parent" property/properties in the name, separated by a `.` (period).
|
||||
The `actionVariables` property should contain the **flattened** names of the state and context variables available when an executor calls `alertInstance.scheduleActions(actionGroup, context)`. These names are meant to be used in prompters in the alerting user interface, are used as text values for display, and can be inserted into to an action parameter text entry field via UI gesture (eg, clicking a menu item from a menu built with these names). They should be flattened, so if a state or context variable is an object with properties, these should be listed with the "parent" property/properties in the name, separated by a `.` (period).
|
||||
|
||||
For example, if the `context` has one variable `foo` which is an object that has one property `bar`, and there are no `state` variables, the `actionVariables` value would be in the following shape:
|
||||
|
||||
|
|
@ -167,7 +168,12 @@ Currently most of the alerts are free features. But some alert types are subscri
|
|||
|
||||
## Documentation
|
||||
|
||||
You should create documentation for the new alert type. Make an entry in the alert type index [`docs/user/alerting/alert-types.asciidoc`](../../../docs/user/alerting/alert-types.asciidoc) that points to a new document for the alert type that should be in the proper application directory.
|
||||
You should create asciidoc for the new alert type.
|
||||
* For stack alerts, add an entry to the alert type index - [`docs/user/alerting/alert-types.asciidoc`](../../../docs/user/alerting/alert-types.asciidoc) which points to a new document for the alert type that should be in the directory [`docs/user/alerting/stack-alerts`](../../../docs/user/alerting/stack-alerts).
|
||||
|
||||
* Solution specific alert documentation should live within the docs for the solution.
|
||||
|
||||
We suggest following the template provided in `docs/alert-type-template.asciidoc`. The [Index Threshold alert type](https://www.elastic.co/guide/en/kibana/master/alert-type-index-threshold.html) is an example of documentation created following the template.
|
||||
|
||||
## Tests
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue