[Alerts][Docs] Added API documentation for alerts plugin (elastic#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>
YulNaumenko · Feb 23, 2021 · 419b2b7 · 419b2b7
1 parent 04b071b
commit 419b2b7
Show file tree

Hide file tree

Showing 15 changed files with 1,011 additions and 0 deletions.
diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc
@@ -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[]
diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc
@@ -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"
+  }
+}
+--------------------------------------------------
diff --git a/docs/api/alerts/delete.asciidoc b/docs/api/alerts/delete.asciidoc
@@ -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
diff --git a/docs/api/alerts/disable.asciidoc b/docs/api/alerts/disable.asciidoc
@@ -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
diff --git a/docs/api/alerts/enable.asciidoc b/docs/api/alerts/enable.asciidoc
@@ -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