-
Notifications
You must be signed in to change notification settings - Fork 8.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch '7.x' into backport/7.x/pr-90600
- Loading branch information
Showing
547 changed files
with
20,219 additions
and
7,452 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| [[alerts-api]] | ||
| == Alerts APIs | ||
|
|
||
| The following APIs are available for managing {kib} alerts. | ||
|
|
||
| * <<alerts-api-create, Create alert API>> to create an alert | ||
|
|
||
| * <<alerts-api-update, Update alert API>> to update the attributes for existing alerts | ||
|
|
||
| * <<alerts-api-get, Get object API>> to retrieve a single alert by ID | ||
|
|
||
| * <<alerts-api-delete, Delete alert API>> to permanently remove an alert | ||
|
|
||
| * <<alerts-api-find, Find alerts API>> to retrieve a paginated set of alerts by condition | ||
|
|
||
| * <<alerts-api-list, List all alert types API>> to retrieve a list of all alert types | ||
|
|
||
| * <<alerts-api-enable, Enable alert API>> to enable a single alert by ID | ||
|
|
||
| * <<alerts-api-disable, Disable alert API>> to disable a single alert by ID | ||
|
|
||
| * <<alerts-api-mute, Mute alert instance API>> to mute alert instances for a single alert by ID | ||
|
|
||
| * <<alerts-api-unmute, Unmute alert instance API>> to unmute alert instances for a single alert by ID | ||
|
|
||
| * <<alerts-api-unmute-all, Unmute all alert instances API>> to unmute all alert instances for a single alert by ID | ||
|
|
||
| * <<alerts-api-health, Get framework health API>> to retrieve the health of the alerts framework | ||
|
|
||
| include::alerts/create.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_all.asciidoc[] | ||
| include::alerts/mute.asciidoc[] | ||
| include::alerts/unmute_all.asciidoc[] | ||
| include::alerts/unmute.asciidoc[] | ||
| include::alerts/health.asciidoc[] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,189 @@ | ||
| [[alerts-api-create]] | ||
| === Create alert API | ||
| ++++ | ||
| <titleabbrev>Create alert</titleabbrev> | ||
| ++++ | ||
|
|
||
| Create {kib} alerts. | ||
|
|
||
| [[alerts-api-create-request]] | ||
| ==== Request | ||
|
|
||
| `POST <kibana host>:<port>/api/alerts/alert` | ||
|
|
||
| [[alerts-api-create-request-body]] | ||
| ==== Request body | ||
|
|
||
| `name`:: | ||
| (Required, string) A name to reference and search. | ||
|
|
||
| `tags`:: | ||
| (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. | ||
|
|
||
| `schedule`:: | ||
| (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. | ||
|
|
||
| `notifyWhen`:: | ||
| (Required, string) The condition for throttling the notification: `onActionGroupChange`, `onActiveAlert`, or `onThrottleInterval`. | ||
|
|
||
| `enabled`:: | ||
| (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. 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. | ||
|
|
||
| `actions`:: | ||
| (Optional, object array) An array of the following action objects. | ||
| + | ||
| .Properties of the action objects: | ||
| [%collapsible%open] | ||
| ===== | ||
| `group`::: | ||
| (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. | ||
| `actionTypeId`::: | ||
| (Required, string) The ID of the <<action-types,action type>>. | ||
| `params`::: | ||
| (Required, object) The map to the `params` that the <<action-types,action type>> will receive. ` params` are handled as Mustache templates and passed a default set of context. | ||
| ===== | ||
|
|
||
|
|
||
| [[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" | ||
| } | ||
| } | ||
| -------------------------------------------------- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| [[alerts-api-delete]] | ||
| === Delete alert API | ||
| ++++ | ||
| <titleabbrev>Delete alert</titleabbrev> | ||
| ++++ | ||
|
|
||
| Permanently remove an alert. | ||
|
|
||
| WARNING: Once you delete an alert, you cannot recover it. | ||
|
|
||
| [[alerts-api-delete-request]] | ||
| ==== Request | ||
|
|
||
| `DELETE <kibana host>:<port>/api/alerts/alert/<id>` | ||
|
|
||
| [[alerts-api-delete-path-params]] | ||
| ==== Path parameters | ||
|
|
||
| `id`:: | ||
| (Required, string) The ID of the alert 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 |
Oops, something went wrong.