mirror of
https://github.com/elastic/kibana.git
synced 2025-04-24 01:38:56 -04:00
[Alerts][Docs] Added API documentation for alerts plugin (#91067)
* Added API documentation for alerts plugin * Added link to user api * fixed links * Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/create.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/delete.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/delete.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/disable.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/enable.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/disable.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/update.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/enable.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/find.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/find.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/find.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/find.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/find.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/find.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/get.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/get.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/health.asciidoc Co-authored-by: Gidi Meir Morris <github@gidi.io> * Update docs/api/alerts/health.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/health.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/health.asciidoc Co-authored-by: Gidi Meir Morris <github@gidi.io> * Update docs/api/alerts/health.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/health.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/health.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/list.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/health.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/health.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/list.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/list.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/api/alerts/list.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * fixed due to comments * fixed due to comments * fixed due to comments * fixed links * Apply suggestions from code review Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * fixed due to comments Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> Co-authored-by: Gidi Meir Morris <github@gidi.io>
This commit is contained in:
Yuliia Naumenko
GitHub
parent
863a2d06a4
commit
da25d2753b
15 changed files with 1011 additions and 0 deletions
42
docs/api/alerts.asciidoc
Normal file
42
docs/api/alerts.asciidoc
Normal file
|
|
@ -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[]
|
||||
189
docs/api/alerts/create.asciidoc
Normal file
189
docs/api/alerts/create.asciidoc
Normal file
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
36
docs/api/alerts/delete.asciidoc
Normal file
36
docs/api/alerts/delete.asciidoc
Normal file
|
|
@ -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
|
||||
34
docs/api/alerts/disable.asciidoc
Normal file
34
docs/api/alerts/disable.asciidoc
Normal file
|
|
@ -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
|
||||
34
docs/api/alerts/enable.asciidoc
Normal file
34
docs/api/alerts/enable.asciidoc
Normal file
|
|
@ -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
|
||||
117
docs/api/alerts/find.asciidoc
Normal file
117
docs/api/alerts/find.asciidoc
Normal file
|
|
@ -0,0 +1,117 @@
|
|||
[[alerts-api-find]]
|
||||
=== Find alerts API
|
||||
++++
|
||||
<titleabbrev>Find alerts</titleabbrev>
|
||||
++++
|
||||
|
||||
Retrieve a paginated set of alerts based on condition.
|
||||
|
||||
[[alerts-api-find-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/alerts/_find`
|
||||
|
||||
[[alerts-api-find-query-params]]
|
||||
==== Query Parameters
|
||||
|
||||
`per_page`::
|
||||
(Optional, number) The number of alerts to return per page.
|
||||
|
||||
`page`::
|
||||
(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.
|
||||
|
||||
`default_search_operator`::
|
||||
(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.
|
||||
|
||||
`fields`::
|
||||
(Optional, array|string) The fields to return in the `attributes` key of the response.
|
||||
|
||||
`sort_field`::
|
||||
(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`.
|
||||
|
||||
`has_reference`::
|
||||
(Optional, object) Filters the alerts that have a relations with the reference objects with the specific "type" and "ID".
|
||||
|
||||
`filter`::
|
||||
(Optional, string) A <<kuery-query, 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, 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.
|
||||
|
||||
[[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
|
||||
70
docs/api/alerts/get.asciidoc
Normal file
70
docs/api/alerts/get.asciidoc
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
[[alerts-api-get]]
|
||||
=== Get alert API
|
||||
++++
|
||||
<titleabbrev>Get alert</titleabbrev>
|
||||
++++
|
||||
|
||||
Retrieve an alert by ID.
|
||||
|
||||
[[alerts-api-get-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/alerts/alert/<id>`
|
||||
|
||||
[[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 ID `41893910-6bca-11eb-9e0d-85d233e3ee35`:
|
||||
|
||||
[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"
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
85
docs/api/alerts/health.asciidoc
Normal file
85
docs/api/alerts/health.asciidoc
Normal file
|
|
@ -0,0 +1,85 @@
|
|||
[[alerts-api-health]]
|
||||
=== Get Alerting framework health API
|
||||
++++
|
||||
<titleabbrev>Get Alerting framework health</titleabbrev>
|
||||
++++
|
||||
|
||||
Retrieve the health status of the Alerting framework.
|
||||
|
||||
[[alerts-api-health-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/api/alerts/_health`
|
||||
|
||||
[[alerts-api-health-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
[[alerts-api-health-example]]
|
||||
==== Example
|
||||
|
||||
Retrieve the health status of the Alerting framework:
|
||||
|
||||
[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"
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
The health API response contains the following properties:
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
|
||||
| `isSufficientlySecure`
|
||||
| Returns `false` if security is enabled, but TLS is not.
|
||||
|
||||
| `hasPermanentEncryptionKey`
|
||||
| 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`.
|
||||
|
||||
|===
|
||||
|
||||
`alertingFrameworkHeath` consists of the following properties:
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
|
||||
| `decryptionHealth`
|
||||
| Returns the timestamp and status of the alert decryption: `ok`, `warn` or `error` .
|
||||
|
||||
| `executionHealth`
|
||||
| Returns the timestamp and status of the alert execution: `ok`, `warn` or `error`.
|
||||
|
||||
| `readHealth`
|
||||
| Returns the timestamp and status of the alert reading events: `ok`, `warn` or `error`.
|
||||
|
||||
|===
|
||||
127
docs/api/alerts/list.asciidoc
Normal file
127
docs/api/alerts/list.asciidoc
Normal file
|
|
@ -0,0 +1,127 @@
|
|||
[[alerts-api-list]]
|
||||
=== List alert types API
|
||||
++++
|
||||
<titleabbrev>List all alert types API</titleabbrev>
|
||||
++++
|
||||
|
||||
Retrieve a list of all alert types.
|
||||
|
||||
[[alerts-api-list-request]]
|
||||
==== Request
|
||||
|
||||
`GET <kibana host>:<port>/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 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 based on the license.
|
||||
|
||||
| `actionGroups`
|
||||
| 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. Do not specify this action group under the `actionGroups` property. If `recoveryActionGroup` is not specified, the default `recovered` action group is used.
|
||||
|
||||
| `defaultActionGroupId`
|
||||
| The default ID for the alert type group.
|
||||
|
||||
| `actionVariables`
|
||||
| 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.
|
||||
|
||||
| `authorizedConsumers`
|
||||
| The list of the plugins IDs that have access to the alert type.
|
||||
|
||||
|===
|
||||
37
docs/api/alerts/mute.asciidoc
Normal file
37
docs/api/alerts/mute.asciidoc
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
[[alerts-api-mute]]
|
||||
=== Mute alert instance API
|
||||
++++
|
||||
<titleabbrev>Mute alert instance</titleabbrev>
|
||||
++++
|
||||
|
||||
Mute an alert instance.
|
||||
|
||||
[[alerts-api-mute-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/alerts/alert/<id>/alert_instance/<alert_instance_id>/_mute`
|
||||
|
||||
[[alerts-api-mute-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the alert whose instance you want to mute.
|
||||
|
||||
`alert_instance_id`::
|
||||
(Required, string) The ID of the alert instance 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
|
||||
34
docs/api/alerts/mute_all.asciidoc
Normal file
34
docs/api/alerts/mute_all.asciidoc
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
[[alerts-api-mute-all]]
|
||||
=== Mute all alert instances API
|
||||
++++
|
||||
<titleabbrev>Mute all alert instances</titleabbrev>
|
||||
++++
|
||||
|
||||
Mute all alert instances.
|
||||
|
||||
[[alerts-api-mute-all-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/alerts/alert/<id>/_mute_all`
|
||||
|
||||
[[alerts-api-mute-all-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the alert whose instances you want to mute.
|
||||
|
||||
[[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
|
||||
37
docs/api/alerts/unmute.asciidoc
Normal file
37
docs/api/alerts/unmute.asciidoc
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
[[alerts-api-unmute]]
|
||||
=== Unmute alert instance API
|
||||
++++
|
||||
<titleabbrev>Unmute alert instance</titleabbrev>
|
||||
++++
|
||||
|
||||
Unmute an alert instance.
|
||||
|
||||
[[alerts-api-unmute-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/alerts/alert/<id>/alert_instance/<alert_instance_id>/_unmute`
|
||||
|
||||
[[alerts-api-unmute-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the alert whose instance you want to mute..
|
||||
|
||||
`alert_instance_id`::
|
||||
(Required, string) The ID of the alert instance 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
|
||||
34
docs/api/alerts/unmute_all.asciidoc
Normal file
34
docs/api/alerts/unmute_all.asciidoc
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
[[alerts-api-unmute-all]]
|
||||
=== Unmute all alert instances API
|
||||
++++
|
||||
<titleabbrev>Unmute all alert instances</titleabbrev>
|
||||
++++
|
||||
|
||||
Unmute all alert instances.
|
||||
|
||||
[[alerts-api-unmute-all-request]]
|
||||
==== Request
|
||||
|
||||
`POST <kibana host>:<port>/api/alerts/alert/<id>/_unmute_all`
|
||||
|
||||
[[alerts-api-unmute-all-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the alert whose instances you want to unmute.
|
||||
|
||||
[[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
|
||||
134
docs/api/alerts/update.asciidoc
Normal file
134
docs/api/alerts/update.asciidoc
Normal file
|
|
@ -0,0 +1,134 @@
|
|||
[[alerts-api-update]]
|
||||
=== Update alert API
|
||||
++++
|
||||
<titleabbrev>Update alert</titleabbrev>
|
||||
++++
|
||||
|
||||
Update the attributes for an existing alert.
|
||||
|
||||
[[alerts-api-update-request]]
|
||||
==== Request
|
||||
|
||||
`PUT <kibana host>:<port>/api/alerts/alert/<id>`
|
||||
|
||||
[[alerts-api-update-path-params]]
|
||||
==== Path parameters
|
||||
|
||||
`id`::
|
||||
(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.
|
||||
|
||||
`tags`::
|
||||
(Optional, string array) A list of keywords to reference and search.
|
||||
|
||||
`schedule`::
|
||||
(Required, object) When to run this alert. Use one of the available schedule formats.
|
||||
+
|
||||
._Schedule Formats_.
|
||||
[%collapsible%open]
|
||||
=====
|
||||
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.
|
||||
|
||||
Example: `{ interval: "10s" }`, `{ interval: "5m" }`, `{ interval: "1h" }`, `{ interval: "1d" }`.
|
||||
|
||||
=====
|
||||
|
||||
`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`.
|
||||
|
||||
`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 the value to `default`.
|
||||
|
||||
`id`:::
|
||||
(Required, string) The ID of the action that saved object executes.
|
||||
|
||||
`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-update-errors-codes]]
|
||||
==== Response code
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
|
||||
[[alerts-api-update-example]]
|
||||
==== Example
|
||||
|
||||
Update an 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"
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
@ -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/actions-and-connectors.asciidoc[]
|
||||
include::{kib-repo-dir}/api/dashboard-api.asciidoc[]
|
||||
include::{kib-repo-dir}/api/logstash-configuration-management.asciidoc[]
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue