[8.13] [DOCS] Improve tracking containment rule (#176979) (#177533)

# Backport This will backport the following commits from `main` to `8.13`: - [[DOCS] Improve tracking containment rule (#176979)](#176979)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport)  Co-authored-by: Lisa Cawley <[email protected]>
elastic · Feb 22, 2024 · 1eab667 · 1eab667
1 parent c414372
commit 1eab667
Show file tree

Hide file tree

Showing 15 changed files with 331 additions and 22 deletions.
diff --git a/docs/user/alerting/images/alert-types-tracking-containment-action-options.png b/docs/user/alerting/images/alert-types-tracking-containment-action-options.png
diff --git a/docs/user/alerting/images/alert-types-tracking-containment-conditions.png b/docs/user/alerting/images/alert-types-tracking-containment-conditions.png
diff --git a/...user/alerting/images/alert-types-tracking-containment-rule-action-variables.png b/...user/alerting/images/alert-types-tracking-containment-rule-action-variables.png
diff --git a/docs/user/alerting/rule-types/es-query.asciidoc b/docs/user/alerting/rule-types/es-query.asciidoc
@@ -134,7 +134,7 @@ For example:
 image::images/es-query-rule-action-query-matched.png[UI for defining a recovery action]
 // NOTE: This is an autogenerated screenshot. Do not edit it directly.
 
-You can further refine the conditions under which actions run by specifying that actions only run they match a KQL query or when an alert occurs within a specific time frame.
+You can further refine the conditions under which actions run by specifying that actions only run when they match a KQL query or when an alert occurs within a specific time frame.
 
 [float]
 === Add action variables

diff --git a/docs/user/alerting/rule-types/geo-rule-types.asciidoc b/docs/user/alerting/rule-types/geo-rule-types.asciidoc
@@ -10,24 +10,91 @@
 
 The tracking containment rule alerts when an entity is contained or no longer contained within a boundary. 
 
+In *{stack-manage-app}* > *{rules-ui}*, click *Create rule*, fill in the name and optional tags, then select *Tracking containment*.
+
 [float]
-=== Requirements
-To create a tracking containment rule, the following requirements must be present:
+=== Define the conditions
+
+When you create a tracking containment rule, you must define the conditions that it detects. For example:
+
+[role="screenshot"]
+image::user/alerting/images/alert-types-tracking-containment-conditions.png[Creating a tracking containment rule in Kibana,width=75%]
+// NOTE: This is an autogenerated screenshot. Do not edit it directly.
+
+. Define the entities index, which must contain a `geo_point` or `geo_shape` field, `date` field, and entity identifier.
+  An entity identifier is a `keyword`, `number`, or `ip` field that identifies the entity.
+  Entity data is expected to be updating so that there are entity movements to alert upon.
+
+. Define the boundaries index, which contains `geo_shape` data.
+  Boundaries data is expected to be static (not updating).
+  Boundaries are collected once when the rule is created and anytime after when boundary configuration is modified.
 
-- *Entities index*: An index containing a `geo_point` or `geo_shape` field, `date` field, and entity identifier. An entity identifier is a `keyword`, `number`, or `ip` field that identifies the entity. Entity data is expected to be updating so that there are entity movements to alert upon.
-- *Boundaries index*: An index containing `geo_shape` data.
-Boundaries data is expected to be static (not updating). Boundaries are collected once when the rule is created and anytime after when boundary configuration is modified.
+. Set the check interval, which defines how often to evaluate the rule conditions. 
 
-Entity locations are queried to determine if they are contained within any monitored boundaries.
-Entity data should be somewhat "real time", meaning the dates of new documents aren’t older
-than the current time minus the amount of the interval. If data older than
-`now - <current interval>` is ingested, it won't trigger a rule.
+Entity locations are queried to determine whether they are contained within any monitored boundaries.
+Entity data should be somewhat "real time", meaning the dates of new documents aren't older than the current time minus the amount of the interval.
+If data older than `now - <check interval>` is ingested, it won't trigger a rule.
 
 [float]
-=== Actions
+=== Add actions
 
-A rule can be triggered either when a containment condition is met or when an entity is no longer contained.
+You can optionally send notifications when the rule conditions are met.
+In particular, this rule type supports:
+
+- alert summaries
+- actions that run when the containment condition is met
+- actions that run when an entity is no longer contained
+
+For each action, you must choose a connector, which provides connection information for a {kib} service or third party integration.
+For more information about all the supported connectors, go to <<action-types>>.
+
+After you select a connector, you must set the action frequency.
+You can choose to create a summary of alerts on each check interval or on a custom interval.
+Alternatively, you can set the action frequency such that actions run for each alert.
+Choose how often the action runs (at each check interval, only when the alert status changes, or at a custom action interval).
+You must also choose an action group, which indicates whether the action runs when the containment condition is met or when an entity is no longer contained.
+Each connector supports a specific set of actions for each action group.
+For example:
 
 [role="screenshot"]
 image::user/alerting/images/alert-types-tracking-containment-action-options.png[Action frequency options for an action,width=75%]
 // NOTE: This is an autogenerated screenshot. Do not edit it directly.
+
+You can further refine the conditions under which actions run by specifying that actions only run when they match a KQL query or when an alert occurs within a specific time frame.
+
+[float]
+=== Add action variables
+
+You can pass rule values to an action to provide contextual details.
+To view the list of variables available for each action, click the "add rule variable" button.
+For example:
+
+[role="screenshot"]
+image::images/alert-types-tracking-containment-rule-action-variables.png[Passing rule values to an action,width=75%]
+// NOTE: This is an autogenerated screenshot. Do not edit it directly.
+
+The following action variables are specific to the tracking containment rule.
+You can also specify <<rule-action-variables,variables common to all rules>>.
+
+`context.containingBoundaryId`::
+The identifier for the boundary containing the entity.
+This value is not set for recovered alerts.
+
+`context.containingBoundaryName`::
+The name of the boundary containing the entity.
+This value is not set for recovered alerts.
+
+`context.detectionDateTime`::
+The end of the check interval when the alert occurred.
+
+`context.entityDateTime`::
+The date the entity was recorded in the boundary.
+
+`context.entityDocumentId`::
+The identifier for the contained entity document.
+
+`context.entityId`::
+The entity identifier for the document that generated the alert.
+
+`context.entityLocation`::
+The location of the entity.
diff --git a/docs/user/alerting/rule-types/index-threshold.asciidoc b/docs/user/alerting/rule-types/index-threshold.asciidoc
@@ -79,7 +79,7 @@ For example:
 image::user/alerting/images/rule-types-index-threshold-example-action.png[UI for defining an action for each alert]
 // NOTE: This is an autogenerated screenshot. Do not edit it directly.
 
-You can further refine the conditions under which actions run by specifying that actions only run they match a KQL query or when an alert occurs within a specific time frame.
+You can further refine the conditions under which actions run by specifying that actions only run when they match a KQL query or when an alert occurs within a specific time frame.
 
 [float]
 [[action-variables-index-threshold]]

diff --git a/x-pack/plugins/alerting/docs/openapi/bundled.json b/x-pack/plugins/alerting/docs/openapi/bundled.json
@@ -67,6 +67,9 @@
                 },
                 "createIndexThresholdRuleRequest": {
                   "$ref": "#/components/examples/create_index_threshold_rule_request"
+                },
+                "createTrackingContainmentRuleRequest": {
+                  "$ref": "#/components/examples/create_tracking_containment_rule_request"
                 }
               }
             }
@@ -92,6 +95,9 @@
                   },
                   "createIndexThresholdRuleResponse": {
                     "$ref": "#/components/examples/create_index_threshold_rule_response"
+                  },
+                  "createTrackingContainmentRuleResponse": {
+                    "$ref": "#/components/examples/create_tracking_containment_rule_response"
                   }
                 }
               }
@@ -7362,6 +7368,29 @@
           ]
         }
       },
+      "create_tracking_containment_rule_request": {
+        "summary": "Create a tracking containment rule.",
+        "value": {
+          "consumer": "alerts",
+          "name": "my tracking rule",
+          "params": {
+            "index": "kibana_sample_data_logs",
+            "dateField\"": "@timestamp",
+            "geoField": "geo.coordinates",
+            "entity": "agent.keyword",
+            "boundaryType": "entireIndex",
+            "boundaryIndexTitle": "boundary*",
+            "boundaryGeoField": "location",
+            "boundaryNameField": "name",
+            "indexId": "90943e30-9a47-11e8-b64d-95841ca0b247",
+            "boundaryIndexId": "0cd90abf-abe7-44c7-909a-f621bbbcfefc"
+          },
+          "rule_type_id": ".geo-containment",
+          "schedule": {
+            "interval": "1h"
+          }
+        }
+      },
       "create_es_query_esql_rule_response": {
         "summary": "The create rule API returns a JSON object that contains details about the rule.",
         "value": {
@@ -7630,6 +7659,64 @@
           "updated_by": "elastic"
         }
       },
+      "create_tracking_containment_rule_response": {
+        "summary": "The create rule API returns a JSON object that contains details about the rule.",
+        "value": {
+          "id": "b6883f9d-5f70-4758-a66e-369d7c26012f",
+          "name": "my tracking rule",
+          "tags": [],
+          "enabled": true,
+          "consumer": "alerts",
+          "throttle": null,
+          "revision": 1,
+          "running": false,
+          "schedule": {
+            "interval": "1h"
+          },
+          "params": {
+            "index": "kibana_sample_data_logs",
+            "dateField": "@timestamp",
+            "geoField": "geo.coordinates",
+            "entity": "agent.keyword",
+            "boundaryType": "entireIndex",
+            "boundaryIndexTitle": "boundary*",
+            "boundaryGeoField": "location",
+            "boundaryNameField": "name",
+            "indexId": "90943e30-9a47-11e8-b64d-95841ca0b247",
+            "boundaryIndexId": "0cd90abf-abe7-44c7-909a-f621bbbcfefc"
+          },
+          "rule_type_id": ".geo-containment",
+          "created_by": "elastic",
+          "updated_by": "elastic",
+          "created_at": "2024-02-14T19:52:55.920Z",
+          "updated_at": "2024-02-15T03:24:32.574Z",
+          "api_key_owner": "elastic",
+          "notify_when": null,
+          "mute_all": false,
+          "muted_alert_ids": [],
+          "scheduled_task_id": "b6883f9d-5f70-4758-a66e-369d7c26012f",
+          "execution_status": {
+            "status": "ok",
+            "last_execution_date": "2024-02-15T03:25:38.125Z",
+            "last_duration": 74
+          },
+          "actions": [],
+          "last_run": {
+            "alerts_count": {
+              "active": 0,
+              "new": 0,
+              "recovered": 0,
+              "ignored": 0
+            },
+            "outcome_msg": null,
+            "outcome_order": 0,
+            "outcome": "succeeded",
+            "warning": null
+          },
+          "next_run": "2024-02-15T03:26:38.033Z",
+          "api_key_created_by_user": false
+        }
+      },
       "get_rule_response": {
         "summary": "The get rule API returns a JSON object that contains details about the rule.",
         "value": {

diff --git a/x-pack/plugins/alerting/docs/openapi/bundled.yaml b/x-pack/plugins/alerting/docs/openapi/bundled.yaml
@@ -43,6 +43,8 @@ paths:
                 $ref: '#/components/examples/create_es_query_kql_rule_request'
               createIndexThresholdRuleRequest:
                 $ref: '#/components/examples/create_index_threshold_rule_request'
+              createTrackingContainmentRuleRequest:
+                $ref: '#/components/examples/create_tracking_containment_rule_request'
       responses:
         '200':
           description: Indicates a successful call.
@@ -59,6 +61,8 @@ paths:
                   $ref: '#/components/examples/create_es_query_kql_rule_response'
                 createIndexThresholdRuleResponse:
                   $ref: '#/components/examples/create_index_threshold_rule_response'
+                createTrackingContainmentRuleResponse:
+                  $ref: '#/components/examples/create_tracking_containment_rule_response'
         '401':
           description: Authorization information is missing or invalid.
           content:
@@ -5093,6 +5097,25 @@ components:
           interval: 1m
         tags:
           - cpu
+    create_tracking_containment_rule_request:
+      summary: Create a tracking containment rule.
+      value:
+        consumer: alerts
+        name: my tracking rule
+        params:
+          index: kibana_sample_data_logs
+          dateField": '@timestamp'
+          geoField: geo.coordinates
+          entity: agent.keyword
+          boundaryType: entireIndex
+          boundaryIndexTitle: boundary*
+          boundaryGeoField: location
+          boundaryNameField: name
+          indexId: 90943e30-9a47-11e8-b64d-95841ca0b247
+          boundaryIndexId: 0cd90abf-abe7-44c7-909a-f621bbbcfefc
+        rule_type_id: .geo-containment
+        schedule:
+          interval: 1h
     create_es_query_esql_rule_response:
       summary: The create rule API returns a JSON object that contains details about the rule.
       value:
@@ -5318,6 +5341,57 @@ components:
         throttle: null
         updated_at: '2022-06-08T17:20:31.632Z'
         updated_by: elastic
+    create_tracking_containment_rule_response:
+      summary: The create rule API returns a JSON object that contains details about the rule.
+      value:
+        id: b6883f9d-5f70-4758-a66e-369d7c26012f
+        name: my tracking rule
+        tags: []
+        enabled: true
+        consumer: alerts
+        throttle: null
+        revision: 1
+        running: false
+        schedule:
+          interval: 1h
+        params:
+          index: kibana_sample_data_logs
+          dateField: '@timestamp'
+          geoField: geo.coordinates
+          entity: agent.keyword
+          boundaryType: entireIndex
+          boundaryIndexTitle: boundary*
+          boundaryGeoField: location
+          boundaryNameField: name
+          indexId: 90943e30-9a47-11e8-b64d-95841ca0b247
+          boundaryIndexId: 0cd90abf-abe7-44c7-909a-f621bbbcfefc
+        rule_type_id: .geo-containment
+        created_by: elastic
+        updated_by: elastic
+        created_at: '2024-02-14T19:52:55.920Z'
+        updated_at: '2024-02-15T03:24:32.574Z'
+        api_key_owner: elastic
+        notify_when: null
+        mute_all: false
+        muted_alert_ids: []
+        scheduled_task_id: b6883f9d-5f70-4758-a66e-369d7c26012f
+        execution_status:
+          status: ok
+          last_execution_date: '2024-02-15T03:25:38.125Z'
+          last_duration: 74
+        actions: []
+        last_run:
+          alerts_count:
+            active: 0
+            new: 0
+            recovered: 0
+            ignored: 0
+          outcome_msg: null
+          outcome_order: 0
+          outcome: succeeded
+          warning: null
+        next_run: '2024-02-15T03:26:38.033Z'
+        api_key_created_by_user: false
     get_rule_response:
       summary: The get rule API returns a JSON object that contains details about the rule.
       value:

diff --git a/...s/alerting/docs/openapi/components/examples/create_tracking_containment_rule_request.yaml b/...s/alerting/docs/openapi/components/examples/create_tracking_containment_rule_request.yaml
@@ -0,0 +1,18 @@
+summary: Create a tracking containment rule.
+value:
+  consumer: alerts
+  name: my tracking rule
+  params:
+    index: kibana_sample_data_logs
+    dateField": '@timestamp'
+    geoField: geo.coordinates
+    entity: agent.keyword
+    boundaryType: entireIndex
+    boundaryIndexTitle: boundary*
+    boundaryGeoField: location
+    boundaryNameField: name
+    indexId: 90943e30-9a47-11e8-b64d-95841ca0b247
+    boundaryIndexId: 0cd90abf-abe7-44c7-909a-f621bbbcfefc
+  rule_type_id: .geo-containment
+  schedule:
+    interval: 1h