github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-23 17:28:26 -04:00
Code Issues Projects Releases Packages Wiki Activity

[8.6] [DOCS] Create open API specification for create rule (#149565) (#149654)

Browse source 
# Backport

This will backport the following commits from `main` to `8.6`:
- [[DOCS] Create open API specification for create rule
(#149565)](https://github.com/elastic/kibana/pull/149565)

<!--- Backport version: 8.9.7 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Lisa
Cawley","email":"lcawley@elastic.co"},"sourceCommit":{"committedDate":"2023-01-27T02:07:23Z","message":"[DOCS]
Create open API specification for create rule
(#149565)","sha":"7421a9737d79b640991c3338248d0b6139a64a04","branchLabelMapping":{"^v8.7.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:enhancement","Team:ResponseOps","docs","Feature:Alerting/RuleTypes","backport:prev-minor","v8.7.0"],"number":149565,"url":"https://github.com/elastic/kibana/pull/149565","mergeCommit":{"message":"[DOCS]
Create open API specification for create rule
(#149565)","sha":"7421a9737d79b640991c3338248d0b6139a64a04"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"main","label":"v8.7.0","labelRegex":"^v8.7.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/149565","number":149565,"mergeCommit":{"message":"[DOCS]
Create open API specification for create rule
(#149565)","sha":"7421a9737d79b640991c3338248d0b6139a64a04"}}]}]
BACKPORT-->

Co-authored-by: Lisa Cawley <lcawley@elastic.co>
This commit is contained in:
Kibana Machine 2023-01-26 22:43:05 -05:00 • committed by GitHub
parent 48709573fd
commit cbe6e6783d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
10 changed files with 754 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

158
docs/api-generated/rules/rule-apis-passthru.asciidoc
View file

@ -18,6 +18,7 @@ Any modifications made to this file will be overwritten.
<div class="method-summary"></div>
<h4><a href="#Alerting">Alerting</a></h4>
<ul>
<li><a href="#createRule"><code><span class="http-method">post</span> /s/{spaceId}/api/alerting/rule/{ruleId}</code></a></li>
<li><a href="#deleteRule"><code><span class="http-method">delete</span> /s/{spaceId}/api/alerting/rule/{ruleId}</code></a></li>
<li><a href="#disableRule"><code><span class="http-method">post</span> /s/{spaceId}/api/alerting/rule/{ruleId}/_disable</code></a></li>
<li><a href="#enableRule"><code><span class="http-method">post</span> /s/{spaceId}/api/alerting/rule/{ruleId}/_enable</code></a></li>
@ -33,6 +34,130 @@ Any modifications made to this file will be overwritten.
</ul>
<h1><a name="Alerting">Alerting</a></h1>
<div class="method"><a name="createRule"/>
<div class="method-path">
<a class="up" href="#__Methods">Up</a>
<pre class="post"><code class="huge"><span class="http-method">post</span> /s/{spaceId}/api/alerting/rule/{ruleId}</code></pre></div>
<div class="method-summary">Creates a rule. (<span class="nickname">createRule</span>)</div>
<div class="method-notes">You must have <code>all</code> privileges for the appropriate Kibana features, depending on the <code>consumer</code> and <code>rule_type_id</code> of the rule you're creating. For example, you must have privileges for the <strong>Management &gt; Stack rules</strong> feature, <strong>Analytics &gt; Discover</strong> and <strong>Machine Learning</strong> features, <strong>Observability</strong> features, or <strong>Security</strong> features. If the rule has actions, you must also have <code>read</code> privileges for the <strong>Management &gt; Actions and Connectors</strong> feature. NOTE: This API supports only token-based authentication. When you create a rule, it identifies which roles you have at that point in time. Thereafter, when the rule performs queries, it uses those security privileges. If a user with different privileges updates the rule, its behavior might change.</div>
<h3 class="field-label">Path parameters</h3>
<div class="field-items">
<div class="param">spaceId (required)</div>
<div class="param-desc"><span class="param-type">Path Parameter</span> &mdash; An identifier for the space. If <code>/s/</code> and the identifier are omitted from the path, the default space is used. default: null </div><div class="param">ruleId (required)</div>
<div class="param-desc"><span class="param-type">Path Parameter</span> &mdash; An UUID v1 or v4 identifier for the rule. If you omit this parameter, an identifier is randomly generated. default: null </div>
</div> <!-- field-items -->
<h3 class="field-label">Consumes</h3>
This API call consumes the following media types via the <span class="header">Content-Type</span> request header:
<ul>
<li><code>application/json</code></li>
</ul>
<h3 class="field-label">Request body</h3>
<div class="field-items">
<div class="param">create_rule_request <a href="#create_rule_request">create_rule_request</a> (required)</div>
<div class="param-desc"><span class="param-type">Body Parameter</span> &mdash; </div>
</div> <!-- field-items -->
<h3 class="field-label">Request headers</h3>
<div class="field-items">
<div class="param">kbn-xsrf (required)</div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; Cross-site request forgery protection default: null </div>
</div> <!-- field-items -->
<h3 class="field-label">Return type</h3>
<div class="return-type">
<a href="#rule_response_properties">rule_response_properties</a>
</div>
<!--Todo: process Response Object and its headers, schema, examples -->
<h3 class="field-label">Example data</h3>
<div class="example-data-content-type">Content-Type: application/json</div>
<pre class="example"><code>{
"throttle" : "10m",
"created_at" : "2022-12-05T23:36:58.284Z",
"last_run" : {
"alerts_count" : {
"ignored" : 6,
"new" : 1,
"recovered" : 5,
"active" : 0
},
"outcome_msg" : "outcome_msg",
"warning" : "warning",
"outcome" : "succeeded"
},
"params" : {
"key" : ""
},
"created_by" : "elastic",
"enabled" : true,
"muted_alert_ids" : [ "muted_alert_ids", "muted_alert_ids" ],
"rule_type_id" : "monitoring_alert_cluster_health",
"tags" : [ "tags", "tags" ],
"api_key_owner" : "elastic",
"schedule" : {
"interval" : "1m"
},
"notify_when" : "onActiveAlert",
"next_run" : "2022-12-06T00:14:43.818Z",
"updated_at" : "2022-12-05T23:36:58.284Z",
"execution_status" : {
"last_execution_date" : "2022-12-06T00:13:43.89Z",
"last_duration" : 55,
"status" : "ok"
},
"name" : "cluster_health_rule",
"updated_by" : "elastic",
"scheduled_task_id" : "b530fed0-74f5-11ed-9801-35303b735aef",
"id" : "b530fed0-74f5-11ed-9801-35303b735aef",
"mute_all" : false,
"actions" : [ {
"id" : "9dca3e00-74f5-11ed-9801-35303b735aef",
"params" : {
"key" : ""
},
"group" : "default"
}, {
"id" : "9dca3e00-74f5-11ed-9801-35303b735aef",
"params" : {
"key" : ""
},
"group" : "default"
} ],
"consumer" : "alerts"
}</code></pre>
<h3 class="field-label">Produces</h3>
This API call produces the following media types according to the <span class="header">Accept</span> request header;
the media type will be conveyed by the <span class="header">Content-Type</span> response header.
<ul>
<li><code>application/json</code></li>
</ul>
<h3 class="field-label">Responses</h3>
<h4 class="field-label">200</h4>
Indicates a successful call.
<a href="#rule_response_properties">rule_response_properties</a>
<h4 class="field-label">401</h4>
Authorization information is missing or invalid.
<a href="#401_response">401_response</a>
<h4 class="field-label">404</h4>
Object is not found.
<a href="#404_response">404_response</a>
</div> <!-- method -->
<hr/>
<div class="method"><a name="deleteRule"/>
<div class="method-path">
<a class="up" href="#__Methods">Up</a>
@ -55,7 +180,7 @@ Any modifications made to this file will be overwritten.
<div class="field-items">
<div class="param">kbn-xsrf (required)</div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; default: null </div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; Cross-site request forgery protection default: null </div>
</div> <!-- field-items -->
@ -106,7 +231,7 @@ Any modifications made to this file will be overwritten.
<div class="field-items">
<div class="param">kbn-xsrf (required)</div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; default: null </div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; Cross-site request forgery protection default: null </div>
</div> <!-- field-items -->
@ -157,7 +282,7 @@ Any modifications made to this file will be overwritten.
<div class="field-items">
<div class="param">kbn-xsrf (required)</div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; default: null </div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; Cross-site request forgery protection default: null </div>
</div> <!-- field-items -->
@ -711,7 +836,7 @@ Any modifications made to this file will be overwritten.
<div class="field-items">
<div class="param">kbn-xsrf (required)</div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; default: null </div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; Cross-site request forgery protection default: null </div>
</div> <!-- field-items -->
@ -759,7 +884,7 @@ Any modifications made to this file will be overwritten.
<div class="field-items">
<div class="param">kbn-xsrf (required)</div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; default: null </div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; Cross-site request forgery protection default: null </div>
</div> <!-- field-items -->
@ -809,7 +934,7 @@ Any modifications made to this file will be overwritten.
<div class="field-items">
<div class="param">kbn-xsrf (required)</div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; default: null </div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; Cross-site request forgery protection default: null </div>
</div> <!-- field-items -->
@ -857,7 +982,7 @@ Any modifications made to this file will be overwritten.
<div class="field-items">
<div class="param">kbn-xsrf (required)</div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; default: null </div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; Cross-site request forgery protection default: null </div>
</div> <!-- field-items -->
@ -917,7 +1042,7 @@ Any modifications made to this file will be overwritten.
<div class="field-items">
<div class="param">kbn-xsrf (required)</div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; default: null </div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; Cross-site request forgery protection default: null </div>
</div> <!-- field-items -->
@ -1016,6 +1141,7 @@ Any modifications made to this file will be overwritten.
<li><a href="#401_response"><code>401_response</code> - Unsuccessful rule API response</a></li>
<li><a href="#404_response"><code>404_response</code> - </a></li>
<li><a href="#actions_inner"><code>actions_inner</code> - </a></li>
<li><a href="#create_rule_request"><code>create_rule_request</code> - Create rule request</a></li>
<li><a href="#findRules_200_response"><code>findRules_200_response</code> - </a></li>
<li><a href="#findRules_has_reference_parameter"><code>findRules_has_reference_parameter</code> - </a></li>
<li><a href="#findRules_search_fields_parameter"><code>findRules_search_fields_parameter</code> - </a></li>
@ -1078,6 +1204,22 @@ Any modifications made to this file will be overwritten.
<div class="param">params (optional)</div><div class="param-desc"><span class="param-type"><a href="#AnyType">map[String, oas_any_type_not_mapped]</a></span> The parameters for the action, which are sent to the connector. The <code>params</code> are handled as Mustache templates and passed a default set of context. </div>
</div> <!-- field-items -->
</div>
<div class="model">
<h3><a name="create_rule_request"><code>create_rule_request</code> - Create rule request</a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'>The create rule API request body varies depending on the type of rule and actions.</div>
<div class="field-items">
<div class="param">actions (optional)</div><div class="param-desc"><span class="param-type"><a href="#actions_inner">array[actions_inner]</a></span> </div>
<div class="param">consumer </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The name of the application or feature that owns the rule. For example: <code>alerts</code>, <code>apm</code>, <code>discover</code>, <code>infrastructure</code>, <code>logs</code>, <code>metrics</code>, <code>ml</code>, <code>monitoring</code>, <code>securitySolution</code>, <code>siem</code>, <code>stackAlerts</code>, or <code>uptime</code>. </div>
<div class="param">enabled (optional)</div><div class="param-desc"><span class="param-type"><a href="#boolean">Boolean</a></span> Indicates whether you want to run the rule on an interval basis after it is created. </div>
<div class="param">name </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The name of the rule. While this name does not have to be unique, a distinctive name can help you identify a rule. </div>
<div class="param">notify_when </div><div class="param-desc"><span class="param-type"><a href="#notify_when">notify_when</a></span> </div>
<div class="param">params </div><div class="param-desc"><span class="param-type"><a href="#AnyType">map[String, oas_any_type_not_mapped]</a></span> The parameters for the rule. </div>
<div class="param">rule_type_id </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The ID of the rule type that you want to call when the rule is scheduled to run. For example, <code>.es-query</code>, <code>.index-threshold</code>, <code>logs.alert.document.count</code>, <code>monitoring_alert_cluster_health</code>, <code>siem.thresholdRule</code>, or <code>xpack.ml.anomaly_detection_alert</code>. </div>
<div class="param">schedule </div><div class="param-desc"><span class="param-type"><a href="#schedule">schedule</a></span> </div>
<div class="param">tags (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">array[String]</a></span> The tags for the rule. </div>
<div class="param">throttle (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The throttle interval, which defines how often an alert generates repeated actions. It is applicable only if <code>notify_when</code> is set to <code>onThrottleInterval</code>. It is specified in seconds, minutes, hours, or days. </div>
</div> <!-- field-items -->
</div>
<div class="model">
<h3><a name="findRules_200_response"><code>findRules_200_response</code> - </a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'></div>

6
docs/api/alerting/create_rule.asciidoc
View file

@ -6,6 +6,12 @@
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]. For a preview, check out <<rule-apis>>.
====
[[create-rule-api-request]]
=== {api-request-title}

235
x-pack/plugins/alerting/docs/openapi/bundled.json
View file

@ -133,6 +133,89 @@
}
]
},
"post": {
"summary": "Creates a rule.",
"operationId": "createRule",
"description": "You must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're creating. For example, you must have privileges for the **Management > Stack rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability** features, or **Security** features. If the rule has actions, you must also have `read` privileges for the **Management > Actions and Connectors** feature. NOTE: This API supports only token-based authentication. When you create a rule, it identifies which roles you have at that point in time. Thereafter, when the rule performs queries, it uses those security privileges. If a user with different privileges updates the rule, its behavior might change.\n",
"tags": [
"alerting"
],
"parameters": [
{
"$ref": "#/components/parameters/kbn_xsrf"
},
{
"$ref": "#/components/parameters/space_id"
},
{
"in": "path",
"name": "ruleId",
"description": "An UUID v1 or v4 identifier for the rule. If you omit this parameter, an identifier is randomly generated.\n",
"required": true,
"schema": {
"type": "string",
"example": "ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create_rule_request"
},
"examples": {
"createCaseRequest": {
"$ref": "#/components/examples/create_rule_request"
}
}
}
}
},
"responses": {
"200": {
"description": "Indicates a successful call.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rule_response_properties"
},
"examples": {
"createRuleResponse": {
"$ref": "#/components/examples/create_rule_response"
}
}
}
}
},
"401": {
"description": "Authorization information is missing or invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/401_response"
}
}
}
},
"404": {
"description": "Object is not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/404_response"
}
}
}
}
},
"servers": [
{
"url": "https://localhost:5601"
}
]
},
"put": {
"summary": "Updates the attributes for a rule.",
"operationId": "updateRule",
@ -1201,6 +1284,7 @@
},
"in": "header",
"name": "kbn-xsrf",
"description": "Cross-site request forgery protection",
"required": true
},
"alert_id": {
@ -1538,6 +1622,58 @@
"$ref": "#/components/schemas/throttle"
}
}
},
"create_rule_request": {
"title": "Create rule request",
"description": "The create rule API request body varies depending on the type of rule and actions.",
"type": "object",
"required": [
"consumer",
"name",
"notify_when",
"params",
"rule_type_id",
"schedule"
],
"properties": {
"actions": {
"$ref": "#/components/schemas/actions"
},
"consumer": {
"type": "string",
"description": "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`.\n"
},
"enabled": {
"type": "boolean",
"description": "Indicates whether you want to run the rule on an interval basis after it is created."
},
"name": {
"type": "string",
"description": "The name of the rule. While this name does not have to be unique, a distinctive name can help you identify a rule.",
"example": "cluster_health_rule"
},
"notify_when": {
"$ref": "#/components/schemas/notify_when"
},
"params": {
"type": "object",
"description": "The parameters for the rule.",
"additionalProperties": true
},
"rule_type_id": {
"type": "string",
"description": "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`.\n"
},
"schedule": {
"$ref": "#/components/schemas/schedule"
},
"tags": {
"$ref": "#/components/schemas/tags"
},
"throttle": {
"$ref": "#/components/schemas/throttle"
}
}
}
},
"examples": {
@ -1701,6 +1837,105 @@
"next_run": "2022-12-12T22:44:21.653Z"
}
},
"create_rule_request": {
"summary": "Create an index threshold rule.",
"value": {
"actions": [
{
"id": "dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2",
"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}}"
}
}
],
"consumer": "alerts",
"name": "my rule",
"notify_when": "onActionGroupChange",
"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",
"schedule": {
"interval": "1m"
},
"tags": [
"cpu"
]
}
},
"create_rule_response": {
"summary": "The create rule API returns a JSON object that contains details about the rule.",
"value": {
"actions": [
{
"group": "threshold met",
"id": "dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2",
"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}}"
}
}
],
"api_key_owner": "elastic",
"consumer": "alerts",
"created_at": "2022-06-08T17:20:31.632Z",
"created_by": "elastic",
"enabled": true,
"execution_status": {
"last_execution_date": "2022-06-08T17:20:31.632Z",
"status": "pending"
},
"id": "41893910-6bca-11eb-9e0d-85d233e3ee35",
"muted_alert_ids": [],
"mute_all": false,
"name": "my rule",
"notify_when": "onActionGroupChange",
"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",
"schedule": {
"interval": "1m"
},
"scheduled_task_id": "425b0800-6bca-11eb-9e0d-85d233e3ee35",
"tags": [
"cpu"
],
"throttle": null,
"updated_at": "2022-06-08T17:20:31.632Z",
"updated_by": "elastic"
}
},
"find_rules_response": {
"summary": "Retrieve information about a rule.",
"value": {

179
x-pack/plugins/alerting/docs/openapi/bundled.yaml
View file

@ -78,6 +78,57 @@ paths:
$ref: '#/components/schemas/404_response'
servers:
- url: https://localhost:5601
post:
summary: Creates a rule.
operationId: createRule
description: |
You must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're creating. For example, you must have privileges for the **Management > Stack rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability** features, or **Security** features. If the rule has actions, you must also have `read` privileges for the **Management > Actions and Connectors** feature. NOTE: This API supports only token-based authentication. When you create a rule, it identifies which roles you have at that point in time. Thereafter, when the rule performs queries, it uses those security privileges. If a user with different privileges updates the rule, its behavior might change.
tags:
- alerting
parameters:
- $ref: '#/components/parameters/kbn_xsrf'
- $ref: '#/components/parameters/space_id'
- in: path
name: ruleId
description: |
An UUID v1 or v4 identifier for the rule. If you omit this parameter, an identifier is randomly generated.
required: true
schema:
type: string
example: ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_rule_request'
examples:
createCaseRequest:
$ref: '#/components/examples/create_rule_request'
responses:
'200':
description: Indicates a successful call.
content:
application/json:
schema:
$ref: '#/components/schemas/rule_response_properties'
examples:
createRuleResponse:
$ref: '#/components/examples/create_rule_response'
'401':
description: Authorization information is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/401_response'
'404':
description: Object is not found.
content:
application/json:
schema:
$ref: '#/components/schemas/404_response'
servers:
- url: https://localhost:5601
put:
summary: Updates the attributes for a rule.
operationId: updateRule
@ -746,6 +797,7 @@ components:
type: string
in: header
name: kbn-xsrf
description: Cross-site request forgery protection
required: true
alert_id:
in: path
@ -1003,6 +1055,47 @@ components:
$ref: '#/components/schemas/tags'
throttle:
$ref: '#/components/schemas/throttle'
create_rule_request:
title: Create rule request
description: The create rule API request body varies depending on the type of rule and actions.
type: object
required:
- consumer
- name
- notify_when
- params
- rule_type_id
- schedule
properties:
actions:
$ref: '#/components/schemas/actions'
consumer:
type: string
description: |
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:
type: boolean
description: Indicates whether you want to run the rule on an interval basis after it is created.
name:
type: string
description: The name of the rule. While this name does not have to be unique, a distinctive name can help you identify a rule.
example: cluster_health_rule
notify_when:
$ref: '#/components/schemas/notify_when'
params:
type: object
description: The parameters for the rule.
additionalProperties: true
rule_type_id:
type: string
description: |
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`.
schedule:
$ref: '#/components/schemas/schedule'
tags:
$ref: '#/components/schemas/tags'
throttle:
$ref: '#/components/schemas/throttle'
examples:
get_rule_response:
summary: The get rule API returns a JSON object that contains details about the rule.
@ -1140,6 +1233,92 @@ components:
warning: null
outcome: succeeded
next_run: '2022-12-12T22:44:21.653Z'
create_rule_request:
summary: Create an index threshold rule.
value:
actions:
- id: dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2
group: threshold met
params:
level: info
message: |-
alert '{{alertName}}' is active for group '{{context.group}}':
- Value: {{context.value}}
- Conditions Met: {{context.conditions}} over {{params.timeWindowSize}}{{params.timeWindowUnit}}
- Timestamp: {{context.date}}
consumer: alerts
name: my rule
notify_when: onActionGroupChange
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
schedule:
interval: 1m
tags:
- cpu
create_rule_response:
summary: The create rule API returns a JSON object that contains details about the rule.
value:
actions:
- group: threshold met
id: dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2
params:
level: info
message: |-
alert {{alertName}} is active for group {{context.group} :
- Value: {{context.value}}
- Conditions Met: {{context.conditions}} over {{params.timeWindowSize}}{{params.timeWindowUnit}}
- Timestamp: {{context.date}}
api_key_owner: elastic
consumer: alerts
created_at: '2022-06-08T17:20:31.632Z'
created_by: elastic
enabled: true
execution_status:
last_execution_date: '2022-06-08T17:20:31.632Z'
status: pending
id: 41893910-6bca-11eb-9e0d-85d233e3ee35
muted_alert_ids: []
mute_all: false
name: my rule
notify_when: onActionGroupChange
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
schedule:
interval: 1m
scheduled_task_id: 425b0800-6bca-11eb-9e0d-85d233e3ee35
tags:
- cpu
throttle: null
updated_at: '2022-06-08T17:20:31.632Z'
updated_by: elastic
find_rules_response:
summary: Retrieve information about a rule.
value:

30
x-pack/plugins/alerting/docs/openapi/components/examples/create_rule_request.yaml Normal file
View file

@ -0,0 +1,30 @@
summary: Create an index threshold rule.
value:
actions:
- id: dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2
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}}"
consumer: alerts
name: my rule
notify_when: onActionGroupChange
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
schedule:
interval: 1m
tags:
- cpu

44
x-pack/plugins/alerting/docs/openapi/components/examples/create_rule_response.yaml Normal file
View file

@ -0,0 +1,44 @@
summary: The create rule API returns a JSON object that contains details about the rule.
value:
actions:
- group: threshold met
id: dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2
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}}"
api_key_owner: elastic
consumer: alerts
created_at: '2022-06-08T17:20:31.632Z'
created_by: elastic
enabled: true
execution_status:
last_execution_date: '2022-06-08T17:20:31.632Z'
status: pending
id: 41893910-6bca-11eb-9e0d-85d233e3ee35
muted_alert_ids: []
mute_all: false
name: my rule
notify_when: onActionGroupChange
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
schedule:
interval: 1m
scheduled_task_id: 425b0800-6bca-11eb-9e0d-85d233e3ee35
tags:
- cpu
throttle: null
updated_at: '2022-06-08T17:20:31.632Z'
updated_by: elastic

2
x-pack/plugins/alerting/docs/openapi/components/examples/update_rule_request.yaml
View file

@ -10,7 +10,7 @@ value:
timeWindowUnit: m
thresholdComparator: ">"
threshold: [1000]
aggField : sheet.version
aggField: sheet.version
termField: name.keyword
termSize: 6
schedule:

1
x-pack/plugins/alerting/docs/openapi/components/headers/kbn_xsrf.yaml
View file

@ -2,4 +2,5 @@ schema:
type: string
in: header
name: kbn-xsrf
description: Cross-site request forgery protection
required: true

45
x-pack/plugins/alerting/docs/openapi/components/schemas/create_rule_request.yaml Normal file
View file

@ -0,0 +1,45 @@
title: Create rule request
description: >-
The create rule API request body varies depending on the type of rule and actions.
type: object
required:
- consumer
- name
- notify_when
- params
- rule_type_id
- schedule
properties:
actions:
$ref: 'actions.yaml'
consumer:
type: string
description: >
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:
type: boolean
description: Indicates whether you want to run the rule on an interval basis after it is created.
name:
type: string
description: The name of the rule. While this name does not have to be unique, a distinctive name can help you identify a rule.
example: cluster_health_rule
notify_when:
$ref: 'notify_when.yaml'
params:
type: object
description: The parameters for the rule.
additionalProperties: true
rule_type_id:
type: string
description: >
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`.
schedule:
$ref: 'schedule.yaml'
tags:
$ref: 'tags.yaml'
throttle:
$ref: 'throttle.yaml'

63
x-pack/plugins/alerting/docs/openapi/paths/s@{spaceid}@api@alerting@rule@{ruleid}.yaml
View file

@ -71,6 +71,69 @@ delete:
servers:
- url: https://localhost:5601
post:
summary: Creates a rule.
operationId: createRule
description: >
You must have `all` privileges for the appropriate Kibana features,
depending on the `consumer` and `rule_type_id` of the rule you're creating.
For example, you must have privileges for the **Management > Stack rules**
feature, **Analytics > Discover** and **Machine Learning** features,
**Observability** features, or **Security** features. If the rule has
actions, you must also have `read` privileges for the
**Management > Actions and Connectors** feature. NOTE: This API supports
only token-based authentication. When you create a rule, it identifies which
roles you have at that point in time. Thereafter, when the rule performs
queries, it uses those security privileges. If a user with different
privileges updates the rule, its behavior might change.
tags:
- alerting
parameters:
- $ref: ../components/headers/kbn_xsrf.yaml
- $ref: '../components/parameters/space_id.yaml'
- in: path
name: ruleId
description: >
An UUID v1 or v4 identifier for the rule. If you omit this parameter,
an identifier is randomly generated.
required: true
schema:
type: string
example: ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74
requestBody:
required: true
content:
application/json:
schema:
$ref: '../components/schemas/create_rule_request.yaml'
examples:
createCaseRequest:
$ref: '../components/examples/create_rule_request.yaml'
responses:
'200':
description: Indicates a successful call.
content:
application/json:
schema:
$ref: '../components/schemas/rule_response_properties.yaml'
examples:
createRuleResponse:
$ref: '../components/examples/create_rule_response.yaml'
'401':
description: Authorization information is missing or invalid.
content:
application/json:
schema:
$ref: '../components/schemas/401_response.yaml'
'404':
description: Object is not found.
content:
application/json:
schema:
$ref: '../components/schemas/404_response.yaml'
servers:
- url: https://localhost:5601
put:
summary: Updates the attributes for a rule.
operationId: updateRule