[role="xpack"]
[[geo-alerting]]
== Tracking containment

<<maps, Maps>> offers the tracking containment rule type which runs an {es} 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.

[float]
=== Requirements
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.

[float]
=== Rule conditions

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

[role="screenshot"]
image::user/alerting/images/alert-types-tracking-containment-conditions.png[Define the condition to detect,width=75%]
// NOTE: This is an autogenerated screenshot. Do not edit it directly.

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.

[float]
=== Actions

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.

[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.
