github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-24 09:48:58 -04:00
Code Issues Projects Releases Packages Wiki Activity

[DOCS] Adds prerequisites to list rule types API (#136326) (#136755)

Browse source 
(cherry picked from commit a64d9fc6ac)

Co-authored-by: Lisa Cawley <lcawley@elastic.co>
This commit is contained in:
Kibana Machine 2022-07-20 13:38:41 -04:00 • committed by GitHub
parent 30784df132
commit d9c3e820f5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 114 additions and 94 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/api/alerting.asciidoc
View file

@ -38,8 +38,8 @@ include::alerting/enable_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/list_rule_types.asciidoc[leveloffset=+1]
include::alerting/update_rule.asciidoc[leveloffset=+1]
include::alerting/list_rule_types.asciidoc[]
include::alerting/mute_all_alerts.asciidoc[]
include::alerting/mute_alert.asciidoc[]
include::alerting/unmute_all_alerts.asciidoc[]

2
docs/api/alerting/find_rules.asciidoc
View file

@ -19,7 +19,7 @@ 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.
with the *{stack-monitor-app}* feature, use the `monitoring_user` built-in role.
For more details, refer to <<kibana-feature-privileges>>.

2
docs/api/alerting/get_rules.asciidoc
View file

@ -19,7 +19,7 @@ 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.
with the *{stack-monitor-app}* feature, use the `monitoring_user` built-in role.
For more details, refer to <<kibana-feature-privileges>>.

202
docs/api/alerting/list_rule_types.asciidoc
View file

@ -1,143 +1,163 @@
[[list-rule-types-api]]
=== List rule types API
== Get rule types API
++++
<titleabbrev>List rule types</titleabbrev>
<titleabbrev>Get rule types</titleabbrev>
++++
Retrieve a list of rule types that the user is authorized to access.
Each rule type includes a list of consumer features. Within these features, users are authorized to perform either `read` or `all` operations on rules of that type. This helps determine which rule types users can read, but not create or modify.
NOTE: Some rule types are limited to specific features. These rule types are not available when <<create-edit-rules, defining rules>> in <<management,Stack Management>>.
[[list-rule-types-api-request]]
==== Request
=== {api-request-title}
`GET <kibana host>:<port>/api/alerting/rule_types`
`GET <kibana host>:<port>/s/<space_id>/api/alerting/rule_types`
=== {api-prereq-title}
If you have `read` privileges for one or more {kib} features, the API response
contains information about the appropriate rule types. For example, there are
rule types associated with the *Management* > *Stack Rules* feature,
*Analytics* > *Discover* and *{ml-app}* features, *{observability}*, and
*Security* features. To get rule types associated with the
*{stack-monitor-app}* feature, use the `monitoring_user` built-in role.
For more details, refer to <<kibana-feature-privileges>>.
=== {api-description-title}
Each rule type includes a list of authorized consumer features. For each feature,
users are authorized to perform either `read` or `all` operations on rules of
that type. This enables you to determine which rule types you can read, create,
or modify. If you want to create or edit a rule in {kib}, some rule types are
limited to specific features and apps.
[[list-rule-types-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.
[[list-rule-types-response]]
=== {api-response-body-title}
Each rule type has the following properties in the API response:
`action_groups`::
(array of objects) An explicit list of groups for which the rule type can
schedule actions, each with the action group's unique ID and human readable name.
Rule `actions` validation uses this configuration to ensure that groups are
valid.
`action_variables`::
(object) A list of action variables that the rule type makes available via
context and state in action parameter templates, and a short human readable
description. When you create a rule in {kib}, it uses this information to prompt
you for these variables in action parameter editors.
`authorized_consumers`::
(object) The list of the plugins IDs that have access to the rule type.
`default_action_group_id`::
(string) The default ID for the rule type group.
`does_set_recovery_context`::
(boolean) Indicates whether the rule passes context variables to its recovery
action.
`enabled_in_license`::
(boolean) Indicates whether the rule type is enabled or disabled based on the
subscription.
`id`::
(string) The unique identifier for the rule type.
`is_exportable`::
(boolean) Indicates whether the rule type is exportable in *{stack-manage-app}*
> *Saved Objects*.
`minimum_license_required`::
(string) The {subscriptions}[subscriptions] required to use the rule type.
`name`::
(string) The descriptive name of the rule type.
`producer`::
(string) An identifier for the application that produces this rule type.
`recovery_action_group`::
(object) An action group to use when an alert goes from an active state to an
inactive one.
[[list-rule-types-api-codes]]
==== Response code
=== {api-response-codes-title}
`200`::
Indicates a successful call.
[[list-rule-types-api-example]]
==== Example
=== {api-examples-title}
[source,sh]
--------------------------------------------------
$ curl -X GET api/alerting/rule_types
GET api/alerting/rule_types
--------------------------------------------------
// KIBANA
The API returns the following:
For example, if you have `read` privileges for the {observability} {logs-app},
the API returns the following:
[source,sh]
--------------------------------------------------
[
{
"id":".index-threshold",
"name":"Index threshold",
"id":"logs.alert.document.count",
"name":"Log threshold",
"producer":"logs",
"enabled_in_license":true,
"recovery_action_group":{
"id":"recovered",
"name":"Recovered"
},
"action_groups":[
{
"id":"threshold met",
"name":"Threshold met"
"id":"logs.threshold.fired",
"name":"Fired"
},
{
"id":"recovered",
"name":"Recovered"
}
],
"recovery_action_group":{
"id":"recovered",
"name":"Recovered"
},
"default_action_group_id":"threshold met",
"default_action_group_id":"logs.threshold.fired",
"minimum_license_required":"basic",
"is_exportable":true,
"rule_task_timeout":"5m",
"action_variables":{
"context":[
{
"name":"message",
"description":"A pre-constructed message for the alert."
"name":"timestamp",
"description":"UTC timestamp of when the alert was triggered"
},
{
"name":"matchingDocuments",
"description":"The number of log entries that matched the conditions provided"
},
{
"name":"conditions",
"description":"The conditions that log entries needed to fulfill"
},
...
],
"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"
},
]
"params":[]
},
"producer":"stackAlerts",
"minimum_license_required":"basic",
"is_exportable":true,
"enabled_in_license":true,
"authorized_consumers":{
"alerts":{
"read":true,
"all":true
},
"stackAlerts":{
"read":true,
"all":true
},
"uptime":{
"read":true,
"all":true
}
}
"logs":{"read":true,"all":false},
"alerts":{"read":true,"all":false}
},
"does_set_recovery_context":true
}
]
--------------------------------------------------
Each rule type contains the following properties:
[cols="2*<"]
|===
| `name`
| The descriptive name of the rule type.
| `id`
| The unique ID of the rule type.
| `minimum_license_required`
| The license required to use the rule type.
| `is_exportable`
| Whether the rule type is exportable through the Saved Objects Management UI.
| `enabled_in_license`
| Whether the rule type is enabled or disabled based on the license.
| `action_groups`
| An explicit list of groups for which the rule type can schedule actions, each with the action group's unique ID and human readable name. Rule `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 rule type.
| `recovery_action_group`
| An action group to use when an alert goes from an active state, to an inactive one. Do not specify this action group under the `action_groups` property. If `recovery_action_group` is not specified, the default `recovered` action group is used.
| `default_action_group_od`
| The default ID for the rule type group.
| `action_variables`
| An explicit list of action variables that the rule type makes available via context and state in action parameter templates, and a short human readable description. The Rule 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 rule type.
| `authorized_consumers`
| The list of the plugins IDs that have access to the rule type.
|===