mirror of
https://github.com/elastic/kibana.git
synced 2025-04-23 17:28:26 -04:00
[DOCS] Add prerequisites to get rule, find rule, get rule health APIs (#134865)
This commit is contained in:
Lisa Cawley
GitHub
parent
16c2c717f1
commit
81e8208258
7 changed files with 157 additions and 119 deletions
|
|
@ -33,9 +33,10 @@ For deprecated APIs, refer to <<alerts-api>>.
|
|||
|
||||
include::alerting/create_rule.asciidoc[leveloffset=+1]
|
||||
include::alerting/delete_rule.asciidoc[leveloffset=+1]
|
||||
include::alerting/find_rules.asciidoc[leveloffset=+1]
|
||||
include::alerting/health.asciidoc[leveloffset=+1]
|
||||
include::alerting/get_rules.asciidoc[leveloffset=+1]
|
||||
include::alerting/update_rule.asciidoc[leveloffset=+1]
|
||||
include::alerting/get_rules.asciidoc[]
|
||||
include::alerting/find_rules.asciidoc[]
|
||||
include::alerting/list_rule_types.asciidoc[]
|
||||
include::alerting/enable_rule.asciidoc[]
|
||||
include::alerting/disable_rule.asciidoc[]
|
||||
|
|
@ -43,5 +44,4 @@ include::alerting/mute_all_alerts.asciidoc[]
|
|||
include::alerting/mute_alert.asciidoc[]
|
||||
include::alerting/unmute_all_alerts.asciidoc[]
|
||||
include::alerting/unmute_alert.asciidoc[]
|
||||
include::alerting/health.asciidoc[]
|
||||
include::alerting/legacy/index.asciidoc[]
|
||||
|
|
|
|||
|
|
@ -16,10 +16,11 @@ Create {kib} rules.
|
|||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `all` privileges for the *Management* > *Stack Rules* feature or
|
||||
for the *{ml-app}*, *{observability}*, or *Security* features, depending on the
|
||||
`consumer` and `rule_type_id` of the rule you're creating. If the rule has
|
||||
`actions`, you must also have `read` privileges for the *Management* >
|
||||
You must have `all` privileges for the appropriate {kib} features, depending on
|
||||
the `consumer` and `rule_type_id` of the rules you're creating. For example, the
|
||||
*Management* > *Stack Rules* feature, *Analytics* > *Discover* and *{ml-app}*
|
||||
features, *{observability}*, and *Security* features. If the rule has `actions`,
|
||||
you must also have `read` privileges for the *Management* >
|
||||
*Actions and Connectors* feature. For more details, refer to
|
||||
<<kibana-feature-privileges>>.
|
||||
|
||||
|
|
|
|||
|
|
@ -17,9 +17,11 @@ WARNING: After you delete a rule, you cannot recover it.
|
|||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `all` privileges for the *Management* > *Stack Rules* feature or
|
||||
for the *{ml-app}*, *{observability}*, or *Security* features, depending on the
|
||||
`consumer` and `rule_type_id` of the rule you're deleting.
|
||||
You must have `all` privileges for the appropriate {kib} features, depending on
|
||||
the `consumer` and `rule_type_id` of the rule you're deleting. For example, the
|
||||
*Management* > *Stack Rules* feature, *Analytics* > *Discover* or *{ml-app}*
|
||||
features, *{observability}*, or *Security* features. For more details, refer to
|
||||
<<kibana-feature-privileges>>.
|
||||
|
||||
[[delete-rule-api-path-params]]
|
||||
=== {api-path-parms-title}
|
||||
|
|
|
|||
|
|
@ -1,77 +1,101 @@
|
|||
[[find-rules-api]]
|
||||
=== Find rules API
|
||||
== Find rules API
|
||||
++++
|
||||
<titleabbrev>Find rules</titleabbrev>
|
||||
++++
|
||||
|
||||
Retrieve a paginated set of rules based on condition.
|
||||
|
||||
NOTE: As rules 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.
|
||||
|
||||
[[find-rules-api-request]]
|
||||
==== Request
|
||||
=== {api-request-title}
|
||||
|
||||
`GET <kibana host>:<port>/api/alerting/rules/_find`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/alerting/rules/_find`
|
||||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `read` privileges for the appropriate {kib} features, depending on
|
||||
the `consumer` and `rule_type_id` of the rules you're seeking. For example, the
|
||||
*Management* > *Stack Rules* feature, *Analytics* > *Discover* and *{ml-app}*
|
||||
features, *{observability}*, and *Security* features. To find rules associated
|
||||
with the *{stack-monitor-app}*, use the `monitoring_user` built-in role.
|
||||
|
||||
For more details, refer to <<kibana-feature-privileges>>.
|
||||
|
||||
=== {api-description-title}
|
||||
|
||||
As rules 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.
|
||||
|
||||
NOTE: Rule `params` are stored as a {ref}/flattened.html[flattened field type]
|
||||
and analyzed as keywords.
|
||||
|
||||
[[find-rules-api-path-params]]
|
||||
==== Path parameters
|
||||
=== {api-path-parms-title}
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in
|
||||
the URL, the default space is used.
|
||||
|
||||
[[find-rules-api-query-params]]
|
||||
==== Query Parameters
|
||||
|
||||
NOTE: Rule `params` are stored as a {ref}/flattened.html[flattened field type] and analyzed as keywords.
|
||||
|
||||
`per_page`::
|
||||
(Optional, number) The number of rules 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 rules in the response.
|
||||
=== {api-query-parms-title}
|
||||
|
||||
`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.
|
||||
(Optional, string) The operator to use for the `simple_query_string`. The
|
||||
default is 'OR'.
|
||||
|
||||
`fields`::
|
||||
(Optional, array of strings) The fields to return in the `attributes` key of the response.
|
||||
|
||||
`sort_field`::
|
||||
(Optional, string) Sorts the response. Could be a rule field returned in the `attributes` key of the response.
|
||||
|
||||
`sort_order`::
|
||||
(Optional, string) Sort direction, either `asc` or `desc`.
|
||||
|
||||
`has_reference`::
|
||||
(Optional, object) Filters the rules that have a relation with the reference objects with the specific "type" and "ID".
|
||||
(Optional, array of strings) The fields to return in the `attributes` key of the
|
||||
response.
|
||||
|
||||
`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.
|
||||
(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`.
|
||||
|
||||
`has_reference`::
|
||||
(Optional, object) Filters the rules that have a relation with the reference
|
||||
objects with the specific "type" and "ID".
|
||||
|
||||
`page`::
|
||||
(Optional, number) The page number.
|
||||
|
||||
`per_page`::
|
||||
(Optional, number) The number of rules to return per page.
|
||||
|
||||
`search`::
|
||||
(Optional, string) An {es}
|
||||
{ref}/query-dsl-simple-query-string-query.html[simple_query_string] query that
|
||||
filters the rules in the response.
|
||||
|
||||
`search_fields`::
|
||||
(Optional, array or string) The fields to perform the `simple_query_string`
|
||||
parsed query against.
|
||||
|
||||
`sort_field`::
|
||||
(Optional, string) Sorts the response. Could be a rule field returned in the
|
||||
`attributes` key of the response.
|
||||
|
||||
`sort_order`::
|
||||
(Optional, string) Sort direction, either `asc` or `desc`.
|
||||
|
||||
[[find-rules-api-request-codes]]
|
||||
==== Response code
|
||||
=== {api-response-codes-title}
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
Indicates a successful call.
|
||||
|
||||
==== Examples
|
||||
=== {api-examples-title}
|
||||
|
||||
Find rules with names that start with `my`:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/alerting/rules/_find?search_fields=name&search=my*
|
||||
GET api/alerting/rules/_find?search_fields=name&search=my*
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
|
|
@ -110,18 +134,19 @@ The API returns the following:
|
|||
"scheduled_task_id": "0b092d90-6b62-11eb-9e0d-85d233e3ee35",
|
||||
"execution_status": {
|
||||
"last_execution_date": "2021-02-10T17:55:14.262Z",
|
||||
"status": "ok"
|
||||
"status": "ok",
|
||||
"last_duration": 384
|
||||
}
|
||||
},
|
||||
}
|
||||
]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
For parameters that accept multiple values (e.g. `fields`), repeat the
|
||||
For parameters that accept multiple values (such as `fields`), repeat the
|
||||
query parameter for each value:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/alerting/rules/_find?fields=id&fields=name
|
||||
GET api/alerting/rules/_find?fields=id&fields=name
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
[[get-rule-api]]
|
||||
=== Get rule API
|
||||
== Get rule API
|
||||
++++
|
||||
<titleabbrev>Get rule</titleabbrev>
|
||||
++++
|
||||
|
|
@ -7,35 +7,46 @@
|
|||
Retrieve a rule by ID.
|
||||
|
||||
[[get-rule-api-request]]
|
||||
==== Request
|
||||
=== {api-request-title}
|
||||
|
||||
`GET <kibana host>:<port>/api/alerting/rule/<id>`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/alerting/rule/<id>`
|
||||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `read` privileges for the appropriate {kib} features, depending on
|
||||
the `consumer` and `rule_type_id` of the rules you're seeking. For example, the
|
||||
*Management* > *Stack Rules* feature, *Analytics* > *Discover* and *{ml-app}*
|
||||
features, *{observability}*, and *Security* features. To get rules associated
|
||||
with the *{stack-monitor-app}*, use the `monitoring_user` built-in role.
|
||||
|
||||
For more details, refer to <<kibana-feature-privileges>>.
|
||||
|
||||
[[get-rule-api-params]]
|
||||
==== Path parameters
|
||||
=== {api-path-parms-title}
|
||||
|
||||
`id`::
|
||||
(Required, string) The ID of the rule to retrieve.
|
||||
(Required, string) The identifier of the rule to retrieve.
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in
|
||||
the URL, the default space is used.
|
||||
|
||||
[[get-rule-api-codes]]
|
||||
==== Response code
|
||||
=== {api-response-codes-title}
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
Indicates a successful call.
|
||||
|
||||
[[get-rule-api-example]]
|
||||
==== Example
|
||||
=== {api-examples-title}
|
||||
|
||||
Retrieve the rule object with the ID `41893910-6bca-11eb-9e0d-85d233e3ee35`:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/alerting/rule/41893910-6bca-11eb-9e0d-85d233e3ee35
|
||||
GET api/alerting/rule/41893910-6bca-11eb-9e0d-85d233e3ee35
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
|
|
@ -69,7 +80,8 @@ The API returns the following:
|
|||
"scheduled_task_id": "0b092d90-6b62-11eb-9e0d-85d233e3ee35",
|
||||
"execution_status": {
|
||||
"last_execution_date": "2021-02-10T17:55:14.262Z",
|
||||
"status": "ok"
|
||||
"status": "ok",
|
||||
"last_duration": 359
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -1,38 +1,45 @@
|
|||
[[get-alerting-framework-health-api]]
|
||||
=== Get Alerting framework health API
|
||||
== Get alerting framework health API
|
||||
++++
|
||||
<titleabbrev>Get Alerting framework health</titleabbrev>
|
||||
<titleabbrev>Get alerting framework health</titleabbrev>
|
||||
++++
|
||||
|
||||
Retrieve the health status of the Alerting framework.
|
||||
Retrieve the health status of the alerting framework.
|
||||
|
||||
[[get-alerting-framework-health-api-request]]
|
||||
==== Request
|
||||
=== {api-request-title}
|
||||
|
||||
`GET <kibana host>:<port>/api/alerting/_health`
|
||||
|
||||
`GET <kibana host>:<port>/s/<space_id>/api/alerting/_health`
|
||||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `read` privileges for the *Management* > *Stack Rules* feature or
|
||||
for at least one of the *Analytics* > *Discover*, *Analytics* > *{ml-app}*,
|
||||
*{observability}*, or *Security* features.
|
||||
|
||||
[[get-alerting-framework-health-api-params]]
|
||||
==== Path parameters
|
||||
=== {api-path-parms-title}
|
||||
|
||||
`space_id`::
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
||||
(Optional, string) An identifier for the space. If `space_id` is not provided in
|
||||
the URL, the default space is used.
|
||||
|
||||
[[get-alerting-framework-health-api-codes]]
|
||||
==== Response code
|
||||
=== {api-response-codes-title}
|
||||
|
||||
`200`::
|
||||
Indicates a successful call.
|
||||
Indicates a successful call.
|
||||
|
||||
[[get-alerting-framework-health-api-example]]
|
||||
==== Example
|
||||
=== {api-examples-title}
|
||||
|
||||
Retrieve the health status of the Alerting framework:
|
||||
Retrieve the health status of the alerting framework:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X GET api/alerting/_health
|
||||
GET api/alerting/_health
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
|
|
@ -41,56 +48,46 @@ The API returns the following:
|
|||
[source,sh]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"is_sufficiently_secure":true,
|
||||
"has_permanent_encryption_key":true,
|
||||
"alerting_framework_health":{
|
||||
"is_sufficiently_secure":true, <1>
|
||||
"has_permanent_encryption_key":true, <2>
|
||||
"alerting_framework_health":{ <3>
|
||||
"decryption_health":{
|
||||
"status":"ok",
|
||||
"timestamp":"2021-02-10T23:35:04.949Z"
|
||||
"timestamp":"2022-06-21T21:46:15.023Z"
|
||||
},
|
||||
"execution_health":{
|
||||
"status":"ok",
|
||||
"timestamp":"2021-02-10T23:35:04.949Z"
|
||||
"timestamp":"2022-06-21T21:46:15.023Z"
|
||||
},
|
||||
"read_health":{
|
||||
"status":"ok",
|
||||
"timestamp":"2021-02-10T23:35:04.949Z"
|
||||
"timestamp":"2022-06-21T21:46:15.023Z"
|
||||
}
|
||||
},
|
||||
"alerting_framework_heath":{ <4>
|
||||
"_deprecated":"This state property has a typo, use \"alerting_framework_health\" instead.","decryption_health":{
|
||||
"status":"ok",
|
||||
"timestamp":"2022-06-21T21:46:15.023Z"
|
||||
},
|
||||
"execution_health":{
|
||||
"status":"ok",
|
||||
"timestamp":"2022-06-21T21:46:15.023Z"
|
||||
},
|
||||
"read_health":{
|
||||
"status":"ok",
|
||||
"timestamp":"2022-06-21T21:46:15.023Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
The health API response contains the following properties:
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
|
||||
| `is_sufficiently_secure`
|
||||
| Returns `false` if security is enabled, but TLS is not.
|
||||
|
||||
| `has_permanent_encryption_key`
|
||||
| Return the state `false` if Encrypted Saved Object plugin has not a permanent encryption Key.
|
||||
|
||||
| `alerting_framework_health`
|
||||
| This state property has three substates that identify the health of the alerting framework API: `decryption_health`, `execution_health`, and `read_health`.
|
||||
|
||||
| deprecated::`alerting_framework_heath`
|
||||
| This state property has a typo, use `alerting_framework_health` instead. It has three substates that identify the health of the alerting framework API: `decryption_health`, `execution_health`, and `read_health`.
|
||||
|
||||
|===
|
||||
|
||||
`alerting_framework_health` consists of the following properties:
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
|
||||
| `decryption_health`
|
||||
| Returns the timestamp and status of the rule decryption: `ok`, `warn` or `error` .
|
||||
|
||||
| `execution_health`
|
||||
| Returns the timestamp and status of the rule execution: `ok`, `warn` or `error`.
|
||||
|
||||
| `read_health`
|
||||
| Returns the timestamp and status of the rule reading events: `ok`, `warn` or `error`.
|
||||
|
||||
|===
|
||||
<1> `is_sufficiently_secure` is `false` when security is enabled, but TLS is not.
|
||||
<2> `has_permanent_encryption_key` is `false` when the encrypted saved object
|
||||
plugin does not have a permanent encryption key.
|
||||
<3> `alerting_framework_health` has three substates that identify the health of
|
||||
the alerting framework: `decryption_health`, `execution_health`, and
|
||||
`read_health`. `decryption_health` returns the timestamp and status of the rule
|
||||
decryption: `ok`, `warn` or `error`. `execution_health` returns the timestamp
|
||||
and status of the rule execution: `ok`, `warn` or `error`. `read_health` returns
|
||||
the timestamp and status of the rule reading events: `ok`, `warn` or `error`.
|
||||
<4> `alerting_framework_heath` has a typo, use `alerting_framework_health`
|
||||
instead. deprecated:[8.0.0]
|
||||
|
|
|
|||
|
|
@ -15,9 +15,10 @@ Update the attributes for an existing rule.
|
|||
|
||||
=== {api-prereq-title}
|
||||
|
||||
You must have `all` privileges for the *Management* > *Stack Rules* feature or
|
||||
for the *{ml-app}*, *{observability}*, or *Security* features, depending on the
|
||||
`consumer` and `rule_type_id` of the rule you're updating. If the rule has
|
||||
You must have `all` privileges for the appropriate {kib} features, depending on
|
||||
the `consumer` and `rule_type_id` of the rule you're updating. For example, the
|
||||
*Management* > *Stack Rules* feature, *Analytics* > *Discover* and *{ml-app}*
|
||||
features, *{observability}*, or *Security* features. If the rule has
|
||||
`actions`, you must also have `read` privileges for the *Management* >
|
||||
*Actions and Connectors* feature. For more details, refer to
|
||||
<<kibana-feature-privileges>>.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue