-
Notifications
You must be signed in to change notification settings - Fork 8.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[Alerts][Docs] Added API documentation for alerts plugin #91067
Merged
Merged
Changes from 61 commits
Commits
Show all changes
64 commits
Select commit
Hold shift + click to select a range
f6a930f
Added API documentation for alerts plugin
YulNaumenko d448d6f
Added link to user api
YulNaumenko 4207b22
fixed links
YulNaumenko 2a151ea
Update docs/api/alerts.asciidoc
YulNaumenko aa5bc09
Update docs/api/alerts.asciidoc
YulNaumenko 6008f3c
Update docs/api/alerts.asciidoc
YulNaumenko 7fbb677
Update docs/api/alerts.asciidoc
YulNaumenko b6beab2
Update docs/api/alerts.asciidoc
YulNaumenko 144711f
Update docs/api/alerts.asciidoc
YulNaumenko fc74e9a
Update docs/api/alerts.asciidoc
YulNaumenko 230c277
Update docs/api/alerts.asciidoc
YulNaumenko 3cf383e
Update docs/api/alerts.asciidoc
YulNaumenko 9f00273
Update docs/api/alerts.asciidoc
YulNaumenko 95124b3
Update docs/api/alerts.asciidoc
YulNaumenko 5d73cd2
Update docs/api/alerts.asciidoc
YulNaumenko 5b6f2f3
Update docs/api/alerts.asciidoc
YulNaumenko d79e6e4
Update docs/api/alerts/create.asciidoc
YulNaumenko 677b024
Update docs/api/alerts/create.asciidoc
YulNaumenko f3a7208
Update docs/api/alerts/create.asciidoc
YulNaumenko 7b3d155
Update docs/api/alerts/create.asciidoc
YulNaumenko cd64b9d
Update docs/api/alerts/create.asciidoc
YulNaumenko 058624b
Update docs/api/alerts/create.asciidoc
YulNaumenko 46a5a8d
Update docs/api/alerts/create.asciidoc
YulNaumenko b563b8a
Update docs/api/alerts/create.asciidoc
YulNaumenko e6be6e8
Update docs/api/alerts/create.asciidoc
YulNaumenko f96abc3
Update docs/api/alerts/create.asciidoc
YulNaumenko f98c3c9
Update docs/api/alerts/delete.asciidoc
YulNaumenko ef16edf
Update docs/api/alerts/delete.asciidoc
YulNaumenko 9617bc3
Update docs/api/alerts/disable.asciidoc
YulNaumenko ff6ce3c
Update docs/api/alerts/enable.asciidoc
YulNaumenko e6d837c
Update docs/api/alerts/disable.asciidoc
YulNaumenko 1d1c1d7
Update docs/api/alerts/update.asciidoc
YulNaumenko 9bf66e3
Update docs/api/alerts/enable.asciidoc
YulNaumenko 4fb804a
Update docs/api/alerts/find.asciidoc
YulNaumenko 96c7017
Update docs/api/alerts/find.asciidoc
YulNaumenko 3bec3bb
Update docs/api/alerts/find.asciidoc
YulNaumenko e180a34
Update docs/api/alerts/find.asciidoc
YulNaumenko 62cce42
Update docs/api/alerts/find.asciidoc
YulNaumenko 0dd56d9
Update docs/api/alerts/find.asciidoc
YulNaumenko 3730bab
Update docs/api/alerts/get.asciidoc
YulNaumenko 01a1585
Update docs/api/alerts/get.asciidoc
YulNaumenko f5a83bb
Update docs/api/alerts/health.asciidoc
YulNaumenko 599a0e1
Update docs/api/alerts/health.asciidoc
YulNaumenko a63072e
Update docs/api/alerts/health.asciidoc
YulNaumenko 825e926
Update docs/api/alerts/health.asciidoc
YulNaumenko e61d6c4
Update docs/api/alerts/health.asciidoc
YulNaumenko a890877
Update docs/api/alerts/health.asciidoc
YulNaumenko 474c6b1
Update docs/api/alerts/health.asciidoc
YulNaumenko 14d90de
Update docs/api/alerts/list.asciidoc
YulNaumenko 273e1ec
Update docs/api/alerts/health.asciidoc
YulNaumenko 4bb7965
Update docs/api/alerts/health.asciidoc
YulNaumenko 826df7d
Update docs/api/alerts/list.asciidoc
YulNaumenko 866aacb
Update docs/api/alerts/list.asciidoc
YulNaumenko 379e46e
Update docs/api/alerts/list.asciidoc
YulNaumenko 32400f8
Apply suggestions from code review
YulNaumenko 698993e
fixed due to comments
YulNaumenko 31affae
fixed merge
YulNaumenko 526d5df
fixed due to comments
YulNaumenko 51b2ab1
fixed due to comments
YulNaumenko 8fdb2c5
Merge remote-tracking branch upstream/master
YulNaumenko ba03d92
fixed links
YulNaumenko e49aeea
Apply suggestions from code review
YulNaumenko 37a3db3
fixed due to comments
YulNaumenko 0f8b92b
merged
YulNaumenko File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,44 @@ | ||
[[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-all, Mute all alert instances API>> to mute all alert instances for 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-all, Unmute all alert instances API>> to unmute all 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-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,178 @@ | ||
[[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) When to run this alert. Use one of the available schedule formats. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Add some context here, like in Update alert. |
||
|
||
`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) 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. | ||
YulNaumenko marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
`id`::: | ||
(Required, string) The id of the action saved object to execute. | ||
YulNaumenko marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
`actionTypeId`::: | ||
(Required, string) The id of the <<action-types,action type>>. | ||
YulNaumenko marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
`params`::: | ||
(Required, object) The map to the `params` the <<action-types,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. | ||
YulNaumenko marked this conversation as resolved.
Show resolved
Hide resolved
|
||
===== | ||
|
||
|
||
YulNaumenko marked this conversation as resolved.
Show resolved
Hide resolved
|
||
[[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 |
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,34 @@ | ||
[[alerts-api-disable]] | ||
=== Disable alert API | ||
++++ | ||
<titleabbrev>Disable alert</titleabbrev> | ||
++++ | ||
|
||
Disable an alert. | ||
|
||
[[alerts-api-disable-request]] | ||
==== Request | ||
|
||
`POST <kibana host>:<port>/api/alerts/alert/<id>/_disable` | ||
|
||
[[alerts-api-disable-path-params]] | ||
==== Path parameters | ||
|
||
`id`:: | ||
(Required, string) The ID of the alert 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 |
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,34 @@ | ||
[[alerts-api-enable]] | ||
=== Enable alert API | ||
++++ | ||
<titleabbrev>Enable alert</titleabbrev> | ||
++++ | ||
|
||
Enable an alert. | ||
|
||
[[alerts-api-enable-request]] | ||
==== Request | ||
|
||
`POST <kibana host>:<port>/api/alerts/alert/<id>/_enable` | ||
|
||
[[alerts-api-enable-path-params]] | ||
==== Path parameters | ||
|
||
`id`:: | ||
(Required, string) The ID of the alert 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 |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggest putting "Mute single" before "Mute all". Same with Unmute.