Skip to content

Commit

Permalink
Merge branch 'master' into long-text-overflow-issue
Browse files Browse the repository at this point in the history
  • Loading branch information
kibanamachine authored Feb 19, 2021
2 parents a835480 + 4d34a13 commit 7f45723
Show file tree
Hide file tree
Showing 91 changed files with 3,084 additions and 1,400 deletions.
42 changes: 42 additions & 0 deletions docs/api/alerts.asciidoc
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[]
189 changes: 189 additions & 0 deletions docs/api/alerts/create.asciidoc
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"
}
}
--------------------------------------------------
36 changes: 36 additions & 0 deletions docs/api/alerts/delete.asciidoc
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
34 changes: 34 additions & 0 deletions docs/api/alerts/disable.asciidoc
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
34 changes: 34 additions & 0 deletions docs/api/alerts/enable.asciidoc
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
Loading

0 comments on commit 7f45723

Please sign in to comment.