Skip to content

Commit 7f45723

Browse files
kibanamachinekibanamachine
authored
Merge branch 'master' into long-text-overflow-issue
2 parents a835480 + 4d34a13 commit 7f45723

File tree

91 files changed

+3084
-1400
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

91 files changed

+3084
-1400
lines changed

‎docs/api/alerts.asciidoc‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
[[alerts-api]]
2+
== Alerts APIs
3+
4+
The following APIs are available for managing {kib} alerts.
5+
6+
* <<alerts-api-create, Create alert API>> to create an alert
7+
8+
* <<alerts-api-update, Update alert API>> to update the attributes for existing alerts
9+
10+
* <<alerts-api-get, Get object API>> to retrieve a single alert by ID
11+
12+
* <<alerts-api-delete, Delete alert API>> to permanently remove an alert
13+
14+
* <<alerts-api-find, Find alerts API>> to retrieve a paginated set of alerts by condition
15+
16+
* <<alerts-api-list, List all alert types API>> to retrieve a list of all alert types
17+
18+
* <<alerts-api-enable, Enable alert API>> to enable a single alert by ID
19+
20+
* <<alerts-api-disable, Disable alert API>> to disable a single alert by ID
21+
22+
* <<alerts-api-mute, Mute alert instance API>> to mute alert instances for a single alert by ID
23+
24+
* <<alerts-api-unmute, Unmute alert instance API>> to unmute alert instances for a single alert by ID
25+
26+
* <<alerts-api-unmute-all, Unmute all alert instances API>> to unmute all alert instances for a single alert by ID
27+
28+
* <<alerts-api-health, Get framework health API>> to retrieve the health of the alerts framework
29+
30+
include::alerts/create.asciidoc[]
31+
include::alerts/update.asciidoc[]
32+
include::alerts/get.asciidoc[]
33+
include::alerts/delete.asciidoc[]
34+
include::alerts/find.asciidoc[]
35+
include::alerts/list.asciidoc[]
36+
include::alerts/enable.asciidoc[]
37+
include::alerts/disable.asciidoc[]
38+
include::alerts/mute_all.asciidoc[]
39+
include::alerts/mute.asciidoc[]
40+
include::alerts/unmute_all.asciidoc[]
41+
include::alerts/unmute.asciidoc[]
42+
include::alerts/health.asciidoc[]

‎docs/api/alerts/create.asciidoc‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
[[alerts-api-create]]
2+
=== Create alert API
3+
++++
4+
<titleabbrev>Create alert</titleabbrev>
5+
++++
6+
7+
Create {kib} alerts.
8+
9+
[[alerts-api-create-request]]
10+
==== Request
11+
12+
`POST <kibana host>:<port>/api/alerts/alert`
13+
14+
[[alerts-api-create-request-body]]
15+
==== Request body
16+
17+
`name`::
18+
(Required, string) A name to reference and search.
19+
20+
`tags`::
21+
(Optional, string array) A list of keywords to reference and search.
22+
23+
`alertTypeId`::
24+
(Required, string) The ID of the alert type that you want to call when the alert is scheduled to run.
25+
26+
`schedule`::
27+
(Required, object) The schedule specifying when this alert should be run, using one of the available schedule formats specified under
28+
+
29+
._Schedule Formats_.
30+
[%collapsible%open]
31+
=====
32+
A schedule is structured such that the key specifies the format you wish to use and its value specifies the schedule.
33+
34+
We currently support the _Interval format_ which specifies the interval in seconds, minutes, hours or days at which the alert should execute.
35+
Example: `{ interval: "10s" }`, `{ interval: "5m" }`, `{ interval: "1h" }`, `{ interval: "1d" }`.
36+
37+
There are plans to support multiple other schedule formats in the near future.
38+
=====
39+
40+
`throttle`::
41+
(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.
42+
43+
`notifyWhen`::
44+
(Required, string) The condition for throttling the notification: `onActionGroupChange`, `onActiveAlert`, or `onThrottleInterval`.
45+
46+
`enabled`::
47+
(Optional, boolean) Indicates if you want to run the alert on an interval basis after it is created.
48+
49+
`consumer`::
50+
(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.
51+
52+
`params`::
53+
(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.
54+
55+
`actions`::
56+
(Optional, object array) An array of the following action objects.
57+
+
58+
.Properties of the action objects:
59+
[%collapsible%open]
60+
=====
61+
`group`:::
62+
(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`.
63+
64+
`id`:::
65+
(Required, string) The ID of the action saved object to execute.
66+
67+
`actionTypeId`:::
68+
(Required, string) The ID of the <<action-types,action type>>.
69+
70+
`params`:::
71+
(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.
72+
=====
73+
74+
75+
[[alerts-api-create-request-codes]]
76+
==== Response code
77+
78+
`200`::
79+
Indicates a successful call.
80+
81+
[[alerts-api-create-example]]
82+
==== Example
83+
84+
[source,sh]
85+
--------------------------------------------------
86+
$ curl -X POST api/alerts/alert -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
87+
{
88+
"params":{
89+
"aggType":"avg",
90+
"termSize":6,
91+
"thresholdComparator":">",
92+
"timeWindowSize":5,
93+
"timeWindowUnit":"m",
94+
"groupBy":"top",
95+
"threshold":[
96+
1000
97+
],
98+
"index":[
99+
".test-index"
100+
],
101+
"timeField":"@timestamp",
102+
"aggField":"sheet.version",
103+
"termField":"name.keyword"
104+
},
105+
"consumer":"alerts",
106+
"alertTypeId":".index-threshold",
107+
"schedule":{
108+
"interval":"1m"
109+
},
110+
"actions":[
111+
{
112+
"id":"dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2",
113+
"actionTypeId":".server-log",
114+
"group":"threshold met",
115+
"params":{
116+
"level":"info",
117+
"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}}"
118+
}
119+
}
120+
],
121+
"tags":[
122+
"cpu"
123+
],
124+
"notifyWhen":"onActionGroupChange",
125+
"name":"my alert"
126+
}'
127+
--------------------------------------------------
128+
// KIBANA
129+
130+
The API returns the following:
131+
132+
[source,sh]
133+
--------------------------------------------------
134+
{
135+
"id": "41893910-6bca-11eb-9e0d-85d233e3ee35",
136+
"notifyWhen": "onActionGroupChange",
137+
"params": {
138+
"aggType": "avg",
139+
"termSize": 6,
140+
"thresholdComparator": ">",
141+
"timeWindowSize": 5,
142+
"timeWindowUnit": "m",
143+
"groupBy": "top",
144+
"threshold": [
145+
1000
146+
],
147+
"index": [
148+
".kibana"
149+
],
150+
"timeField": "@timestamp",
151+
"aggField": "sheet.version",
152+
"termField": "name.keyword"
153+
},
154+
"consumer": "alerts",
155+
"alertTypeId": ".index-threshold",
156+
"schedule": {
157+
"interval": "1m"
158+
},
159+
"actions": [
160+
{
161+
"actionTypeId": ".server-log",
162+
"group": "threshold met",
163+
"params": {
164+
"level": "info",
165+
"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}}"
166+
},
167+
"id": "dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2"
168+
}
169+
],
170+
"tags": [
171+
"cpu"
172+
],
173+
"name": "my alert",
174+
"enabled": true,
175+
"throttle": null,
176+
"apiKeyOwner": "elastic",
177+
"createdBy": "elastic",
178+
"updatedBy": "elastic",
179+
"muteAll": false,
180+
"mutedInstanceIds": [],
181+
"updatedAt": "2021-02-10T18:03:19.961Z",
182+
"createdAt": "2021-02-10T18:03:19.961Z",
183+
"scheduledTaskId": "425b0800-6bca-11eb-9e0d-85d233e3ee35",
184+
"executionStatus": {
185+
"lastExecutionDate": "2021-02-10T18:03:19.966Z",
186+
"status": "pending"
187+
}
188+
}
189+
--------------------------------------------------

‎docs/api/alerts/delete.asciidoc‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
[[alerts-api-delete]]
2+
=== Delete alert API
3+
++++
4+
<titleabbrev>Delete alert</titleabbrev>
5+
++++
6+
7+
Permanently remove an alert.
8+
9+
WARNING: Once you delete an alert, you cannot recover it.
10+
11+
[[alerts-api-delete-request]]
12+
==== Request
13+
14+
`DELETE <kibana host>:<port>/api/alerts/alert/<id>`
15+
16+
[[alerts-api-delete-path-params]]
17+
==== Path parameters
18+
19+
`id`::
20+
(Required, string) The ID of the alert that you want to remove.
21+
22+
[[alerts-api-delete-response-codes]]
23+
==== Response code
24+
25+
`200`::
26+
Indicates a successful call.
27+
28+
==== Example
29+
30+
Delete an alert with ID:
31+
32+
[source,sh]
33+
--------------------------------------------------
34+
$ curl -X DELETE api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35
35+
--------------------------------------------------
36+
// KIBANA

‎docs/api/alerts/disable.asciidoc‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
[[alerts-api-disable]]
2+
=== Disable alert API
3+
++++
4+
<titleabbrev>Disable alert</titleabbrev>
5+
++++
6+
7+
Disable an alert.
8+
9+
[[alerts-api-disable-request]]
10+
==== Request
11+
12+
`POST <kibana host>:<port>/api/alerts/alert/<id>/_disable`
13+
14+
[[alerts-api-disable-path-params]]
15+
==== Path parameters
16+
17+
`id`::
18+
(Required, string) The ID of the alert that you want to disable.
19+
20+
[[alerts-api-disable-response-codes]]
21+
==== Response code
22+
23+
`200`::
24+
Indicates a successful call.
25+
26+
==== Example
27+
28+
Disable an alert with ID:
29+
30+
[source,sh]
31+
--------------------------------------------------
32+
$ curl -X POST api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35/_disable
33+
--------------------------------------------------
34+
// KIBANA

‎docs/api/alerts/enable.asciidoc‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
[[alerts-api-enable]]
2+
=== Enable alert API
3+
++++
4+
<titleabbrev>Enable alert</titleabbrev>
5+
++++
6+
7+
Enable an alert.
8+
9+
[[alerts-api-enable-request]]
10+
==== Request
11+
12+
`POST <kibana host>:<port>/api/alerts/alert/<id>/_enable`
13+
14+
[[alerts-api-enable-path-params]]
15+
==== Path parameters
16+
17+
`id`::
18+
(Required, string) The ID of the alert that you want to enable.
19+
20+
[[alerts-api-enable-response-codes]]
21+
==== Response code
22+
23+
`200`::
24+
Indicates a successful call.
25+
26+
==== Example
27+
28+
Enable an alert with ID:
29+
30+
[source,sh]
31+
--------------------------------------------------
32+
$ curl -X POST api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35/_enable
33+
--------------------------------------------------
34+
// KIBANA

0 commit comments

Comments
 (0)