From f6a930f946409e5291f25ebe3ab0d991d7f50fe7 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Wed, 10 Feb 2021 16:11:13 -0800 Subject: [PATCH 01/61] Added API documentation for alerts plugin --- docs/api/alerts.asciidoc | 45 ++++++++ docs/api/alerts/create.asciidoc | 161 ++++++++++++++++++++++++++++ docs/api/alerts/delete.asciidoc | 36 +++++++ docs/api/alerts/disable.asciidoc | 34 ++++++ docs/api/alerts/enable.asciidoc | 34 ++++++ docs/api/alerts/find.asciidoc | 120 +++++++++++++++++++++ docs/api/alerts/get.asciidoc | 70 ++++++++++++ docs/api/alerts/health.asciidoc | 85 +++++++++++++++ docs/api/alerts/list.asciidoc | 127 ++++++++++++++++++++++ docs/api/alerts/mute.asciidoc | 37 +++++++ docs/api/alerts/mute_all.asciidoc | 34 ++++++ docs/api/alerts/unmute.asciidoc | 37 +++++++ docs/api/alerts/unmute_all.asciidoc | 34 ++++++ docs/api/alerts/update.asciidoc | 108 +++++++++++++++++++ 14 files changed, 962 insertions(+) create mode 100644 docs/api/alerts.asciidoc create mode 100644 docs/api/alerts/create.asciidoc create mode 100644 docs/api/alerts/delete.asciidoc create mode 100644 docs/api/alerts/disable.asciidoc create mode 100644 docs/api/alerts/enable.asciidoc create mode 100644 docs/api/alerts/find.asciidoc create mode 100644 docs/api/alerts/get.asciidoc create mode 100644 docs/api/alerts/health.asciidoc create mode 100644 docs/api/alerts/list.asciidoc create mode 100644 docs/api/alerts/mute.asciidoc create mode 100644 docs/api/alerts/mute_all.asciidoc create mode 100644 docs/api/alerts/unmute.asciidoc create mode 100644 docs/api/alerts/unmute_all.asciidoc create mode 100644 docs/api/alerts/update.asciidoc diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc new file mode 100644 index 0000000000000..fbc572071e0dd --- /dev/null +++ b/docs/api/alerts.asciidoc @@ -0,0 +1,45 @@ +[[alerts-api]] +== Alerts APIs + +Manage {kib} alerts. +The following alerts APIs are available: + +* <> to create {kib} alert + +* <> to update the attributes for existing {kib} alerts + +* <> to retrieve a single {kib} alert by ID + +* <> to remove {kib} alert + +* <> to retrieve a paginated set of {kib} alerts by various conditions + +* <> to retrieve a list of all {kib} alert types + +* <> to enable a single {kib} alert by ID + +* <> to disable a single {kib} alert by ID + +* <> to mute all alert instances for a single {kib} alert by ID + +* <> to mute alert instance for a single {kib} alert by ID + +* <> to unmute all alert instances for a single {kib} alert by ID + +* <> to unmute alert instance for a single {kib} alert by ID + +* <> to retrieve a {kib} alerts framework health + +include::alerts/get.asciidoc[] +include::alerts/list.asciidoc[] +include::alerts/find.asciidoc[] +include::alerts/create.asciidoc[] +include::alerts/enable.asciidoc[] +include::alerts/update.asciidoc[] +include::alerts/delete.asciidoc[] +include::alerts/disable.asciidoc[] +include::alerts/mute.asciidoc[] +include::alerts/unmute.asciidoc[] +include::alerts/mute_all.asciidoc[] +include::alerts/unmute_all.asciidoc[] +include::alerts/health.asciidoc[] diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc new file mode 100644 index 0000000000000..7cb22388460da --- /dev/null +++ b/docs/api/alerts/create.asciidoc @@ -0,0 +1,161 @@ +[[alerts-api-create]] +=== Create alert API +++++ +Create alert +++++ + +Create {kib} alerts. + +[[alerts-api-create-request]] +==== Request + +`POST :/api/alerts/alert` + +[[alerts-api-create-request-body]] +==== Request body + +`name`:: + (Required, string) A name to reference and search in the future. + +`tags`:: + (Optional, string array) A list of keywords to reference and search in the future. + +`alertTypeId`:: + (Required, string) The id value of the alert type you want to call when the alert is scheduled to execute. + +`schedule`:: + (Required, object) The schedule specifying when this alert should be run, using one of the available schedule formats specified under _Schedule Formats_ below. + +`throttle`:: + (Optional, string) A Duration specifying how often this alert should fire the same actions. This will prevent the alert from sending out the same notification over and over. For example, if an alert with a `schedule` of 1 minute stays in a triggered state for 90 minutes, setting a `throttle` of `10m` or `1h` will prevent it from sending 90 notifications over this period. + +`notifyWhen`:: + (Required, string) Defines the conditions for notifications thottling from the three available option types 'onActionGroupChange', 'onActiveAlert', 'onThrottleInterval'. + +`enabled`:: + (Optional, boolean) Indicate if you want the alert to start executing on an interval basis after it has been created. + +`consumer`:: + (Required, string) A name of the application which owns the alert. + +`params`:: + (Required, object) The parameters to pass in to the alert type executor `params` value. This will also validate against the alert type params validator if defined. + +`actions`:: + (Optional, object array) Array of the following:
- `group` (string): We support grouping actions in the scenario of escalations or different types of alert instances. If you don't need this, feel free to use `default` as a value.
- `id` (string): The id of the action saved object to execute.
- `params` (object): The map to the `params` the action type will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. (see templating actions). + +[[alerts-api-create-request-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +[[alerts-api-create-example]] +==== Example + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/alerts/alert -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d ' +{ + "params":{ + "aggType":"avg", + "termSize":6, + "thresholdComparator":">", + "timeWindowSize":5, + "timeWindowUnit":"m", + "groupBy":"top", + "threshold":[ + 1000 + ], + "index":[ + ".test-index" + ], + "timeField":"@timestamp", + "aggField":"sheet.version", + "termField":"name.keyword" + }, + "consumer":"alerts", + "alertTypeId":".index-threshold", + "schedule":{ + "interval":"1m" + }, + "actions":[ + { + "id":"dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2", + "actionTypeId":".server-log", + "group":"threshold met", + "params":{ + "level":"info", + "message":"alert '{{alertName}}' is active for group '{{context.group}}':\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{params.timeWindowSize}}{{params.timeWindowUnit}}\n- Timestamp: {{context.date}}" + } + } + ], + "tags":[ + "cpu" + ], + "notifyWhen":"onActionGroupChange", + "name":"my alert" +}' +-------------------------------------------------- +// KIBANA + +The API returns the following: + +[source,sh] +-------------------------------------------------- +{ + "id": "41893910-6bca-11eb-9e0d-85d233e3ee35", + "notifyWhen": "onActionGroupChange", + "params": { + "aggType": "avg", + "termSize": 6, + "thresholdComparator": ">", + "timeWindowSize": 5, + "timeWindowUnit": "m", + "groupBy": "top", + "threshold": [ + 1000 + ], + "index": [ + ".kibana" + ], + "timeField": "@timestamp", + "aggField": "sheet.version", + "termField": "name.keyword" + }, + "consumer": "alerts", + "alertTypeId": ".index-threshold", + "schedule": { + "interval": "1m" + }, + "actions": [ + { + "actionTypeId": ".server-log", + "group": "threshold met", + "params": { + "level": "info", + "message": "alert {{alertName}} is active for group {{context.group}}:\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{params.timeWindowSize}}{{params.timeWindowUnit}}\n- Timestamp: {{context.date}}" + }, + "id": "dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2" + } + ], + "tags": [ + "cpu" + ], + "name": "my alert", + "enabled": true, + "throttle": null, + "apiKeyOwner": "elastic", + "createdBy": "elastic", + "updatedBy": "elastic", + "muteAll": false, + "mutedInstanceIds": [], + "updatedAt": "2021-02-10T18:03:19.961Z", + "createdAt": "2021-02-10T18:03:19.961Z", + "scheduledTaskId": "425b0800-6bca-11eb-9e0d-85d233e3ee35", + "executionStatus": { + "lastExecutionDate": "2021-02-10T18:03:19.966Z", + "status": "pending" + } +} +-------------------------------------------------- diff --git a/docs/api/alerts/delete.asciidoc b/docs/api/alerts/delete.asciidoc new file mode 100644 index 0000000000000..5d86c0d9b13d2 --- /dev/null +++ b/docs/api/alerts/delete.asciidoc @@ -0,0 +1,36 @@ +[[alerts-api-delete]] +=== Delete alert API +++++ +Delete alert +++++ + +Remove {kib} alerts. + +WARNING: Once you delete an alert, _it cannot be recovered_. + +[[alerts-api-delete-request]] +==== Request + +`DELETE :/api/alerts/alert/` + +[[alerts-api-delete-path-params]] +==== Path parameters + +`id`:: + (Required, string) The alert ID that you want to remove. + +[[alerts-api-delete-response-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +==== Example + +Delete an alert with ID: + +[source,sh] +-------------------------------------------------- +$ curl -X DELETE api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35 +-------------------------------------------------- +// KIBANA diff --git a/docs/api/alerts/disable.asciidoc b/docs/api/alerts/disable.asciidoc new file mode 100644 index 0000000000000..fd5d6f47249ba --- /dev/null +++ b/docs/api/alerts/disable.asciidoc @@ -0,0 +1,34 @@ +[[alerts-api-disable]] +=== Disable alert API +++++ +Disable alert +++++ + +Disable {kib} alerts. + +[[alerts-api-disable-request]] +==== Request + +`POST :/api/alerts/alert//_disable` + +[[alerts-api-disable-path-params]] +==== Path parameters + +`id`:: + (Required, string) The alert ID that you want to disable. + +[[alerts-api-disable-response-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +==== Example + +Disable an alert with ID: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35/_disable +-------------------------------------------------- +// KIBANA diff --git a/docs/api/alerts/enable.asciidoc b/docs/api/alerts/enable.asciidoc new file mode 100644 index 0000000000000..961da23e1c382 --- /dev/null +++ b/docs/api/alerts/enable.asciidoc @@ -0,0 +1,34 @@ +[[alerts-api-enable]] +=== Enable alert API +++++ +Enable alert +++++ + +Enable {kib} alerts. + +[[alerts-api-enable-request]] +==== Request + +`POST :/api/alerts/alert//_enable` + +[[alerts-api-enable-path-params]] +==== Path parameters + +`id`:: + (Required, string) The alert ID that you want to enable. + +[[alerts-api-enable-response-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +==== Example + +Enable an alert with ID: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35/_enable +-------------------------------------------------- +// KIBANA diff --git a/docs/api/alerts/find.asciidoc b/docs/api/alerts/find.asciidoc new file mode 100644 index 0000000000000..5467bf9fec85d --- /dev/null +++ b/docs/api/alerts/find.asciidoc @@ -0,0 +1,120 @@ +[[alerts-api-find]] +=== Find alerts API +++++ +Find alerts +++++ + +Retrieve a paginated set of {kib} alerts by various conditions. + +[[alerts-api-find-request]] +==== Request + +`GET :/api/alerts/_find` + +[[saved-objects-api-find-query-params]] +==== Query Parameters + +`per_page`:: + (Optional, number) The number of objects to return per page. + +`page`:: + (Optional, number) The page of objects to return. + +`search`:: + (Optional, string) An Elasticsearch {ref}/query-dsl-simple-query-string-query.html[simple_query_string] query that filters the alerts in the response. + +`default_search_operator`:: + (Optional, string) The default operator to use for the `simple_query_string`. By default is 'OR'. + +`search_fields`:: + (Optional, array|string) The fields to perform the `simple_query_string` parsed query against. + +`fields`:: + (Optional, array|string) The fields to return in the `attributes` key of the response. + +`sort_field`:: + (Optional, string) Sorts the response. Includes "root" and "type" fields. "root" fields exist for all saved objects, such as "updated_at". + "type" fields are specific to an object type, such as fields returned in the `attributes` key of the response. When a single type is + defined in the `type` parameter, the "root" and "type" fields are allowed, and validity checks are made in that order. When multiple types + are defined in the `type` parameter, only "root" fields are allowed. + +`sort_order`:: + (Optional, string) Sort directions. Could be two values 'asc' or 'desc'. + +`has_reference`:: + (Optional, object) Filters to objects that have a relationship with the type and ID combination. + +`filter`:: + (Optional, string) The filter is a KQL string with the caveat that if you filter with an attribute from your type saved object. + It should look like that savedObjectType.attributes.title: "myTitle". However, If you used a direct attribute of a saved object like `updatedAt`, + you will have to define your filter like that savedObjectType.updatedAt > 2018-12-22. + +NOTE: As alerts change in {kib}, the results on each page of the response also +change. Use the find API for traditional paginated results, but avoid using it to export large amounts of data. + +[[alerts-api-find-request-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +==== Examples + +Find alerts with names that start with `my`: + +[source,sh] +-------------------------------------------------- +$ curl -X GET api/alerts/_find?search_fields=name&search=my* +-------------------------------------------------- +// KIBANA + +The API returns the following: + +[source,sh] +-------------------------------------------------- +{ + "page": 1, + "perPage": 10, + "total": 1, + "data": [ + { + "id": "0a037d60-6b62-11eb-9e0d-85d233e3ee35", + "notifyWhen": "onActionGroupChange", + "params": { + "aggType": "avg", + }, + "consumer": "alerts", + "alertTypeId": "test.alert.type", + "schedule": { + "interval": "1m" + }, + "actions": [], + "tags": [], + "name": "test alert", + "enabled": true, + "throttle": null, + "apiKeyOwner": "elastic", + "createdBy": "elastic", + "updatedBy": "elastic", + "muteAll": false, + "mutedInstanceIds": [], + "updatedAt": "2021-02-10T05:37:19.086Z", + "createdAt": "2021-02-10T05:37:19.086Z", + "scheduledTaskId": "0b092d90-6b62-11eb-9e0d-85d233e3ee35", + "executionStatus": { + "lastExecutionDate": "2021-02-10T17:55:14.262Z", + "status": "ok" + } + }, + ] +} +-------------------------------------------------- + +For parameters that accept multiple values (e.g. `fields`), repeat the +query parameter for each value: + +[source,sh] +-------------------------------------------------- +$ curl -X GET api/alerts/_find?fields=id&fields=name +-------------------------------------------------- +// KIBANA diff --git a/docs/api/alerts/get.asciidoc b/docs/api/alerts/get.asciidoc new file mode 100644 index 0000000000000..799e5d03586f8 --- /dev/null +++ b/docs/api/alerts/get.asciidoc @@ -0,0 +1,70 @@ +[[alerts-api-get]] +=== Get alert API +++++ +Get alert +++++ + +Retrieve a single {kib} alert by ID. + +[[alerts-api-get-request]] +==== Request + +`GET :/api/alerts/alert/` + +[[alerts-api-get-params]] +==== Path parameters + +`id`:: + (Required, string) The ID of the alert to retrieve. + +[[alerts-api-get-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +[[alerts-api-get-example]] +==== Example + +Retrieve the alert object with the `41893910-6bca-11eb-9e0d-85d233e3ee35` ID: + +[source,sh] +-------------------------------------------------- +$ curl -X GET api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35 +-------------------------------------------------- +// KIBANA + +The API returns the following: + +[source,sh] +-------------------------------------------------- +{ + "id": "0a037d60-6b62-11eb-9e0d-85d233e3ee35", + "notifyWhen": "onActionGroupChange", + "params": { + "aggType": "avg", + }, + "consumer": "alerts", + "alertTypeId": "test.alert.type", + "schedule": { + "interval": "1m" + }, + "actions": [], + "tags": [], + "name": "test alert", + "enabled": true, + "throttle": null, + "apiKeyOwner": "elastic", + "createdBy": "elastic", + "updatedBy": "elastic", + "muteAll": false, + "mutedInstanceIds": [], + "updatedAt": "2021-02-10T05:37:19.086Z", + "createdAt": "2021-02-10T05:37:19.086Z", + "scheduledTaskId": "0b092d90-6b62-11eb-9e0d-85d233e3ee35", + "executionStatus": { + "lastExecutionDate": "2021-02-10T17:55:14.262Z", + "status": "ok" + } +} +-------------------------------------------------- diff --git a/docs/api/alerts/health.asciidoc b/docs/api/alerts/health.asciidoc new file mode 100644 index 0000000000000..1d911589b513d --- /dev/null +++ b/docs/api/alerts/health.asciidoc @@ -0,0 +1,85 @@ +[[alerts-api-health]] +=== Get alert framework health API +++++ +Get alert framework health +++++ + +Retrieve the alert framework health status. + +[[alerts-api-get-request]] +==== Request + +`GET :/api/alerts/_health` + +[[alerts-api-get-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +[[alerts-api-health-example]] +==== Example + +Retrieve the alert framework health status: + +[source,sh] +-------------------------------------------------- +$ curl -X GET api/alerts/_health +-------------------------------------------------- +// KIBANA + +The API returns the following: + +[source,sh] +-------------------------------------------------- +{ + "isSufficientlySecure":true, + "hasPermanentEncryptionKey":true, + "alertingFrameworkHeath":{ + "decryptionHealth":{ + "status":"ok", + "timestamp":"2021-02-10T23:35:04.949Z" + }, + "executionHealth":{ + "status":"ok", + "timestamp":"2021-02-10T23:35:04.949Z" + }, + "readHealth":{ + "status":"ok", + "timestamp":"2021-02-10T23:35:04.949Z" + } + } +} +-------------------------------------------------- + +Health API response contains the following properties: + +[cols="2*<"] +|=== + +| `isSufficientlySecure` +| Return the state false if the security is enabled but TLS is not. + +| `hasPermanentEncryptionKey` +| Return the state true if Encryption Saved Object plugin has a permanent encryption Key + +| `alertingFrameworkHeath` +| This state property includes three different substates: `decryptionHealth`, `executionHealth`, `readHealth` which identify the alerting framework API health. + +|=== + +alertingFrameworkHeath itself consists from the next properties: + +[cols="2*<"] +|=== + +| `decryptionHealth` +| Return the latest status `ok`, `warn` or `error` with the timestamp, which identify if the alerts have the decryption errors. + +| `executionHealth` +| Return the latest status `ok`, `warn` or `error` with the timestamp, which identify if the alerts executions have results with the errors. + +| `readHealth` +| Return the latest status `ok`, `warn` or `error` with the timestamp, which identify if the alerts read events have any errors. + +|=== diff --git a/docs/api/alerts/list.asciidoc b/docs/api/alerts/list.asciidoc new file mode 100644 index 0000000000000..a479f5420cfc9 --- /dev/null +++ b/docs/api/alerts/list.asciidoc @@ -0,0 +1,127 @@ +[[alerts-api-list]] +=== List alert types API +++++ +List all alert types API +++++ + +Retrieve a list of all {kib} alert types. + +[[alerts-api-list-request]] +==== Request + +`GET :/api/alerts/list_alert_types` + +[[alerts-api-list-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +[[alerts-api-list-example]] +==== Example + +[source,sh] +-------------------------------------------------- +$ curl -X GET api/alerts/list_alert_types +-------------------------------------------------- +// KIBANA + +The API returns the following: + +[source,sh] +-------------------------------------------------- +[ + { + "id":".index-threshold", + "name":"Index threshold", + "actionGroups":[ + { + "id":"threshold met", + "name":"Threshold met" + }, + { + "id":"recovered", + "name":"Recovered" + } + ], + "recoveryActionGroup":{ + "id":"recovered", + "name":"Recovered" + }, + "defaultActionGroupId":"threshold met", + "actionVariables":{ + "context":[ + { + "name":"message", + "description":"A pre-constructed message for the alert." + }, + ], + "state":[], + "params":[ + { + "name":"threshold", + "description":"An array of values to use as the threshold; 'between' and 'notBetween' require two values, the others require one." + }, + { + "name":"index", + "description":"index" + }, + ] + }, + "producer":"stackAlerts", + "minimumLicenseRequired":"basic", + "enabledInLicense":true, + "authorizedConsumers":{ + "alerts":{ + "read":true, + "all":true + }, + "stackAlerts":{ + "read":true, + "all":true + }, + "uptime":{ + "read":true, + "all":true + } + } + } +] +-------------------------------------------------- + +Each alert type object contains the following properties: + +[cols="2*<"] +|=== + +| `name` +| The descriptive name of the alert type. + +| `id` +| The unique ID of the alert type. + +| `minimumLicenseRequired` +| The license required to use the alert type. + +| `enabledInLicense` +| Whether the alert type is enabled or disabled due to license. + +| `actionGroups` +| An explicit list of groups the alert type may schedule actions for, each specifying the ActionGroup's unique ID and human readable name. Alert `actions` validation will use this configuartion to ensure groups are valid. We highly encourage using `kbn-i18n` to translate the names of actionGroup when registering the AlertType. + +| `recoveryActionGroup` +| An action group to use when an alert instance goes from an active state, to an inactive one. This action group should not be specified under the `actionGroups` property. If no recoveryActionGroup is specified, the default `recovered` action group will be used. + +| `defaultActionGroupId` +| Default ID value for the group of the alert type. + +| `actionVariables` +| An explicit list of action variables the alert type makes available via context and state in action parameter templates, and a short human readable description. Alert UI will use this to display prompts for the users for these variables, in action parameter editors. We highly encourage using `kbn-i18n` to translate the descriptions. + +| `producer` +| The id of the application producing this alert type. + +| `authorizedConsumers` +| The list of the plugins ids which has access for the alert type. + +|=== diff --git a/docs/api/alerts/mute.asciidoc b/docs/api/alerts/mute.asciidoc new file mode 100644 index 0000000000000..90b1d74d62a60 --- /dev/null +++ b/docs/api/alerts/mute.asciidoc @@ -0,0 +1,37 @@ +[[alerts-api-mute]] +=== Mute alert instance API +++++ +Mute alert instance +++++ + +Mute {kib} alert instance. + +[[alerts-api-mute-request]] +==== Request + +`POST :/api/alerts/alert//alert_instance//_mute` + +[[alerts-api-mute-path-params]] +==== Path parameters + +`id`:: + (Required, string) The alert ID that you want to mute a single instance. + +`alert_instance_id`:: + (Required, string) The alert instance ID that you want to mute. + +[[alerts-api-mute-response-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +==== Example + +Mute alert instance with ID: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35/alert_instance/dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2/_mute +-------------------------------------------------- +// KIBANA diff --git a/docs/api/alerts/mute_all.asciidoc b/docs/api/alerts/mute_all.asciidoc new file mode 100644 index 0000000000000..f7a7e0755c745 --- /dev/null +++ b/docs/api/alerts/mute_all.asciidoc @@ -0,0 +1,34 @@ +[[alerts-api-mute-all]] +=== Mute all alert instances API +++++ +Mute all alert instances +++++ + +Mute all {kib} alert instances. + +[[alerts-api-mute-all-request]] +==== Request + +`POST :/api/alerts/alert//_mute_all` + +[[alerts-api-mute-all-path-params]] +==== Path parameters + +`id`:: + (Required, string) The alert ID that you want to mute all instances. + +[[alerts-api-mute-all-response-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +==== Example + +Mute all alert instances with ID: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35/_mute_all +-------------------------------------------------- +// KIBANA diff --git a/docs/api/alerts/unmute.asciidoc b/docs/api/alerts/unmute.asciidoc new file mode 100644 index 0000000000000..f118ad434aa44 --- /dev/null +++ b/docs/api/alerts/unmute.asciidoc @@ -0,0 +1,37 @@ +[[alerts-api-unmute]] +=== Unmute alert instance API +++++ +Unmute alert instance +++++ + +Unmute {kib} alert instance. + +[[alerts-api-unmute-request]] +==== Request + +`POST :/api/alerts/alert//alert_instance//_unmute` + +[[alerts-api-unmute-path-params]] +==== Path parameters + +`id`:: + (Required, string) The alert ID that you want to unmute a single instance. + +`alert_instance_id`:: + (Required, string) The alert instance ID that you want to unmute. + +[[alerts-api-unmute-response-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +==== Example + +Unmute alert instance with ID: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35/alert_instance/dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2/_unmute +-------------------------------------------------- +// KIBANA diff --git a/docs/api/alerts/unmute_all.asciidoc b/docs/api/alerts/unmute_all.asciidoc new file mode 100644 index 0000000000000..ade5618606e71 --- /dev/null +++ b/docs/api/alerts/unmute_all.asciidoc @@ -0,0 +1,34 @@ +[[alerts-api-unmute-all]] +=== Unmute all alert instances API +++++ +Unmute all alert instances +++++ + +Unmute all {kib} alert instances. + +[[alerts-api-unmute-all-request]] +==== Request + +`POST :/api/alerts/alert//_unmute_all` + +[[alerts-api-unmute-all-path-params]] +==== Path parameters + +`id`:: + (Required, string) The alert ID that you want to unmute all instances. + +[[alerts-api-unmute-all-response-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +==== Example + +Unmute all alert instances with ID: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35/_unmute_all +-------------------------------------------------- +// KIBANA diff --git a/docs/api/alerts/update.asciidoc b/docs/api/alerts/update.asciidoc new file mode 100644 index 0000000000000..021de89d71e20 --- /dev/null +++ b/docs/api/alerts/update.asciidoc @@ -0,0 +1,108 @@ +[[alerts-api-update]] +=== Update alert API +++++ +Update alert +++++ + +Update the attributes for existing {kib} alerts. + +[[alerts-api-update-request]] +==== Request + +`PUT :/api/alerts/alert/` + +[[alerts-api-update-path-params]] +==== Path parameters + +`id`:: + (Required, string) The alert ID to update. + +[[alerts-api-update-request-body]] +==== Request body + +`name`:: + (Required, string) A name to reference and search in the future. + +`tags`:: + (Optional, string array) A list of keywords to reference and search in the future. + +`schedule`:: + (Required, object) The schedule specifying when this alert should be run, using one of the available schedule formats specified under _Schedule Formats_ below. + +`throttle`:: + (Optional, string) A Duration specifying how often this alert should fire the same actions. This will prevent the alert from sending out the same notification over and over. For example, if an alert with a `schedule` of 1 minute stays in a triggered state for 90 minutes, setting a `throttle` of `10m` or `1h` will prevent it from sending 90 notifications over this period. + +`notifyWhen`:: + (Required, string) Defines the conditions for notifications thottling from the three available option types 'onActionGroupChange', 'onActiveAlert', 'onThrottleInterval'. + +`params`:: + (Required, object) The parameters to pass in to the alert type executor `params` value. This will also validate against the alert type params validator if defined. + +`actions`:: + (Optional, object array) Array of the following:
- `group` (string): We support grouping actions in the scenario of escalations or different types of alert instances. If you don't need this, feel free to use `default` as a value.
- `id` (string): The id of the action saved object to execute.
- `params` (object): The map to the `params` the action type will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. (see templating actions). + +[[alerts-api-update-errors-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +[[alerts-api-update-example]] +==== Example + +Update an existing alert with ID `ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74`, with a different name: + +[source,sh] +-------------------------------------------------- +$ curl -X PUT api/alerts/alert/ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74 + +{ + "notifyWhen": "onActionGroupChange", + "params": { + "aggType": "avg", + }, + "schedule": { + "interval": "1m" + }, + "actions": [], + "tags": [], + "name": "new name", + "throttle": null, +} +-------------------------------------------------- +// KIBANA + +The API returns the following: + +[source,sh] +-------------------------------------------------- +{ + "id": "ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74", + "notifyWhen": "onActionGroupChange", + "params": { + "aggType": "avg", + }, + "consumer": "alerts", + "alertTypeId": "test.alert.type", + "schedule": { + "interval": "1m" + }, + "actions": [], + "tags": [], + "name": "new name", + "enabled": true, + "throttle": null, + "apiKeyOwner": "elastic", + "createdBy": "elastic", + "updatedBy": "elastic", + "muteAll": false, + "mutedInstanceIds": [], + "updatedAt": "2021-02-10T05:37:19.086Z", + "createdAt": "2021-02-10T05:37:19.086Z", + "scheduledTaskId": "0b092d90-6b62-11eb-9e0d-85d233e3ee35", + "executionStatus": { + "lastExecutionDate": "2021-02-10T17:55:14.262Z", + "status": "ok" + } +} +-------------------------------------------------- From d448d6fb5372d275e0b4ced7c8ea7c0ed122f7fb Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Wed, 10 Feb 2021 16:29:08 -0800 Subject: [PATCH 02/61] Added link to user api --- docs/user/api.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/user/api.asciidoc b/docs/user/api.asciidoc index 20f1fc89367f2..bcb8e62586fce 100644 --- a/docs/user/api.asciidoc +++ b/docs/user/api.asciidoc @@ -36,6 +36,7 @@ include::{kib-repo-dir}/api/features.asciidoc[] include::{kib-repo-dir}/api/spaces-management.asciidoc[] include::{kib-repo-dir}/api/role-management.asciidoc[] include::{kib-repo-dir}/api/saved-objects.asciidoc[] +include::{kib-repo-dir}/api/alerts.asciidoc[] include::{kib-repo-dir}/api/dashboard-api.asciidoc[] include::{kib-repo-dir}/api/logstash-configuration-management.asciidoc[] include::{kib-repo-dir}/api/url-shortening.asciidoc[] From 4207b22159606cdce3cf02bace0dff229ff10fe0 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Wed, 10 Feb 2021 17:19:44 -0800 Subject: [PATCH 03/61] fixed links --- docs/api/alerts/find.asciidoc | 2 +- docs/api/alerts/health.asciidoc | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api/alerts/find.asciidoc b/docs/api/alerts/find.asciidoc index 5467bf9fec85d..9f24290999986 100644 --- a/docs/api/alerts/find.asciidoc +++ b/docs/api/alerts/find.asciidoc @@ -11,7 +11,7 @@ Retrieve a paginated set of {kib} alerts by various conditions. `GET :/api/alerts/_find` -[[saved-objects-api-find-query-params]] +[[alerts-api-find-query-params]] ==== Query Parameters `per_page`:: diff --git a/docs/api/alerts/health.asciidoc b/docs/api/alerts/health.asciidoc index 1d911589b513d..d8fb1d6abf3f8 100644 --- a/docs/api/alerts/health.asciidoc +++ b/docs/api/alerts/health.asciidoc @@ -6,12 +6,12 @@ Retrieve the alert framework health status. -[[alerts-api-get-request]] +[[alerts-api-health-request]] ==== Request `GET :/api/alerts/_health` -[[alerts-api-get-codes]] +[[alerts-api-health-codes]] ==== Response code `200`:: From 2a151eaf0cd1ddad4e9f269da25711e1f3f28211 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:53:12 -0800 Subject: [PATCH 04/61] Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc index fbc572071e0dd..8eb8d4af99bc8 100644 --- a/docs/api/alerts.asciidoc +++ b/docs/api/alerts.asciidoc @@ -4,7 +4,7 @@ Manage {kib} alerts. The following alerts APIs are available: -* <> to create {kib} alert +* <> to create an alert * <> to update the attributes for existing {kib} alerts From aa5bc091859c70a5d61ad95baac45442bfb8c3b3 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:53:27 -0800 Subject: [PATCH 05/61] Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc index 8eb8d4af99bc8..69f997da2a80b 100644 --- a/docs/api/alerts.asciidoc +++ b/docs/api/alerts.asciidoc @@ -10,7 +10,7 @@ The following alerts APIs are available: * <> to retrieve a single {kib} alert by ID -* <> to remove {kib} alert +* <> to permanently remove an alert * <> to retrieve a paginated set of {kib} alerts by various conditions From 6008f3c13ed1e4adf8800c7e684eaa745b3171ec Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:53:39 -0800 Subject: [PATCH 06/61] Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc index 69f997da2a80b..19a94cf45e67b 100644 --- a/docs/api/alerts.asciidoc +++ b/docs/api/alerts.asciidoc @@ -12,7 +12,7 @@ The following alerts APIs are available: * <> to permanently remove an alert -* <> to retrieve a paginated set of {kib} alerts by various conditions +* <> to retrieve a paginated set of alerts by condition * <> to retrieve a list of all {kib} alert types From 7fbb6774521aa5752e2c4606244017e6c5fda753 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:53:46 -0800 Subject: [PATCH 07/61] Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc index 19a94cf45e67b..84da4dfd59abc 100644 --- a/docs/api/alerts.asciidoc +++ b/docs/api/alerts.asciidoc @@ -6,7 +6,7 @@ The following alerts APIs are available: * <> to create an alert -* <> to update the attributes for existing {kib} alerts +* <> to update the attributes for existing alerts * <> to retrieve a single {kib} alert by ID From b6beab27f5f375f4e421543e6ffdf6efa649f209 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:53:57 -0800 Subject: [PATCH 08/61] Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc index 84da4dfd59abc..b5e8537480b65 100644 --- a/docs/api/alerts.asciidoc +++ b/docs/api/alerts.asciidoc @@ -8,7 +8,7 @@ The following alerts APIs are available: * <> to update the attributes for existing alerts -* <> to retrieve a single {kib} alert by ID +* <> to retrieve a single alert by ID * <> to permanently remove an alert From 144711f1e8430fb9c908559f5d6e294302933a90 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:54:12 -0800 Subject: [PATCH 09/61] Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc index b5e8537480b65..5d6582e58a01d 100644 --- a/docs/api/alerts.asciidoc +++ b/docs/api/alerts.asciidoc @@ -14,7 +14,7 @@ The following alerts APIs are available: * <> to retrieve a paginated set of alerts by condition -* <> to retrieve a list of all {kib} alert types +* <> to retrieve a list of all alert types * <> to enable a single {kib} alert by ID From fc74e9a8eb64f519c5a5eed5f96acc9a53a81311 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:54:23 -0800 Subject: [PATCH 10/61] Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc index 5d6582e58a01d..c0ac8d8a066c5 100644 --- a/docs/api/alerts.asciidoc +++ b/docs/api/alerts.asciidoc @@ -16,7 +16,7 @@ The following alerts APIs are available: * <> to retrieve a list of all alert types -* <> to enable a single {kib} alert by ID +* <> to enable a single alert by ID * <> to disable a single {kib} alert by ID From 230c277d20ba4c4e78e7fcac09b319864ff4a774 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:54:35 -0800 Subject: [PATCH 11/61] Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc index c0ac8d8a066c5..adcbb369ccd6d 100644 --- a/docs/api/alerts.asciidoc +++ b/docs/api/alerts.asciidoc @@ -18,7 +18,7 @@ The following alerts APIs are available: * <> to enable a single alert by ID -* <> to disable a single {kib} alert by ID +* <> to disable a single alert by ID * <> to mute all alert instances for a single {kib} alert by ID From 3cf383e454b9df4b529c010e7a06153e3f181552 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:54:47 -0800 Subject: [PATCH 12/61] Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc index adcbb369ccd6d..ccbeab7d4a3e3 100644 --- a/docs/api/alerts.asciidoc +++ b/docs/api/alerts.asciidoc @@ -20,7 +20,7 @@ The following alerts APIs are available: * <> to disable a single alert by ID -* <> to mute all alert instances for a single {kib} alert by ID +* <> to mute all alert instances for a single alert by ID * <> to mute alert instance for a single {kib} alert by ID From 9f00273b8c71592073efae5b70776732091c52d2 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:54:59 -0800 Subject: [PATCH 13/61] Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc index ccbeab7d4a3e3..7030725cba0e2 100644 --- a/docs/api/alerts.asciidoc +++ b/docs/api/alerts.asciidoc @@ -22,7 +22,7 @@ The following alerts APIs are available: * <> to mute all alert instances for a single alert by ID -* <> to mute alert instance for a single {kib} alert by ID +* <> to mute alert instances for a single alert by ID * <> to unmute all alert instances for a single {kib} alert by ID From 95124b34bc6ddb9f3ab17666b26586c938f7530c Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:55:12 -0800 Subject: [PATCH 14/61] Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc index 7030725cba0e2..6823f733a6430 100644 --- a/docs/api/alerts.asciidoc +++ b/docs/api/alerts.asciidoc @@ -24,7 +24,7 @@ The following alerts APIs are available: * <> to mute alert instances for a single alert by ID -* <> to unmute all alert instances for a single {kib} alert by ID +* <> to unmute all alert instances for a single alert by ID * <> to unmute alert instance for a single {kib} alert by ID From 5d73cd2160e95226a22302b7aa772130d69211c6 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:55:23 -0800 Subject: [PATCH 15/61] Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc index 6823f733a6430..44710ec704b6c 100644 --- a/docs/api/alerts.asciidoc +++ b/docs/api/alerts.asciidoc @@ -26,7 +26,7 @@ The following alerts APIs are available: * <> to unmute all alert instances for a single alert by ID -* <> to unmute alert instance for a single {kib} alert by ID +* <> to unmute alert instances for a single alert by ID * <> to retrieve a {kib} alerts framework health From 5b6f2f38a65f5621c29e953ccd95df94c9812fa8 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:55:34 -0800 Subject: [PATCH 16/61] Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc index 44710ec704b6c..7be5fca684f4f 100644 --- a/docs/api/alerts.asciidoc +++ b/docs/api/alerts.asciidoc @@ -28,7 +28,7 @@ The following alerts APIs are available: * <> to unmute alert instances for a single alert by ID -* <> to retrieve a {kib} alerts framework health +* <> to retrieve the health of the alerts framework include::alerts/get.asciidoc[] include::alerts/list.asciidoc[] From d79e6e4af23eab4986fceef46f676bcc9735c852 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:55:50 -0800 Subject: [PATCH 17/61] Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/create.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc index 7cb22388460da..9db2d05311bec 100644 --- a/docs/api/alerts/create.asciidoc +++ b/docs/api/alerts/create.asciidoc @@ -21,7 +21,7 @@ Create {kib} alerts. (Optional, string array) A list of keywords to reference and search in the future. `alertTypeId`:: - (Required, string) The id value of the alert type you want to call when the alert is scheduled to execute. + (Required, string) The ID of the alert type that you want to call when the alert is scheduled to run. `schedule`:: (Required, object) The schedule specifying when this alert should be run, using one of the available schedule formats specified under _Schedule Formats_ below. From 677b02493946a9a4f4a1398c4c39c19f48820c56 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:56:03 -0800 Subject: [PATCH 18/61] Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/create.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc index 9db2d05311bec..e9a48f1ee458f 100644 --- a/docs/api/alerts/create.asciidoc +++ b/docs/api/alerts/create.asciidoc @@ -30,7 +30,7 @@ Create {kib} alerts. (Optional, string) A Duration specifying how often this alert should fire the same actions. This will prevent the alert from sending out the same notification over and over. For example, if an alert with a `schedule` of 1 minute stays in a triggered state for 90 minutes, setting a `throttle` of `10m` or `1h` will prevent it from sending 90 notifications over this period. `notifyWhen`:: - (Required, string) Defines the conditions for notifications thottling from the three available option types 'onActionGroupChange', 'onActiveAlert', 'onThrottleInterval'. + (Required, string) The condition for throttling the notification: `onActionGroupChange`, `onActiveAlert`, or `onThrottleInterval`. `enabled`:: (Optional, boolean) Indicate if you want the alert to start executing on an interval basis after it has been created. From f3a72080f523a6614cfe027d302f2f8bc9651e60 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:56:15 -0800 Subject: [PATCH 19/61] Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/create.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc index e9a48f1ee458f..a312852fa77ef 100644 --- a/docs/api/alerts/create.asciidoc +++ b/docs/api/alerts/create.asciidoc @@ -33,7 +33,7 @@ Create {kib} alerts. (Required, string) The condition for throttling the notification: `onActionGroupChange`, `onActiveAlert`, or `onThrottleInterval`. `enabled`:: - (Optional, boolean) Indicate if you want the alert to start executing on an interval basis after it has been created. + (Optional, boolean) Indicates if you want to run the alert on an interval basis after it is created. `consumer`:: (Required, string) A name of the application which owns the alert. From 7b3d155d17c8472215298874c132dafb053f227b Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:56:23 -0800 Subject: [PATCH 20/61] Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/create.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc index a312852fa77ef..ef954eeafcff2 100644 --- a/docs/api/alerts/create.asciidoc +++ b/docs/api/alerts/create.asciidoc @@ -36,7 +36,7 @@ Create {kib} alerts. (Optional, boolean) Indicates if you want to run the alert on an interval basis after it is created. `consumer`:: - (Required, string) A name of the application which owns the alert. + (Required, string) The name of the application that owns the alert. `params`:: (Required, object) The parameters to pass in to the alert type executor `params` value. This will also validate against the alert type params validator if defined. From cd64b9d8dfa1d3e4dd58b7798e6ad93c1bc2f011 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:56:31 -0800 Subject: [PATCH 21/61] Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/create.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc index ef954eeafcff2..a2473da4caee6 100644 --- a/docs/api/alerts/create.asciidoc +++ b/docs/api/alerts/create.asciidoc @@ -39,7 +39,7 @@ Create {kib} alerts. (Required, string) The name of the application that owns the alert. `params`:: - (Required, object) The parameters to pass in to the alert type executor `params` value. This will also validate against the alert type params validator if defined. + (Required, object) The parameters to pass to the alert type executor `params` value. This will also validate against the alert type params validator, if defined. `actions`:: (Optional, object array) Array of the following:
- `group` (string): We support grouping actions in the scenario of escalations or different types of alert instances. If you don't need this, feel free to use `default` as a value.
- `id` (string): The id of the action saved object to execute.
- `params` (object): The map to the `params` the action type will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. (see templating actions). From 058624b3833fb46a747855c318f594887c26da2d Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:56:40 -0800 Subject: [PATCH 22/61] Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/create.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc index a2473da4caee6..0d30bb3aae132 100644 --- a/docs/api/alerts/create.asciidoc +++ b/docs/api/alerts/create.asciidoc @@ -42,7 +42,7 @@ Create {kib} alerts. (Required, object) The parameters to pass to the alert type executor `params` value. This will also validate against the alert type params validator, if defined. `actions`:: - (Optional, object array) Array of the following:
- `group` (string): We support grouping actions in the scenario of escalations or different types of alert instances. If you don't need this, feel free to use `default` as a value.
- `id` (string): The id of the action saved object to execute.
- `params` (object): The map to the `params` the action type will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. (see templating actions). + (Optional, object array) An array of the following:
- `group` (string): We support grouping actions in the scenario of escalations or different types of alert instances. If you don't need this, feel free to use `default` as a value.
- `id` (string): The id of the action saved object to execute.
- `params` (object): The map to the `params` the action type will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. (see templating actions). [[alerts-api-create-request-codes]] ==== Response code From 46a5a8d46565f134b3789810425ac52b44f50e33 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:57:11 -0800 Subject: [PATCH 23/61] Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/create.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc index 0d30bb3aae132..8450991458198 100644 --- a/docs/api/alerts/create.asciidoc +++ b/docs/api/alerts/create.asciidoc @@ -24,7 +24,7 @@ Create {kib} alerts. (Required, string) The ID of the alert type that you want to call when the alert is scheduled to run. `schedule`:: - (Required, object) The schedule specifying when this alert should be run, using one of the available schedule formats specified under _Schedule Formats_ below. + (Required, object) When to run this alert. Use one of the available schedule formats. `throttle`:: (Optional, string) A Duration specifying how often this alert should fire the same actions. This will prevent the alert from sending out the same notification over and over. For example, if an alert with a `schedule` of 1 minute stays in a triggered state for 90 minutes, setting a `throttle` of `10m` or `1h` will prevent it from sending 90 notifications over this period. From b563b8a63f2af5c42cbc59d08776f88cc093ffa8 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 19:58:06 -0800 Subject: [PATCH 24/61] Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/create.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc index 8450991458198..5742646be10af 100644 --- a/docs/api/alerts/create.asciidoc +++ b/docs/api/alerts/create.asciidoc @@ -27,7 +27,7 @@ Create {kib} alerts. (Required, object) When to run this alert. Use one of the available schedule formats. `throttle`:: - (Optional, string) A Duration specifying how often this alert should fire the same actions. This will prevent the alert from sending out the same notification over and over. For example, if an alert with a `schedule` of 1 minute stays in a triggered state for 90 minutes, setting a `throttle` of `10m` or `1h` will prevent it from sending 90 notifications over this period. + (Optional, string) How often this alert should fire the same actions. This will prevent the alert from sending out the same notification over and over. For example, if an alert with a `schedule` of 1 minute stays in a triggered state for 90 minutes, setting a `throttle` of `10m` or `1h` will prevent it from sending 90 notifications during this period. `notifyWhen`:: (Required, string) The condition for throttling the notification: `onActionGroupChange`, `onActiveAlert`, or `onThrottleInterval`. From e6be6e8fc4a6410b508b21eca9bfd59edcb4d892 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:07:01 -0800 Subject: [PATCH 25/61] Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/create.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc index 5742646be10af..2fb4c09aedd77 100644 --- a/docs/api/alerts/create.asciidoc +++ b/docs/api/alerts/create.asciidoc @@ -15,7 +15,7 @@ Create {kib} alerts. ==== Request body `name`:: - (Required, string) A name to reference and search in the future. + (Required, string) A name to reference and search. `tags`:: (Optional, string array) A list of keywords to reference and search in the future. From f96abc391ab5f4ff7f88a1fdc5c2c3b753638fbf Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:07:24 -0800 Subject: [PATCH 26/61] Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/create.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc index 2fb4c09aedd77..6a7381d9ff97d 100644 --- a/docs/api/alerts/create.asciidoc +++ b/docs/api/alerts/create.asciidoc @@ -18,7 +18,7 @@ Create {kib} alerts. (Required, string) A name to reference and search. `tags`:: - (Optional, string array) A list of keywords to reference and search in the future. + (Optional, string array) A list of keywords to reference and search. `alertTypeId`:: (Required, string) The ID of the alert type that you want to call when the alert is scheduled to run. From f98c3c90f1d72e86ef7b7664e6742a6f48ae6b2c Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:07:43 -0800 Subject: [PATCH 27/61] Update docs/api/alerts/delete.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/delete.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/delete.asciidoc b/docs/api/alerts/delete.asciidoc index 5d86c0d9b13d2..a832b92294a70 100644 --- a/docs/api/alerts/delete.asciidoc +++ b/docs/api/alerts/delete.asciidoc @@ -6,7 +6,7 @@ Remove {kib} alerts. -WARNING: Once you delete an alert, _it cannot be recovered_. +WARNING: Once you delete an alert, you cannot recover it. [[alerts-api-delete-request]] ==== Request From ef16edfc83d2c11466983d10bcc9539eaa05792f Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:08:00 -0800 Subject: [PATCH 28/61] Update docs/api/alerts/delete.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/delete.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/delete.asciidoc b/docs/api/alerts/delete.asciidoc index a832b92294a70..1bf90a5669a72 100644 --- a/docs/api/alerts/delete.asciidoc +++ b/docs/api/alerts/delete.asciidoc @@ -17,7 +17,7 @@ WARNING: Once you delete an alert, you cannot recover it. ==== Path parameters `id`:: - (Required, string) The alert ID that you want to remove. + (Required, string) The ID of the alert that you want to remove. [[alerts-api-delete-response-codes]] ==== Response code From 9617bc3f155a4edaa4077efb68f17b8108e339a0 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:08:06 -0800 Subject: [PATCH 29/61] Update docs/api/alerts/disable.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/disable.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/disable.asciidoc b/docs/api/alerts/disable.asciidoc index fd5d6f47249ba..2f203356d435d 100644 --- a/docs/api/alerts/disable.asciidoc +++ b/docs/api/alerts/disable.asciidoc @@ -15,7 +15,7 @@ Disable {kib} alerts. ==== Path parameters `id`:: - (Required, string) The alert ID that you want to disable. + (Required, string) The ID of the alert that you want to disable. [[alerts-api-disable-response-codes]] ==== Response code From ff6ce3c91ea4e05c77ce9bee27c0760f1d1213f3 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:08:26 -0800 Subject: [PATCH 30/61] Update docs/api/alerts/enable.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/enable.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/enable.asciidoc b/docs/api/alerts/enable.asciidoc index 961da23e1c382..34214b72c9a79 100644 --- a/docs/api/alerts/enable.asciidoc +++ b/docs/api/alerts/enable.asciidoc @@ -4,7 +4,7 @@ Enable alert ++++ -Enable {kib} alerts. +Enable an alert. [[alerts-api-enable-request]] ==== Request From e6d837ca56cce00922b7ff826afdfdfc9b4593fa Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:10:09 -0800 Subject: [PATCH 31/61] Update docs/api/alerts/disable.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/disable.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/disable.asciidoc b/docs/api/alerts/disable.asciidoc index 2f203356d435d..5f74c33379409 100644 --- a/docs/api/alerts/disable.asciidoc +++ b/docs/api/alerts/disable.asciidoc @@ -4,7 +4,7 @@ Disable alert ++++ -Disable {kib} alerts. +Disable an alert. [[alerts-api-disable-request]] ==== Request From 1d1c1d783f2a046077d5fb39aea366ea56fd3cc2 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:10:51 -0800 Subject: [PATCH 32/61] Update docs/api/alerts/update.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/update.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/update.asciidoc b/docs/api/alerts/update.asciidoc index 021de89d71e20..d0ff32bce528a 100644 --- a/docs/api/alerts/update.asciidoc +++ b/docs/api/alerts/update.asciidoc @@ -50,7 +50,7 @@ Update the attributes for existing {kib} alerts. [[alerts-api-update-example]] ==== Example -Update an existing alert with ID `ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74`, with a different name: +Update an alert with ID `ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74` with a different name: [source,sh] -------------------------------------------------- From 9bf66e317f9b3346240ab6523af69bd21d6deaf2 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:11:11 -0800 Subject: [PATCH 33/61] Update docs/api/alerts/enable.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/enable.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/enable.asciidoc b/docs/api/alerts/enable.asciidoc index 34214b72c9a79..a10383f2a440d 100644 --- a/docs/api/alerts/enable.asciidoc +++ b/docs/api/alerts/enable.asciidoc @@ -15,7 +15,7 @@ Enable an alert. ==== Path parameters `id`:: - (Required, string) The alert ID that you want to enable. + (Required, string) The ID of the alert that you want to enable. [[alerts-api-enable-response-codes]] ==== Response code From 4fb804a0ecb0340f3419e731495710a0ab14fbdf Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:11:26 -0800 Subject: [PATCH 34/61] Update docs/api/alerts/find.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/find.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/find.asciidoc b/docs/api/alerts/find.asciidoc index 9f24290999986..d7f50eaf2d937 100644 --- a/docs/api/alerts/find.asciidoc +++ b/docs/api/alerts/find.asciidoc @@ -4,7 +4,7 @@ Find alerts ++++ -Retrieve a paginated set of {kib} alerts by various conditions. +Retrieve a paginated set of alerts based on condition. [[alerts-api-find-request]] ==== Request From 96c701762b2367b4d4ad6f81d5d91340704e812c Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:12:13 -0800 Subject: [PATCH 35/61] Update docs/api/alerts/find.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/find.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/find.asciidoc b/docs/api/alerts/find.asciidoc index d7f50eaf2d937..230172f24fe4b 100644 --- a/docs/api/alerts/find.asciidoc +++ b/docs/api/alerts/find.asciidoc @@ -39,7 +39,7 @@ Retrieve a paginated set of alerts based on condition. are defined in the `type` parameter, only "root" fields are allowed. `sort_order`:: - (Optional, string) Sort directions. Could be two values 'asc' or 'desc'. + (Optional, string) Sort direction, either `asc` or `desc`. `has_reference`:: (Optional, object) Filters to objects that have a relationship with the type and ID combination. From 3bec3bb342c0b16f5d5e76bc95d4ca66c7e6f957 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:19:53 -0800 Subject: [PATCH 36/61] Update docs/api/alerts/find.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/find.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/find.asciidoc b/docs/api/alerts/find.asciidoc index 230172f24fe4b..80f5b439a3d33 100644 --- a/docs/api/alerts/find.asciidoc +++ b/docs/api/alerts/find.asciidoc @@ -24,7 +24,7 @@ Retrieve a paginated set of alerts based on condition. (Optional, string) An Elasticsearch {ref}/query-dsl-simple-query-string-query.html[simple_query_string] query that filters the alerts in the response. `default_search_operator`:: - (Optional, string) The default operator to use for the `simple_query_string`. By default is 'OR'. + (Optional, string) The operator to use for the `simple_query_string`. The default is 'OR'. `search_fields`:: (Optional, array|string) The fields to perform the `simple_query_string` parsed query against. From e180a3415a96f8e2149f5605bfde8d8c51e1a01a Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:27:14 -0800 Subject: [PATCH 37/61] Update docs/api/alerts/find.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/find.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/find.asciidoc b/docs/api/alerts/find.asciidoc index 80f5b439a3d33..604bd04417256 100644 --- a/docs/api/alerts/find.asciidoc +++ b/docs/api/alerts/find.asciidoc @@ -45,7 +45,7 @@ Retrieve a paginated set of alerts based on condition. (Optional, object) Filters to objects that have a relationship with the type and ID combination. `filter`:: - (Optional, string) The filter is a KQL string with the caveat that if you filter with an attribute from your type saved object. + (Optional, string) A KQL string that you filter with an attribute from your saved object. It should look like that savedObjectType.attributes.title: "myTitle". However, If you used a direct attribute of a saved object like `updatedAt`, you will have to define your filter like that savedObjectType.updatedAt > 2018-12-22. From 62cce42d194307aff2f73c247e0d34ebb8e0b56d Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:27:37 -0800 Subject: [PATCH 38/61] Update docs/api/alerts/find.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/find.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/find.asciidoc b/docs/api/alerts/find.asciidoc index 604bd04417256..54af16e35b217 100644 --- a/docs/api/alerts/find.asciidoc +++ b/docs/api/alerts/find.asciidoc @@ -46,7 +46,7 @@ Retrieve a paginated set of alerts based on condition. `filter`:: (Optional, string) A KQL string that you filter with an attribute from your saved object. - It should look like that savedObjectType.attributes.title: "myTitle". However, If you used a direct attribute of a saved object like `updatedAt`, + It should look like savedObjectType.attributes.title: "myTitle". However, If you used a direct attribute of a saved object, such as `updatedAt`, you will have to define your filter like that savedObjectType.updatedAt > 2018-12-22. NOTE: As alerts change in {kib}, the results on each page of the response also From 0dd56d9247179c0a8176870d2a16d0e056051323 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:27:52 -0800 Subject: [PATCH 39/61] Update docs/api/alerts/find.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/find.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/find.asciidoc b/docs/api/alerts/find.asciidoc index 54af16e35b217..34c4065536a7b 100644 --- a/docs/api/alerts/find.asciidoc +++ b/docs/api/alerts/find.asciidoc @@ -47,7 +47,7 @@ Retrieve a paginated set of alerts based on condition. `filter`:: (Optional, string) A KQL string that you filter with an attribute from your saved object. It should look like savedObjectType.attributes.title: "myTitle". However, If you used a direct attribute of a saved object, such as `updatedAt`, - you will have to define your filter like that savedObjectType.updatedAt > 2018-12-22. + you will have to define your filter, for example, savedObjectType.updatedAt > 2018-12-22. NOTE: As alerts change in {kib}, the results on each page of the response also change. Use the find API for traditional paginated results, but avoid using it to export large amounts of data. From 3730bab214ec3d20aacb7777ba1346e1eac47668 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:28:17 -0800 Subject: [PATCH 40/61] Update docs/api/alerts/get.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/get.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/get.asciidoc b/docs/api/alerts/get.asciidoc index 799e5d03586f8..16712e3729b3f 100644 --- a/docs/api/alerts/get.asciidoc +++ b/docs/api/alerts/get.asciidoc @@ -4,7 +4,7 @@ Get alert ++++ -Retrieve a single {kib} alert by ID. +Retrieve an alert by ID. [[alerts-api-get-request]] ==== Request From 01a1585314629c3be49cce1120fa20e184b6e534 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:28:36 -0800 Subject: [PATCH 41/61] Update docs/api/alerts/get.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/get.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/get.asciidoc b/docs/api/alerts/get.asciidoc index 16712e3729b3f..934d7466dec3d 100644 --- a/docs/api/alerts/get.asciidoc +++ b/docs/api/alerts/get.asciidoc @@ -26,7 +26,7 @@ Retrieve an alert by ID. [[alerts-api-get-example]] ==== Example -Retrieve the alert object with the `41893910-6bca-11eb-9e0d-85d233e3ee35` ID: +Retrieve the alert object with the ID `41893910-6bca-11eb-9e0d-85d233e3ee35`: [source,sh] -------------------------------------------------- From f5a83bbdb97362a8fff9ad6fd13735427c75f1e9 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:28:55 -0800 Subject: [PATCH 42/61] Update docs/api/alerts/health.asciidoc Co-authored-by: Gidi Meir Morris --- docs/api/alerts/health.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/health.asciidoc b/docs/api/alerts/health.asciidoc index d8fb1d6abf3f8..240a9c24289fb 100644 --- a/docs/api/alerts/health.asciidoc +++ b/docs/api/alerts/health.asciidoc @@ -4,7 +4,7 @@ Get alert framework health ++++ -Retrieve the alert framework health status. +Retrieve the Alerting framework health status. [[alerts-api-health-request]] ==== Request From 599a0e147eb8fbb85fbcc5be65b496340d2f76c6 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:29:16 -0800 Subject: [PATCH 43/61] Update docs/api/alerts/health.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/health.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/health.asciidoc b/docs/api/alerts/health.asciidoc index 240a9c24289fb..b5eb528667b35 100644 --- a/docs/api/alerts/health.asciidoc +++ b/docs/api/alerts/health.asciidoc @@ -20,7 +20,7 @@ Retrieve the Alerting framework health status. [[alerts-api-health-example]] ==== Example -Retrieve the alert framework health status: +Retrieve the health status of the alert framework: [source,sh] -------------------------------------------------- From a63072ec8505104276c26bf43e45d5e55dd4b3a3 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:29:37 -0800 Subject: [PATCH 44/61] Update docs/api/alerts/health.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/health.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/health.asciidoc b/docs/api/alerts/health.asciidoc index b5eb528667b35..4af2eccbfb070 100644 --- a/docs/api/alerts/health.asciidoc +++ b/docs/api/alerts/health.asciidoc @@ -64,7 +64,7 @@ Health API response contains the following properties: | Return the state true if Encryption Saved Object plugin has a permanent encryption Key | `alertingFrameworkHeath` -| This state property includes three different substates: `decryptionHealth`, `executionHealth`, `readHealth` which identify the alerting framework API health. +| This state property has three substates that identify the health of the alerting framework API: `decryptionHealth`, `executionHealth`, and `readHealth`. |=== From 825e926cc690774b98036d151940851500aad1f7 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:29:51 -0800 Subject: [PATCH 45/61] Update docs/api/alerts/health.asciidoc Co-authored-by: Gidi Meir Morris --- docs/api/alerts/health.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/health.asciidoc b/docs/api/alerts/health.asciidoc index 4af2eccbfb070..7aba21b650692 100644 --- a/docs/api/alerts/health.asciidoc +++ b/docs/api/alerts/health.asciidoc @@ -68,7 +68,7 @@ Health API response contains the following properties: |=== -alertingFrameworkHeath itself consists from the next properties: +alertingFrameworkHeath itself consists from the following properties: [cols="2*<"] |=== From e61d6c495b6220a172a7449af17abe150a7ae8ff Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:30:16 -0800 Subject: [PATCH 46/61] Update docs/api/alerts/health.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/health.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/health.asciidoc b/docs/api/alerts/health.asciidoc index 7aba21b650692..9cd3cd6930ccc 100644 --- a/docs/api/alerts/health.asciidoc +++ b/docs/api/alerts/health.asciidoc @@ -52,7 +52,7 @@ The API returns the following: } -------------------------------------------------- -Health API response contains the following properties: +The health API response contains the following properties: [cols="2*<"] |=== From a890877891edc6e45e2eb7fa821269c0a676c4d1 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:30:36 -0800 Subject: [PATCH 47/61] Update docs/api/alerts/health.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/health.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/health.asciidoc b/docs/api/alerts/health.asciidoc index 9cd3cd6930ccc..41dc3be6dfa72 100644 --- a/docs/api/alerts/health.asciidoc +++ b/docs/api/alerts/health.asciidoc @@ -58,7 +58,7 @@ The health API response contains the following properties: |=== | `isSufficientlySecure` -| Return the state false if the security is enabled but TLS is not. +| Returns`false` if security is enabled, but TLS is not. | `hasPermanentEncryptionKey` | Return the state true if Encryption Saved Object plugin has a permanent encryption Key From 474c6b11d33545353f6f1e356d62651b28088584 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:31:16 -0800 Subject: [PATCH 48/61] Update docs/api/alerts/health.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/health.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/health.asciidoc b/docs/api/alerts/health.asciidoc index 41dc3be6dfa72..147c2d9e4ad72 100644 --- a/docs/api/alerts/health.asciidoc +++ b/docs/api/alerts/health.asciidoc @@ -74,7 +74,7 @@ alertingFrameworkHeath itself consists from the following properties: |=== | `decryptionHealth` -| Return the latest status `ok`, `warn` or `error` with the timestamp, which identify if the alerts have the decryption errors. +| Returns the timestamp and status of the alert decryption: `ok`, `warn` or `error` . | `executionHealth` | Return the latest status `ok`, `warn` or `error` with the timestamp, which identify if the alerts executions have results with the errors. From 14d90de180c3da4b2ec1878196295eaf794e957f Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:31:36 -0800 Subject: [PATCH 49/61] Update docs/api/alerts/list.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/list.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/list.asciidoc b/docs/api/alerts/list.asciidoc index a479f5420cfc9..95ce4a5d78421 100644 --- a/docs/api/alerts/list.asciidoc +++ b/docs/api/alerts/list.asciidoc @@ -4,7 +4,7 @@ List all alert types API ++++ -Retrieve a list of all {kib} alert types. +Retrieve a list of all alert types. [[alerts-api-list-request]] ==== Request From 273e1ec327ae4ef3fdd4335b933d5cf94be1562f Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:31:55 -0800 Subject: [PATCH 50/61] Update docs/api/alerts/health.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/health.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/health.asciidoc b/docs/api/alerts/health.asciidoc index 147c2d9e4ad72..adccabb3fba04 100644 --- a/docs/api/alerts/health.asciidoc +++ b/docs/api/alerts/health.asciidoc @@ -77,7 +77,7 @@ alertingFrameworkHeath itself consists from the following properties: | Returns the timestamp and status of the alert decryption: `ok`, `warn` or `error` . | `executionHealth` -| Return the latest status `ok`, `warn` or `error` with the timestamp, which identify if the alerts executions have results with the errors. +| Returns the timestamp and status of the alert execution: `ok`, `warn` or `error`. | `readHealth` | Return the latest status `ok`, `warn` or `error` with the timestamp, which identify if the alerts read events have any errors. From 4bb7965f2c82ee438452e0412d270b56854ca575 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:32:15 -0800 Subject: [PATCH 51/61] Update docs/api/alerts/health.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/health.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/health.asciidoc b/docs/api/alerts/health.asciidoc index adccabb3fba04..169a377db31cc 100644 --- a/docs/api/alerts/health.asciidoc +++ b/docs/api/alerts/health.asciidoc @@ -80,6 +80,6 @@ alertingFrameworkHeath itself consists from the following properties: | Returns the timestamp and status of the alert execution: `ok`, `warn` or `error`. | `readHealth` -| Return the latest status `ok`, `warn` or `error` with the timestamp, which identify if the alerts read events have any errors. +| Returns the timestamp and status of the alert reading events: `ok`, `warn` or `error`. |=== From 826df7d4d13261cd615deca6adee876e64f9d6d7 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:33:16 -0800 Subject: [PATCH 52/61] Update docs/api/alerts/list.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/list.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/list.asciidoc b/docs/api/alerts/list.asciidoc index 95ce4a5d78421..3956426badecd 100644 --- a/docs/api/alerts/list.asciidoc +++ b/docs/api/alerts/list.asciidoc @@ -89,7 +89,7 @@ The API returns the following: ] -------------------------------------------------- -Each alert type object contains the following properties: +Each alert type contains the following properties: [cols="2*<"] |=== From 866aacba8409c2aa7cb504268ca575db6d47f8d5 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:33:33 -0800 Subject: [PATCH 53/61] Update docs/api/alerts/list.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/list.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/list.asciidoc b/docs/api/alerts/list.asciidoc index 3956426badecd..b54f814ec89ad 100644 --- a/docs/api/alerts/list.asciidoc +++ b/docs/api/alerts/list.asciidoc @@ -104,7 +104,7 @@ Each alert type contains the following properties: | The license required to use the alert type. | `enabledInLicense` -| Whether the alert type is enabled or disabled due to license. +| Whether the alert type is enabled or disabled based on the license. | `actionGroups` | An explicit list of groups the alert type may schedule actions for, each specifying the ActionGroup's unique ID and human readable name. Alert `actions` validation will use this configuartion to ensure groups are valid. We highly encourage using `kbn-i18n` to translate the names of actionGroup when registering the AlertType. From 379e46e61b973beec6459af890d357e65aa8dede Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:34:23 -0800 Subject: [PATCH 54/61] Update docs/api/alerts/list.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/list.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/alerts/list.asciidoc b/docs/api/alerts/list.asciidoc index b54f814ec89ad..b40fe104e8f6e 100644 --- a/docs/api/alerts/list.asciidoc +++ b/docs/api/alerts/list.asciidoc @@ -107,7 +107,7 @@ Each alert type contains the following properties: | Whether the alert type is enabled or disabled based on the license. | `actionGroups` -| An explicit list of groups the alert type may schedule actions for, each specifying the ActionGroup's unique ID and human readable name. Alert `actions` validation will use this configuartion to ensure groups are valid. We highly encourage using `kbn-i18n` to translate the names of actionGroup when registering the AlertType. +| An explicit list of groups for which the alert type can schedule actions, each with the action group's unique ID and human readable name. Alert `actions` validation will use this configuration to ensure that groups are valid. Use `kbn-i18n` to translate the names of the action group when registering the alert type. | `recoveryActionGroup` | An action group to use when an alert instance goes from an active state, to an inactive one. This action group should not be specified under the `actionGroups` property. If no recoveryActionGroup is specified, the default `recovered` action group will be used. From 32400f8a14484523e8fda7a91993e8d119e2105f Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:37:28 -0800 Subject: [PATCH 55/61] Apply suggestions from code review Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/list.asciidoc | 10 +++++----- docs/api/alerts/mute.asciidoc | 4 ++-- docs/api/alerts/mute_all.asciidoc | 2 +- docs/api/alerts/unmute.asciidoc | 6 +++--- docs/api/alerts/unmute_all.asciidoc | 2 +- docs/api/alerts/update.asciidoc | 14 +++++++------- 6 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/api/alerts/list.asciidoc b/docs/api/alerts/list.asciidoc index b40fe104e8f6e..0bc3e158ec263 100644 --- a/docs/api/alerts/list.asciidoc +++ b/docs/api/alerts/list.asciidoc @@ -110,18 +110,18 @@ Each alert type contains the following properties: | An explicit list of groups for which the alert type can schedule actions, each with the action group's unique ID and human readable name. Alert `actions` validation will use this configuration to ensure that groups are valid. Use `kbn-i18n` to translate the names of the action group when registering the alert type. | `recoveryActionGroup` -| An action group to use when an alert instance goes from an active state, to an inactive one. This action group should not be specified under the `actionGroups` property. If no recoveryActionGroup is specified, the default `recovered` action group will be used. +| An action group to use when an alert instance goes from an active state, to an inactive one. Do not specify this action group under the `actionGroups` property. If `recoveryActionGroup` is not specified, the default `recovered` action group is used. | `defaultActionGroupId` -| Default ID value for the group of the alert type. +| The default ID for the alert type group. | `actionVariables` -| An explicit list of action variables the alert type makes available via context and state in action parameter templates, and a short human readable description. Alert UI will use this to display prompts for the users for these variables, in action parameter editors. We highly encourage using `kbn-i18n` to translate the descriptions. +| An explicit list of action variables that the alert type makes available via context and state in action parameter templates, and a short human readable description. The Alert UI will use this information to prompt users for these variables in action parameter editors. Use `kbn-i18n` to translate the descriptions. | `producer` -| The id of the application producing this alert type. +| The ID of the application producing this alert type. | `authorizedConsumers` -| The list of the plugins ids which has access for the alert type. +| The list of the plugins IDs that have access to the alert type. |=== diff --git a/docs/api/alerts/mute.asciidoc b/docs/api/alerts/mute.asciidoc index 90b1d74d62a60..f96300dfb5a81 100644 --- a/docs/api/alerts/mute.asciidoc +++ b/docs/api/alerts/mute.asciidoc @@ -4,7 +4,7 @@ Mute alert instance ++++ -Mute {kib} alert instance. +Mute an alert instance. [[alerts-api-mute-request]] ==== Request @@ -18,7 +18,7 @@ Mute {kib} alert instance. (Required, string) The alert ID that you want to mute a single instance. `alert_instance_id`:: - (Required, string) The alert instance ID that you want to mute. + (Required, string) The ID of the alert instance that you want to mute. [[alerts-api-mute-response-codes]] ==== Response code diff --git a/docs/api/alerts/mute_all.asciidoc b/docs/api/alerts/mute_all.asciidoc index f7a7e0755c745..982f4bf382ef1 100644 --- a/docs/api/alerts/mute_all.asciidoc +++ b/docs/api/alerts/mute_all.asciidoc @@ -4,7 +4,7 @@ Mute all alert instances ++++ -Mute all {kib} alert instances. +Mute all alert instances. [[alerts-api-mute-all-request]] ==== Request diff --git a/docs/api/alerts/unmute.asciidoc b/docs/api/alerts/unmute.asciidoc index f118ad434aa44..f091ae3f45325 100644 --- a/docs/api/alerts/unmute.asciidoc +++ b/docs/api/alerts/unmute.asciidoc @@ -4,7 +4,7 @@ Unmute alert instance ++++ -Unmute {kib} alert instance. +Unmute an alert instance. [[alerts-api-unmute-request]] ==== Request @@ -15,10 +15,10 @@ Unmute {kib} alert instance. ==== Path parameters `id`:: - (Required, string) The alert ID that you want to unmute a single instance. + (Required, string) The ID of the alert whose instance you want to mute.. `alert_instance_id`:: - (Required, string) The alert instance ID that you want to unmute. + (Required, string) The ID of the alert instance that you want to unmute. [[alerts-api-unmute-response-codes]] ==== Response code diff --git a/docs/api/alerts/unmute_all.asciidoc b/docs/api/alerts/unmute_all.asciidoc index ade5618606e71..3d2a39570bef9 100644 --- a/docs/api/alerts/unmute_all.asciidoc +++ b/docs/api/alerts/unmute_all.asciidoc @@ -4,7 +4,7 @@ Unmute all alert instances ++++ -Unmute all {kib} alert instances. +Unmute all alert instances. [[alerts-api-unmute-all-request]] ==== Request diff --git a/docs/api/alerts/update.asciidoc b/docs/api/alerts/update.asciidoc index d0ff32bce528a..6b2c879d7e378 100644 --- a/docs/api/alerts/update.asciidoc +++ b/docs/api/alerts/update.asciidoc @@ -4,7 +4,7 @@ Update alert ++++ -Update the attributes for existing {kib} alerts. +Update the attributes for an existing alert. [[alerts-api-update-request]] ==== Request @@ -15,28 +15,28 @@ Update the attributes for existing {kib} alerts. ==== Path parameters `id`:: - (Required, string) The alert ID to update. + (Required, string) The ID of the alert that you want to update. [[alerts-api-update-request-body]] ==== Request body `name`:: - (Required, string) A name to reference and search in the future. + (Required, string) A name to reference and search. `tags`:: - (Optional, string array) A list of keywords to reference and search in the future. + (Optional, string array) A list of keywords to reference and search. `schedule`:: (Required, object) The schedule specifying when this alert should be run, using one of the available schedule formats specified under _Schedule Formats_ below. `throttle`:: - (Optional, string) A Duration specifying how often this alert should fire the same actions. This will prevent the alert from sending out the same notification over and over. For example, if an alert with a `schedule` of 1 minute stays in a triggered state for 90 minutes, setting a `throttle` of `10m` or `1h` will prevent it from sending 90 notifications over this period. + (Optional, string) How often this alert should fire the same actions. This will prevent the alert from sending out the same notification over and over. For example, if an alert with a `schedule` of 1 minute stays in a triggered state for 90 minutes, setting a `throttle` of `10m` or `1h` will prevent it from sending 90 notifications during this period. `notifyWhen`:: - (Required, string) Defines the conditions for notifications thottling from the three available option types 'onActionGroupChange', 'onActiveAlert', 'onThrottleInterval'. + (Required, string) The condition for throttling the notification: `onActionGroupChange`, `onActiveAlert`, or `onThrottleInterval`. `params`:: - (Required, object) The parameters to pass in to the alert type executor `params` value. This will also validate against the alert type params validator if defined. + (Required, object) The parameters to pass to the alert type executor `params` value. This will also validate against the alert type params validator, if defined. `actions`:: (Optional, object array) Array of the following:
- `group` (string): We support grouping actions in the scenario of escalations or different types of alert instances. If you don't need this, feel free to use `default` as a value.
- `id` (string): The id of the action saved object to execute.
- `params` (object): The map to the `params` the action type will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. (see templating actions). From 698993ebde4d1322a91513e5d820d15589540480 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Tue, 16 Feb 2021 21:57:03 -0800 Subject: [PATCH 56/61] fixed due to comments --- docs/api/alerts.asciidoc | 15 +++++++-------- docs/api/alerts/create.asciidoc | 2 +- docs/api/alerts/delete.asciidoc | 2 +- docs/api/alerts/find.asciidoc | 6 +++--- docs/api/alerts/health.asciidoc | 10 +++++----- docs/api/alerts/mute.asciidoc | 2 +- docs/api/alerts/mute_all.asciidoc | 2 +- docs/api/alerts/unmute_all.asciidoc | 2 +- docs/api/alerts/update.asciidoc | 12 +++++++++++- 9 files changed, 31 insertions(+), 22 deletions(-) diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc index 7be5fca684f4f..42a8ebd0b6a84 100644 --- a/docs/api/alerts.asciidoc +++ b/docs/api/alerts.asciidoc @@ -1,8 +1,7 @@ [[alerts-api]] == Alerts APIs -Manage {kib} alerts. -The following alerts APIs are available: +The following APIs are available for managing {kib} alerts. * <> to create an alert @@ -30,16 +29,16 @@ The following alerts APIs are available: * <> to retrieve the health of the alerts framework -include::alerts/get.asciidoc[] -include::alerts/list.asciidoc[] -include::alerts/find.asciidoc[] include::alerts/create.asciidoc[] -include::alerts/enable.asciidoc[] include::alerts/update.asciidoc[] +include::alerts/get.asciidoc[] include::alerts/delete.asciidoc[] +include::alerts/find.asciidoc[] +include::alerts/list.asciidoc[] +include::alerts/enable.asciidoc[] include::alerts/disable.asciidoc[] -include::alerts/mute.asciidoc[] -include::alerts/unmute.asciidoc[] include::alerts/mute_all.asciidoc[] +include::alerts/mute.asciidoc[] include::alerts/unmute_all.asciidoc[] +include::alerts/unmute.asciidoc[] include::alerts/health.asciidoc[] diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc index 5742646be10af..4acc152590aa9 100644 --- a/docs/api/alerts/create.asciidoc +++ b/docs/api/alerts/create.asciidoc @@ -36,7 +36,7 @@ Create {kib} alerts. (Optional, boolean) Indicates if you want to run the alert on an interval basis after it is created. `consumer`:: - (Required, string) The name of the application that owns the alert. + (Required, string) The name of the application that owns the alert. This name has to match the Kibana Feature name, as that dictates the required RBAC privileges. `params`:: (Required, object) The parameters to pass to the alert type executor `params` value. This will also validate against the alert type params validator, if defined. diff --git a/docs/api/alerts/delete.asciidoc b/docs/api/alerts/delete.asciidoc index 5d86c0d9b13d2..73e0e791df798 100644 --- a/docs/api/alerts/delete.asciidoc +++ b/docs/api/alerts/delete.asciidoc @@ -4,7 +4,7 @@ Delete alert ++++ -Remove {kib} alerts. +Permanently remove an alert. WARNING: Once you delete an alert, _it cannot be recovered_. diff --git a/docs/api/alerts/find.asciidoc b/docs/api/alerts/find.asciidoc index 9f24290999986..2312421682efe 100644 --- a/docs/api/alerts/find.asciidoc +++ b/docs/api/alerts/find.asciidoc @@ -15,10 +15,10 @@ Retrieve a paginated set of {kib} alerts by various conditions. ==== Query Parameters `per_page`:: - (Optional, number) The number of objects to return per page. + (Optional, number) The number of alerts to return per page. `page`:: - (Optional, number) The page of objects to return. + (Optional, number) The page number. `search`:: (Optional, string) An Elasticsearch {ref}/query-dsl-simple-query-string-query.html[simple_query_string] query that filters the alerts in the response. @@ -42,7 +42,7 @@ Retrieve a paginated set of {kib} alerts by various conditions. (Optional, string) Sort directions. Could be two values 'asc' or 'desc'. `has_reference`:: - (Optional, object) Filters to objects that have a relationship with the type and ID combination. + (Optional, object) Filters the alerts that have a relations with the reference objects with the specific "type" and "ID". `filter`:: (Optional, string) The filter is a KQL string with the caveat that if you filter with an attribute from your type saved object. diff --git a/docs/api/alerts/health.asciidoc b/docs/api/alerts/health.asciidoc index d8fb1d6abf3f8..c9c1b94b48829 100644 --- a/docs/api/alerts/health.asciidoc +++ b/docs/api/alerts/health.asciidoc @@ -1,10 +1,10 @@ [[alerts-api-health]] -=== Get alert framework health API +=== Get Alerting framework health API ++++ -Get alert framework health +Get Alerting framework health ++++ -Retrieve the alert framework health status. +Retrieve the health status of the Alerting framework. [[alerts-api-health-request]] ==== Request @@ -20,7 +20,7 @@ Retrieve the alert framework health status. [[alerts-api-health-example]] ==== Example -Retrieve the alert framework health status: +Retrieve the Alerting framework health status: [source,sh] -------------------------------------------------- @@ -68,7 +68,7 @@ Health API response contains the following properties: |=== -alertingFrameworkHeath itself consists from the next properties: +`alertingFrameworkHeath` consists of the following properties: [cols="2*<"] |=== diff --git a/docs/api/alerts/mute.asciidoc b/docs/api/alerts/mute.asciidoc index 90b1d74d62a60..ce9298fd99cfc 100644 --- a/docs/api/alerts/mute.asciidoc +++ b/docs/api/alerts/mute.asciidoc @@ -15,7 +15,7 @@ Mute {kib} alert instance. ==== Path parameters `id`:: - (Required, string) The alert ID that you want to mute a single instance. + (Required, string) The ID of the alert whose instance you want to mute. `alert_instance_id`:: (Required, string) The alert instance ID that you want to mute. diff --git a/docs/api/alerts/mute_all.asciidoc b/docs/api/alerts/mute_all.asciidoc index f7a7e0755c745..148dfe04845a2 100644 --- a/docs/api/alerts/mute_all.asciidoc +++ b/docs/api/alerts/mute_all.asciidoc @@ -15,7 +15,7 @@ Mute all {kib} alert instances. ==== Path parameters `id`:: - (Required, string) The alert ID that you want to mute all instances. + (Required, string) The ID of the alert whose instances you want to mute. [[alerts-api-mute-all-response-codes]] ==== Response code diff --git a/docs/api/alerts/unmute_all.asciidoc b/docs/api/alerts/unmute_all.asciidoc index ade5618606e71..87c8eaad360a2 100644 --- a/docs/api/alerts/unmute_all.asciidoc +++ b/docs/api/alerts/unmute_all.asciidoc @@ -15,7 +15,7 @@ Unmute all {kib} alert instances. ==== Path parameters `id`:: - (Required, string) The alert ID that you want to unmute all instances. + (Required, string) The ID of the alert whose instances you want to unmute. [[alerts-api-unmute-all-response-codes]] ==== Response code diff --git a/docs/api/alerts/update.asciidoc b/docs/api/alerts/update.asciidoc index 021de89d71e20..d7c62a0ef8cc5 100644 --- a/docs/api/alerts/update.asciidoc +++ b/docs/api/alerts/update.asciidoc @@ -39,7 +39,17 @@ Update the attributes for existing {kib} alerts. (Required, object) The parameters to pass in to the alert type executor `params` value. This will also validate against the alert type params validator if defined. `actions`:: - (Optional, object array) Array of the following:
- `group` (string): We support grouping actions in the scenario of escalations or different types of alert instances. If you don't need this, feel free to use `default` as a value.
- `id` (string): The id of the action saved object to execute.
- `params` (object): The map to the `params` the action type will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. (see templating actions). + (Optional, object array) An array of the following:
- `group` (string): We support grouping actions in the scenario of escalations or different types of alert instances. If you don't need this, feel free to use `default` as a value.
- `id` (string): The id of the action saved object to execute.
- `params` (object): The map to the `params` the action type will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. (see templating actions). + + +[[shedule-formats]] +==== Schedule Formats +A schedule is structured such that the key specifies the format you wish to use and its value specifies the schedule. + +We currently support the _Interval format_ which specifies the interval in seconds, minutes, hours or days at which the alert should execute. +Example: `{ interval: "10s" }`, `{ interval: "5m" }`, `{ interval: "1h" }`, `{ interval: "1d" }`. + +There are plans to support multiple other schedule formats in the near future. [[alerts-api-update-errors-codes]] ==== Response code From 526d5df583e723ff88de68c2d0fa94ccf980d074 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Wed, 17 Feb 2021 10:42:26 -0800 Subject: [PATCH 57/61] fixed due to comments --- docs/api/alerts/create.asciidoc | 19 +++++++++++++++++- docs/api/alerts/find.asciidoc | 9 ++++----- docs/api/alerts/health.asciidoc | 4 ++-- docs/api/alerts/update.asciidoc | 34 +++++++++++++++++++++++++-------- 4 files changed, 50 insertions(+), 16 deletions(-) diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc index cae6029c41dd8..100b702727357 100644 --- a/docs/api/alerts/create.asciidoc +++ b/docs/api/alerts/create.asciidoc @@ -42,7 +42,24 @@ Create {kib} alerts. (Required, object) The parameters to pass to the alert type executor `params` value. This will also validate against the alert type params validator, if defined. `actions`:: - (Optional, object array) An array of the following:
- `group` (string): We support grouping actions in the scenario of escalations or different types of alert instances. If you don't need this, feel free to use `default` as a value.
- `id` (string): The id of the action saved object to execute.
- `params` (object): The map to the `params` the action type will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. (see templating actions). + (Optional, object array) An array of the following action objects: ++ +.Properties of `objects` +[%collapsible%open] +===== + `group`::: + (Required, string) We support grouping actions in the scenario of escalations or different types of alert instances. If you don't need this, feel free to use `default` as a value. + + `id`::: + (Required, string) The id of the action saved object to execute. + + `actionTypeId`::: + (Required, string) The id of the action type. + + `params`::: + (Required, object) The map to the `params` the action type will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. +===== + [[alerts-api-create-request-codes]] ==== Response code diff --git a/docs/api/alerts/find.asciidoc b/docs/api/alerts/find.asciidoc index 9feab9908e1dc..bf1d4bf5b4d7b 100644 --- a/docs/api/alerts/find.asciidoc +++ b/docs/api/alerts/find.asciidoc @@ -33,10 +33,7 @@ Retrieve a paginated set of alerts based on condition. (Optional, array|string) The fields to return in the `attributes` key of the response. `sort_field`:: - (Optional, string) Sorts the response. Includes "root" and "type" fields. "root" fields exist for all saved objects, such as "updated_at". - "type" fields are specific to an object type, such as fields returned in the `attributes` key of the response. When a single type is - defined in the `type` parameter, the "root" and "type" fields are allowed, and validity checks are made in that order. When multiple types - are defined in the `type` parameter, only "root" fields are allowed. + (Optional, string) Sorts the response. Could be an alert fields returned in the `attributes` key of the response. `sort_order`:: (Optional, string) Sort direction, either `asc` or `desc`. @@ -45,7 +42,7 @@ Retrieve a paginated set of alerts based on condition. (Optional, object) Filters the alerts that have a relations with the reference objects with the specific "type" and "ID". `filter`:: - (Optional, string) A KQL string that you filter with an attribute from your saved object. + (Optional, string) A <> string that you filter with an attribute from your saved object. It should look like savedObjectType.attributes.title: "myTitle". However, If you used a direct attribute of a saved object, such as `updatedAt`, you will have to define your filter, for example, savedObjectType.updatedAt > 2018-12-22. @@ -118,3 +115,5 @@ query parameter for each value: $ curl -X GET api/alerts/_find?fields=id&fields=name -------------------------------------------------- // KIBANA + +include::discover/kuery.asciidoc[] diff --git a/docs/api/alerts/health.asciidoc b/docs/api/alerts/health.asciidoc index 85f34f9b3cc3a..67434ffd68c90 100644 --- a/docs/api/alerts/health.asciidoc +++ b/docs/api/alerts/health.asciidoc @@ -58,10 +58,10 @@ The health API response contains the following properties: |=== | `isSufficientlySecure` -| Returns`false` if security is enabled, but TLS is not. +| Returns `false` if security is enabled, but TLS is not. | `hasPermanentEncryptionKey` -| Return the state true if Encryption Saved Object plugin has a permanent encryption Key +| Return the state `false` if Encrypted Saved Object plugin has not a permanent encryption Key. | `alertingFrameworkHeath` | This state property has three substates that identify the health of the alerting framework API: `decryptionHealth`, `executionHealth`, and `readHealth`. diff --git a/docs/api/alerts/update.asciidoc b/docs/api/alerts/update.asciidoc index 45a28a4087886..a2569d4690b69 100644 --- a/docs/api/alerts/update.asciidoc +++ b/docs/api/alerts/update.asciidoc @@ -27,7 +27,18 @@ Update the attributes for an existing alert. (Optional, string array) A list of keywords to reference and search. `schedule`:: - (Required, object) The schedule specifying when this alert should be run, using one of the available schedule formats specified under _Schedule Formats_ below. + (Required, object) The schedule specifying when this alert should be run, using one of the available schedule formats specified under ++ +._Schedule Formats_. +[%collapsible%open] +===== +A schedule is structured such that the key specifies the format you wish to use and its value specifies the schedule. + +We currently support the _Interval format_ which specifies the interval in seconds, minutes, hours or days at which the alert should execute. +Example: `{ interval: "10s" }`, `{ interval: "5m" }`, `{ interval: "1h" }`, `{ interval: "1d" }`. + +There are plans to support multiple other schedule formats in the near future. +===== `throttle`:: (Optional, string) How often this alert should fire the same actions. This will prevent the alert from sending out the same notification over and over. For example, if an alert with a `schedule` of 1 minute stays in a triggered state for 90 minutes, setting a `throttle` of `10m` or `1h` will prevent it from sending 90 notifications during this period. @@ -39,17 +50,24 @@ Update the attributes for an existing alert. (Required, object) The parameters to pass to the alert type executor `params` value. This will also validate against the alert type params validator, if defined. `actions`:: - (Optional, object array) An array of the following:
- `group` (string): We support grouping actions in the scenario of escalations or different types of alert instances. If you don't need this, feel free to use `default` as a value.
- `id` (string): The id of the action saved object to execute.
- `params` (object): The map to the `params` the action type will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. (see templating actions). + (Optional, object array) An array of the following action objects: ++ +.Properties of `objects` +[%collapsible%open] +===== + `group`::: + (Required, string) We support grouping actions in the scenario of escalations or different types of alert instances. If you don't need this, feel free to use `default` as a value. + `id`::: + (Required, string) The id of the action saved object to execute. -[[shedule-formats]] -==== Schedule Formats -A schedule is structured such that the key specifies the format you wish to use and its value specifies the schedule. + `actionTypeId`::: + (Required, string) The id of the action type. -We currently support the _Interval format_ which specifies the interval in seconds, minutes, hours or days at which the alert should execute. -Example: `{ interval: "10s" }`, `{ interval: "5m" }`, `{ interval: "1h" }`, `{ interval: "1d" }`. + `params`::: + (Required, object) The map to the `params` the action type will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. +===== -There are plans to support multiple other schedule formats in the near future. [[alerts-api-update-errors-codes]] ==== Response code From 51b2ab191177f5ff5e14ff1e67076cf843845974 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Wed, 17 Feb 2021 10:51:43 -0800 Subject: [PATCH 58/61] fixed due to comments --- docs/api/alerts/create.asciidoc | 2 +- docs/api/alerts/find.asciidoc | 2 -- docs/api/alerts/update.asciidoc | 2 +- 3 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc index 100b702727357..7c07d4537f9d7 100644 --- a/docs/api/alerts/create.asciidoc +++ b/docs/api/alerts/create.asciidoc @@ -57,7 +57,7 @@ Create {kib} alerts. (Required, string) The id of the action type. `params`::: - (Required, object) The map to the `params` the action type will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. + (Required, object) The map to the `params` the <> will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. ===== diff --git a/docs/api/alerts/find.asciidoc b/docs/api/alerts/find.asciidoc index bf1d4bf5b4d7b..97cd9f4c19ba7 100644 --- a/docs/api/alerts/find.asciidoc +++ b/docs/api/alerts/find.asciidoc @@ -115,5 +115,3 @@ query parameter for each value: $ curl -X GET api/alerts/_find?fields=id&fields=name -------------------------------------------------- // KIBANA - -include::discover/kuery.asciidoc[] diff --git a/docs/api/alerts/update.asciidoc b/docs/api/alerts/update.asciidoc index a2569d4690b69..4152f9313377d 100644 --- a/docs/api/alerts/update.asciidoc +++ b/docs/api/alerts/update.asciidoc @@ -65,7 +65,7 @@ There are plans to support multiple other schedule formats in the near future. (Required, string) The id of the action type. `params`::: - (Required, object) The map to the `params` the action type will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. + (Required, object) The map to the `params` the <>. will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. ===== From ba03d92c10002996f622c8a6f2906abaedc0acd9 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Wed, 17 Feb 2021 11:09:42 -0800 Subject: [PATCH 59/61] fixed links --- docs/api/alerts/create.asciidoc | 6 +++--- docs/api/alerts/update.asciidoc | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc index 7c07d4537f9d7..80db795760aa1 100644 --- a/docs/api/alerts/create.asciidoc +++ b/docs/api/alerts/create.asciidoc @@ -42,9 +42,9 @@ Create {kib} alerts. (Required, object) The parameters to pass to the alert type executor `params` value. This will also validate against the alert type params validator, if defined. `actions`:: - (Optional, object array) An array of the following action objects: + (Optional, object array) An array of the following action objects. + -.Properties of `objects` +.Properties of the action objects: [%collapsible%open] ===== `group`::: @@ -54,7 +54,7 @@ Create {kib} alerts. (Required, string) The id of the action saved object to execute. `actionTypeId`::: - (Required, string) The id of the action type. + (Required, string) The id of the <>. `params`::: (Required, object) The map to the `params` the <> will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. diff --git a/docs/api/alerts/update.asciidoc b/docs/api/alerts/update.asciidoc index 4152f9313377d..1d34723ea9f91 100644 --- a/docs/api/alerts/update.asciidoc +++ b/docs/api/alerts/update.asciidoc @@ -50,9 +50,9 @@ There are plans to support multiple other schedule formats in the near future. (Required, object) The parameters to pass to the alert type executor `params` value. This will also validate against the alert type params validator, if defined. `actions`:: - (Optional, object array) An array of the following action objects: + (Optional, object array) An array of the following action objects. + -.Properties of `objects` +.Properties of the action objects: [%collapsible%open] ===== `group`::: @@ -62,10 +62,10 @@ There are plans to support multiple other schedule formats in the near future. (Required, string) The id of the action saved object to execute. `actionTypeId`::: - (Required, string) The id of the action type. + (Required, string) The id of the <>. `params`::: - (Required, object) The map to the `params` the <>. will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. + (Required, object) The map to the `params` the <> will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. ===== From e49aeea3d986bad6ded9d1c266ab12d0d0465b57 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Thu, 18 Feb 2021 12:12:49 -0800 Subject: [PATCH 60/61] Apply suggestions from code review Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/api/alerts/create.asciidoc | 8 ++++---- docs/api/alerts/health.asciidoc | 2 +- docs/api/alerts/update.asciidoc | 12 +++++------- 3 files changed, 10 insertions(+), 12 deletions(-) diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc index 80db795760aa1..e146862f85d43 100644 --- a/docs/api/alerts/create.asciidoc +++ b/docs/api/alerts/create.asciidoc @@ -48,16 +48,16 @@ Create {kib} alerts. [%collapsible%open] ===== `group`::: - (Required, string) We support grouping actions in the scenario of escalations or different types of alert instances. If you don't need this, feel free to use `default` as a value. + (Required, string) Grouping actions is recommended for escalations for different types of alert instances. If you don't need this, set this value to `default`. `id`::: - (Required, string) The id of the action saved object to execute. + (Required, string) The ID of the action saved object to execute. `actionTypeId`::: - (Required, string) The id of the <>. + (Required, string) The ID of the <>. `params`::: - (Required, object) The map to the `params` the <> will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. + (Required, object) The map to the `params` that the <> will receive. ` params` are handled as Mustache templates and passed a default set of context. ===== diff --git a/docs/api/alerts/health.asciidoc b/docs/api/alerts/health.asciidoc index 67434ffd68c90..3710ccf424945 100644 --- a/docs/api/alerts/health.asciidoc +++ b/docs/api/alerts/health.asciidoc @@ -20,7 +20,7 @@ Retrieve the health status of the Alerting framework. [[alerts-api-health-example]] ==== Example -Retrieve the Alerting framework health status: +Retrieve the health status of the Alerting framework: [source,sh] -------------------------------------------------- diff --git a/docs/api/alerts/update.asciidoc b/docs/api/alerts/update.asciidoc index 1d34723ea9f91..aee2dd049a66f 100644 --- a/docs/api/alerts/update.asciidoc +++ b/docs/api/alerts/update.asciidoc @@ -27,17 +27,15 @@ Update the attributes for an existing alert. (Optional, string array) A list of keywords to reference and search. `schedule`:: - (Required, object) The schedule specifying when this alert should be run, using one of the available schedule formats specified under + (Required, object) When to run this alert. Use one of the available schedule formats. + ._Schedule Formats_. [%collapsible%open] ===== -A schedule is structured such that the key specifies the format you wish to use and its value specifies the schedule. +A schedule uses a key: value format. {kib} currently supports the _Interval format_ , which specifies the interval in seconds, minutes, hours, or days at which to execute the alert. -We currently support the _Interval format_ which specifies the interval in seconds, minutes, hours or days at which the alert should execute. Example: `{ interval: "10s" }`, `{ interval: "5m" }`, `{ interval: "1h" }`, `{ interval: "1d" }`. -There are plans to support multiple other schedule formats in the near future. ===== `throttle`:: @@ -56,16 +54,16 @@ There are plans to support multiple other schedule formats in the near future. [%collapsible%open] ===== `group`::: - (Required, string) We support grouping actions in the scenario of escalations or different types of alert instances. If you don't need this, feel free to use `default` as a value. + (Required, string) Grouping actions is recommended for escalations for different types of alert instances. If you don't need this, set the value to `default`. `id`::: - (Required, string) The id of the action saved object to execute. + (Required, string) The ID of the action that saved object executes. `actionTypeId`::: (Required, string) The id of the <>. `params`::: - (Required, object) The map to the `params` the <> will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. + (Required, object) The map to the `params` that the <> will receive. `params` are handled as Mustache templates and passed a default set of context. ===== From 37a3db3f6dd4ea49bc1072ffb34607238b2e326c Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Thu, 18 Feb 2021 12:22:57 -0800 Subject: [PATCH 61/61] fixed due to comments --- docs/api/alerts.asciidoc | 6 ++---- docs/api/alerts/create.asciidoc | 13 ++++++++++++- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc index 42a8ebd0b6a84..a19c538bcb4d7 100644 --- a/docs/api/alerts.asciidoc +++ b/docs/api/alerts.asciidoc @@ -19,14 +19,12 @@ The following APIs are available for managing {kib} alerts. * <> to disable a single alert by ID -* <> to mute all alert instances for a single alert by ID - * <> to mute alert instances for a single alert by ID -* <> to unmute all alert instances for a single alert by ID - * <> to unmute alert instances for a single alert by ID +* <> to unmute all alert instances for a single alert by ID + * <> to retrieve the health of the alerts framework include::alerts/create.asciidoc[] diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc index 80db795760aa1..c33d80f20fe71 100644 --- a/docs/api/alerts/create.asciidoc +++ b/docs/api/alerts/create.asciidoc @@ -24,7 +24,18 @@ Create {kib} alerts. (Required, string) The ID of the alert type that you want to call when the alert is scheduled to run. `schedule`:: - (Required, object) When to run this alert. Use one of the available schedule formats. + (Required, object) The schedule specifying when this alert should be run, using one of the available schedule formats specified under ++ +._Schedule Formats_. +[%collapsible%open] +===== +A schedule is structured such that the key specifies the format you wish to use and its value specifies the schedule. + +We currently support the _Interval format_ which specifies the interval in seconds, minutes, hours or days at which the alert should execute. +Example: `{ interval: "10s" }`, `{ interval: "5m" }`, `{ interval: "1h" }`, `{ interval: "1d" }`. + +There are plans to support multiple other schedule formats in the near future. +===== `throttle`:: (Optional, string) How often this alert should fire the same actions. This will prevent the alert from sending out the same notification over and over. For example, if an alert with a `schedule` of 1 minute stays in a triggered state for 90 minutes, setting a `throttle` of `10m` or `1h` will prevent it from sending 90 notifications during this period.