diff --git a/docs/action-type-template.asciidoc b/docs/action-type-template.asciidoc new file mode 100644 index 00000000000000..5b61c259563ad2 --- /dev/null +++ b/docs/action-type-template.asciidoc @@ -0,0 +1,73 @@ +[[-action-type]] +=== action +++++ + +++++ + +Include a short description of the action type. + +[float] +[[-connector-configuration]] +==== Connector configuration + + 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--configuration]] +==== Preconfigured action type + +//// +Example preconfigured format for this action type +//// + +[source,text] +-- + my-: + name: preconfigured--action-type + actionTypeId: . + config: + property1: value1 + property2: value2 + secrets: + property3: value3 +-- + +[float] +[[-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-configuration]] +==== Action configuration + + 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-]] +==== Configure +//// diff --git a/docs/alert-type-template.asciidoc b/docs/alert-type-template.asciidoc new file mode 100644 index 00000000000000..292ed00d05496f --- /dev/null +++ b/docs/alert-type-template.asciidoc @@ -0,0 +1,39 @@ +[[alert-type-]] +=== + +Include a short description of the alert type. + +[float] +==== Create the alert + +Fill in the <>, then select **. + +[float] +==== Define the conditions + +Define properties to detect the condition. + +//// +Optional, include a screenshot +[role="screenshot"] +image::user/alerting/images/alert-types--conditions.png[Conditions for alert type] +//// + +Condition1:: This is a condition the user must define. +Condition2:: This is another condition the user must define. + +[float] +==== Add action variables + +<> to run when the alert condition is met. The following variables are specific to the alert. You can also specify <>. + +`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} <> to setup and tune the conditions on an alert. For this example, we want to detect when . +//// \ No newline at end of file diff --git a/docs/user/alerting/action-types/email.asciidoc b/docs/user/alerting/action-types/email.asciidoc index 0c238da1b39e38..3813eccd048d9d 100644 --- a/docs/user/alerting/action-types/email.asciidoc +++ b/docs/user/alerting/action-types/email.asciidoc @@ -1,6 +1,9 @@ [role="xpack"] [[email-action-type]] === Email action +++++ +Email +++++ 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 <"` 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 <> 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 <>. 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 <>. 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 ` 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 ` 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. diff --git a/docs/user/alerting/action-types/index.asciidoc b/docs/user/alerting/action-types/index.asciidoc index 7ecc1cdb4f74e8..a57048243d7577 100644 --- a/docs/user/alerting/action-types/index.asciidoc +++ b/docs/user/alerting/action-types/index.asciidoc @@ -1,6 +1,9 @@ [role="xpack"] [[index-action-type]] === Index action +++++ +Index +++++ 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] diff --git a/docs/user/alerting/action-types/jira.asciidoc b/docs/user/alerting/action-types/jira.asciidoc index d37f565c1739ba..a1941b4b302834 100644 --- a/docs/user/alerting/action-types/jira.asciidoc +++ b/docs/user/alerting/action-types/jira.asciidoc @@ -1,6 +1,9 @@ [role="xpack"] [[jira-action-type]] === Jira action +++++ +Jira +++++ 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 <>. - -|=== +`email`:: A string that corresponds to *Email*. +`apiToken`:: A string that corresponds to *API Token*. Should be stored in the <>. +[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. diff --git a/docs/user/alerting/action-types/pagerduty.asciidoc b/docs/user/alerting/action-types/pagerduty.asciidoc index cadf8e0b16a44d..f74b5773b37197 100644 --- a/docs/user/alerting/action-types/pagerduty.asciidoc +++ b/docs/user/alerting/action-types/pagerduty.asciidoc @@ -1,49 +1,72 @@ [role="xpack"] [[pagerduty-action-type]] === PagerDuty action +++++ +PagerDuty +++++ 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. -* <> -* <> -* <> - [float] -[[pagerduty-benefits]] -==== PagerDuty + Elastic integration benefits +[[pagerduty-connector-configuration]] +==== Connector configuration -By integrating PagerDuty with alerts, you can: +PagerDuty connectors have the following configuration properties. -* Route your alerts to the right PagerDuty responder within your team, based on your structure, escalation policies, and workflows. -* 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. +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 <> 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] -[[pagerduty-how-it-works]] -===== How it works +[[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*. -{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. +Secrets defines sensitive information for the action type. + +`routingKey`:: A string that corresponds to *Integration Key*. [float] -===== Requirements +[[pagerduty-action-configuration]] +==== Action configuration -In the `kibana.yml` configuration file, you must add the <>. -This is required to encrypt parameters that must be secured, for example PagerDuty’s integration key. +PagerDuty actions have the following properties. -If you have security enabled: +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 `:`. 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`. -* 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 <>. -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]. +For more details on these properties, see https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2[PagerDuty v2 event parameters]. -Although not a requirement, to harden the integrations security you might want to -review the <> that are available to you. +[float] +[[pagerduty-benefits]] +==== Configure PagerDuty + +By integrating PagerDuty with alerts, you can: + +* Route your alerts to the right PagerDuty responder within your team, based on your structure, escalation policies, and workflows. +* 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-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 <> 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 <> 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 `:`. 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]. diff --git a/docs/user/alerting/action-types/resilient.asciidoc b/docs/user/alerting/action-types/resilient.asciidoc index feca42a542a2f2..296156875ceb69 100644 --- a/docs/user/alerting/action-types/resilient.asciidoc +++ b/docs/user/alerting/action-types/resilient.asciidoc @@ -1,6 +1,9 @@ [role="xpack"] [[resilient-action-type]] === IBM Resilient action +++++ +IBM Resilient +++++ 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 <>. - -|=== +`apiKeyId`:: A string that corresponds to *API key ID*. +`apiKeySecret`:: A string that corresponds to *API Key secret*. Should be stored in the <>. +[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. diff --git a/docs/user/alerting/action-types/server-log.asciidoc b/docs/user/alerting/action-types/server-log.asciidoc index 276f64e7786bd9..7849a70a239c36 100644 --- a/docs/user/alerting/action-types/server-log.asciidoc +++ b/docs/user/alerting/action-types/server-log.asciidoc @@ -1,6 +1,9 @@ [role="xpack"] [[server-log-action-type]] === Server log action +++++ +Server log +++++ 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`. diff --git a/docs/user/alerting/action-types/servicenow.asciidoc b/docs/user/alerting/action-types/servicenow.asciidoc index 4a11a2e28712a0..f002c39416f1ad 100644 --- a/docs/user/alerting/action-types/servicenow.asciidoc +++ b/docs/user/alerting/action-types/servicenow.asciidoc @@ -1,6 +1,9 @@ [role="xpack"] [[servicenow-action-type]] === ServiceNow action +++++ +ServiceNow +++++ 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 <>. - -|=== +`username`:: A string that corresponds to *Username*. +`password`:: A string that corresponds to *Password*. Should be stored in the <>. +[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. diff --git a/docs/user/alerting/action-types/slack.asciidoc b/docs/user/alerting/action-types/slack.asciidoc index 62589697533562..6f7d1b3e11d318 100644 --- a/docs/user/alerting/action-types/slack.asciidoc +++ b/docs/user/alerting/action-types/slack.asciidoc @@ -1,6 +1,9 @@ [role="xpack"] [[slack-action-type]] === Slack action +++++ +Slack +++++ 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 <> 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 diff --git a/docs/user/alerting/action-types/teams.asciidoc b/docs/user/alerting/action-types/teams.asciidoc index 7f4a29dc86fc52..294b5474e390a4 100644 --- a/docs/user/alerting/action-types/teams.asciidoc +++ b/docs/user/alerting/action-types/teams.asciidoc @@ -1,6 +1,9 @@ [role="xpack"] [[teams-action-type]] === Microsoft Teams action +++++ +Microsoft Teams +++++ 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 <> 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 diff --git a/docs/user/alerting/action-types/webhook.asciidoc b/docs/user/alerting/action-types/webhook.asciidoc index efe1077707ef09..381d6e72bf9c0c 100644 --- a/docs/user/alerting/action-types/webhook.asciidoc +++ b/docs/user/alerting/action-types/webhook.asciidoc @@ -1,6 +1,9 @@ [role="xpack"] [[webhook-action-type]] === Webhook action +++++ +Webhook +++++ 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 <> 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 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 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 <>. 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 <>. 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: + diff --git a/docs/user/alerting/alert-types.asciidoc b/docs/user/alerting/alert-types.asciidoc index 5afce8fa6cd93b..9eac084bd03c40 100644 --- a/docs/user/alerting/alert-types.asciidoc +++ b/docs/user/alerting/alert-types.asciidoc @@ -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 <> for more information. - {kib} provides two stack alerts: * <> * <> +Users require the `all` privilege to access the *Stack Alerts* feature and create and edit alerts. +See <> for more information. [float] ==== Domain-specific alerts diff --git a/docs/user/alerting/defining-alerts.asciidoc b/docs/user/alerting/defining-alerts.asciidoc index 8c8e25cea407a0..27f3a6c7309cb0 100644 --- a/docs/user/alerting/defining-alerts.asciidoc +++ b/docs/user/alerting/defining-alerts.asciidoc @@ -5,9 +5,9 @@ {kib} alerts can be created in a variety of apps including <>, <>, <>, <>, <> and from <> 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. . <> . <> @@ -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 <>. diff --git a/docs/user/alerting/images/slack-copy-webhook-url.png b/docs/user/alerting/images/slack-copy-webhook-url.png index 0acc9488e22a33..805f5719980dab 100644 Binary files a/docs/user/alerting/images/slack-copy-webhook-url.png and b/docs/user/alerting/images/slack-copy-webhook-url.png differ diff --git a/docs/user/alerting/stack-alerts/es-query.asciidoc b/docs/user/alerting/stack-alerts/es-query.asciidoc index 9f4a882328b9f7..d25b7267ed18ff 100644 --- a/docs/user/alerting/stack-alerts/es-query.asciidoc +++ b/docs/user/alerting/stack-alerts/es-query.asciidoc @@ -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 <>. Fill in the <>, 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 <>, 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 <>, 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: +<> to run when the alert condition is met. The following variables are specific to the ES query alert. You can also specify <>. `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] \ No newline at end of file diff --git a/docs/user/alerting/stack-alerts/index-threshold.asciidoc b/docs/user/alerting/stack-alerts/index-threshold.asciidoc index 6b45f69401c4aa..89ca8e3087f12a 100644 --- a/docs/user/alerting/stack-alerts/index-threshold.asciidoc +++ b/docs/user/alerting/stack-alerts/index-threshold.asciidoc @@ -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 <>. Fill in the <>, 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 <>, 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: +<> to run when the alert condition is met. The following variables are specific to the index threshold alert. You can also specify <>. `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} <> 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} <> 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 <>, create a new alert, and fill in the <>. 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] \ No newline at end of file diff --git a/x-pack/plugins/actions/README.md b/x-pack/plugins/actions/README.md index f1be1ec12b79c5..3ec8545017ca11 100644 --- a/x-pack/plugins/actions/README.md +++ b/x-pack/plugins/actions/README.md @@ -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 diff --git a/x-pack/plugins/alerts/README.md b/x-pack/plugins/alerts/README.md index 07bad42a3bfa3d..057d86e4c0f31c 100644 --- a/x-pack/plugins/alerts/README.md +++ b/x-pack/plugins/alerts/README.md @@ -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