mirror of
https://github.com/elastic/kibana.git
synced 2025-04-25 02:09:32 -04:00
229 lines
6.9 KiB
Text
229 lines
6.9 KiB
Text
[[create-rule-api]]
|
|
== Create rule API
|
|
++++
|
|
<titleabbrev>Create rule</titleabbrev>
|
|
++++
|
|
|
|
Create {kib} rules.
|
|
|
|
[NOTE]
|
|
====
|
|
For the most up-to-date API details, refer to the
|
|
{kib-repo}/tree/{branch}/x-pack/plugins/alerting/docs/openapi[open API specification].
|
|
====
|
|
|
|
[[create-rule-api-request]]
|
|
=== {api-request-title}
|
|
|
|
`POST <kibana host>:<port>/api/alerting/rule/<id>`
|
|
|
|
`POST <kibana host>:<port>/s/<space_id>/api/alerting/rule/<id>`
|
|
|
|
|
|
=== {api-prereq-title}
|
|
|
|
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* >
|
|
*{connectors-feature}* feature. For more details, refer to
|
|
<<kibana-feature-privileges>>.
|
|
|
|
[[create-rule-api-path-params]]
|
|
=== {api-path-parms-title}
|
|
|
|
`<id>`::
|
|
(Optional, string) Specifies a UUID v1 or v4 to use instead of a randomly
|
|
generated ID.
|
|
|
|
`space_id`::
|
|
(Optional, string) An identifier for the space. If `space_id` is not provided in
|
|
the URL, the default space is used.
|
|
|
|
[role="child_attributes"]
|
|
[[create-rule-api-request-body]]
|
|
=== {api-request-body-title}
|
|
|
|
`actions`::
|
|
(Optional, object array) An array of action objects.
|
|
+
|
|
.Properties of the action objects:
|
|
[%collapsible%open]
|
|
=====
|
|
|
|
`group`:::
|
|
(Required, string) Grouping actions is recommended for escalations for different
|
|
types of alerts. If you don't need this, set this value to `default`.
|
|
|
|
`id`:::
|
|
(Required, string) The ID of the connector saved object, which you can obtain by
|
|
using <<get-all-connectors-api>>.
|
|
|
|
`params`:::
|
|
(Required, object) The map to the `params` that the
|
|
<<action-types,connector type>> will receive. ` params` are handled as Mustache
|
|
templates and passed a default set of context.
|
|
=====
|
|
|
|
`consumer`::
|
|
(Required, string) The name of the application or feature that owns the rule.
|
|
For example: `alerts`, `apm`, `discover`, `infrastructure`, `logs`, `metrics`,
|
|
`ml`, `monitoring`, `securitySolution`, `siem`, `stackAlerts`, or `uptime`.
|
|
|
|
`enabled`::
|
|
(Optional, boolean) Indicates if you want to run the rule on an interval basis
|
|
after it is created.
|
|
|
|
`name`::
|
|
(Required, string) The name of the rule. While this name does not have to be
|
|
unique, a distinctive name can help you identify a rule.
|
|
|
|
`notify_when`::
|
|
(Required, string) Defines how often alerts generate actions. Valid values are:
|
|
+
|
|
--
|
|
|
|
* `onActionGroupChange`: Actions run when the alert status changes.
|
|
* `onActiveAlert`: Actions run when the alert becomes active and at each check
|
|
interval while the rule conditions are met.
|
|
* `onThrottleInterval`: Actions run when the alert becomes active and at the
|
|
interval specified in the `throttle` property while the rule conditions are met.
|
|
|
|
--
|
|
|
|
`params`::
|
|
(Required, object) The parameters to pass to the rule type executor `params`
|
|
value. This will also validate against the rule type params validator, if defined.
|
|
|
|
`rule_type_id`::
|
|
(Required, string) The ID of the rule type that you want to call when the rule
|
|
is scheduled to run. For example, `.es-query`, `.index-threshold`,
|
|
`logs.alert.document.count`, `monitoring_alert_cluster_health`,
|
|
`siem.thresholdRule`, or `xpack.ml.anomaly_detection_alert`. For more
|
|
information, refer to <<rule-types>>.
|
|
|
|
`schedule`::
|
|
(Required, object) The check interval, which specifies how frequently the rule
|
|
conditions are checked. The interval must be specified in seconds, minutes,
|
|
hours or days. For example: `{ "interval": "10s" }`, `{ "interval": "5m" }`,
|
|
`{ "interval": "1h" }`, or `{ "interval": "1d" }`.
|
|
|
|
`tags`::
|
|
(Optional, string array) A list of tag names that are applied to a rule.
|
|
|
|
`throttle`::
|
|
(Optional, string) Defines how often an alert generates repeated actions.
|
|
This custom action interval must be specified in seconds, minutes, hours, or
|
|
days. For example, `10m` or `1h`. This property is used only if `notify_when`
|
|
is `onThrottleInterval`.
|
|
|
|
[[create-rule-api-request-codes]]
|
|
=== {api-response-codes-title}
|
|
|
|
`200`::
|
|
Indicates a successful call.
|
|
|
|
[[create-rule-api-example]]
|
|
=== {api-examples-title}
|
|
|
|
Create an <<rule-type-index-threshold,index threshold rule>> that has actions
|
|
associated with a server log connector:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
POST api/alerting/rule
|
|
{
|
|
"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",
|
|
"rule_type_id":".index-threshold",
|
|
"schedule":{
|
|
"interval":"1m"
|
|
},
|
|
"actions":[
|
|
{
|
|
"id":"dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2",
|
|
"group":"threshold met",
|
|
"params":{
|
|
"level":"info",
|
|
"message":"Rule '{{rule.name}}' is active for group '{{context.group}}':\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
|
|
}
|
|
}
|
|
],
|
|
"tags":[
|
|
"cpu"
|
|
],
|
|
"notify_when":"onActionGroupChange",
|
|
"name":"my alert"
|
|
}
|
|
--------------------------------------------------
|
|
// KIBANA
|
|
|
|
The API returns the following:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
{
|
|
"id": "41893910-6bca-11eb-9e0d-85d233e3ee35",
|
|
"consumer": "alerts",
|
|
"tags": ["cpu"],
|
|
"name": "my alert",
|
|
"enabled": true,
|
|
"throttle": null,
|
|
"schedule": {"interval": "1m"},
|
|
"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"
|
|
},
|
|
"rule_type_id": ".index-threshold",
|
|
"scheduled_task_id": "425b0800-6bca-11eb-9e0d-85d233e3ee35",
|
|
"created_by": "elastic",
|
|
"updated_by": "elastic",
|
|
"created_at": "2022-06-08T17:20:31.632Z",
|
|
"updated_at": "2022-06-08T17:20:31.632Z",
|
|
"api_key_owner": "elastic",
|
|
"notify_when": "onActionGroupChange",
|
|
"mute_all": false,
|
|
"muted_alert_ids": [],
|
|
"execution_status": {
|
|
"last_execution_date": "2022-06-08T17:20:31.632Z",
|
|
"status": "pending"
|
|
},
|
|
"actions": [
|
|
{
|
|
"group": "threshold met",
|
|
"id": "dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2",
|
|
"params": {
|
|
"level": "info",
|
|
"message": "Rule {{rule.name}} is active for group {{context.group}}:\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
|
|
},
|
|
"connector_type_id": ".server-log"
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|