IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Elasticsearch query Troubleshooting and limitations »

› › ›

Tracking containment

edit

Tracking containment

edit

Maps offers the tracking containment rule type which runs an Elasticsearch query over indices to determine whether any documents are currently contained within any boundaries from the specified boundary index. In the event that an entity is contained within a boundary, an alert may be generated.

Requirements

edit

To create a tracking containment rule, the following requirements must be present:

Tracks index or data view: An index containing a geo_point field, date field, and some form of entity identifier. An entity identifier is a keyword or number field that consistently identifies the entity to be tracked. The data in this index should be dynamically updating so that there are entity movements to alert upon.
Boundaries index or data view: An index containing geo_shape data, such as boundary data and bounding box data. This data is presumed to be static (not updating). Shape data matching the query is harvested once when the rule is created and anytime after when the rule is re-enabled after disablement.

By design, current interval entity locations (current is determined by date in the Tracked index or data view) 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.

Create the rule

edit

Fill in the rule details, then select Tracking containment.

Define the conditions

edit

Tracking containment rules have 3 clauses that define the condition to detect, as well as 2 Kuery bars used to provide additional filtering context for each of the indices.

Five clauses define the condition to detect

Index (entity): This clause requires an index or data view, a time field that will be used for the time window, and a geo_point field for tracking.
When entity: This clause specifies which crossing option to track. The values Entered, Exited, and Crossed can be selected to indicate which crossing conditions should trigger a rule. Entered alerts on entry into a boundary, Exited alerts on exit from a boundary, and Crossed alerts on all boundary crossings whether they be entrances or exits.
Index (Boundary): This clause requires an index or data view, a geo_shape field identifying boundaries, and an optional Human-readable boundary name for better alerting messages.

Add action

edit

Conditions for how a rule is tracked can be specified uniquely for each individual action. A rule can be triggered either when a containment condition is met or when an entity is no longer contained.

Known issues

edit

There is a known issue in 8.5 and 8.6 that results in corruption of the rule definition when you update API keys or add or remove snooze schedules in Stack Management > Rules and Connectors. In particular, this bug affects Elasticsearch query rules with the KQL or Lucene query type and tracking containment rules. As a result of this bug, an "Unable to load rules" error occurs in Rules and Connectors.

The long-term solution is to migrate to the latest release; 8.7 and later releases contain the fix for this bug. If you encounter this bug in 8.5, you can recover access to your rules in Kibana by using APIs to delete and recreate them:

Find the affected rules. For example, run the following query in Dev Tools:

GET .kibana*/_search
{
  "query": {
    "bool": {
      "filter": [
        {
          "terms": {
            "alert.alertTypeId": [
              ".es-query",
              ".geo-containment"
            ]
          }
        }
      ],
      "must_not": {
        "exists": {
          "field": "references"
        }
      }
    }
  }
}

Make a copy of the query output, since you will use it to recreate the rules.
Delete the affected rules. For example, run the following query in Dev Tools, replacing <rule_id> with the appropriate rule identifiers:
```
DELETE kbn:/api/alerting/rule/<rule_id>
```
Recreate the rules. For example, use Stack Management > Rules and Connectors or the create rule API with the property values obtained from your query output.

If you update the API keys or add or remove snooze schedules again, the problem will re-occur until you upgrade to a release that contains the fix.

« Elasticsearch query Troubleshooting and limitations »