elastic / elastic/docs-content

Docs: explain catch-up search window before gaps are recorded (monitor-rule-executions / fill-rule-gaps)

Open
#7,708 1 comment 0 reactions 0 assignees View on GitHub
Team:SKI
Dominant language
No language data
Stars
47
Forks
261
Avg merge
3d 12h
Merged PRs (30d)
116

Description

## Summary

The [Monitor rule executions](https://www.elastic.co/docs/solutions/security/detect-and-alert/monitor-rule-executions#scheduling-and-gaps) and [Fill rule gaps](https://www.elastic.co/docs/solutions/security/detect-and-alert/fill-rule-gaps) pages don't mention that a delayed rule automatically expands its search window to cover missed periods before a Gap is recorded.

Users [might see](https://github.com/elastic/sdh-security-team/issues/1770#issuecomment-5167442726) a **scheduling delay** past the execution interval but an **empty gap duration** and empty gaps table, and don't understand why — they assume data coverage was lost.

## What's missing

When a rule runs late, the Security wrapper adds up to **4 catch-up windows** (each one `interval`-wide, stepped back in time) before declaring a Gap. Only drift beyond that ceiling becomes a recorded Gap.

**Example** — rule with 5 min interval, 1 min lookback (`from: now-6m`):

| Delay since last run | What happens |
|---|---|
| Up to ~26 min | Catch-up covers the missed period; Gap = 0 |
| > 26 min | Partial catch-up (4 × 5 min); remaining drift recorded as a Gap |

Concretely: if the previous run was at 11:31 and the next fires at 11:45 (14 min later), the rule silently folds two catch-up windows into that single execution and reports zero Gap, even though it appeared to "skip" the 11:35 and 11:40 slots.

## Suggested addition

On the **Scheduling and gaps** section of the monitor-rule-executions page (or as a callout on the fill-rule-gaps page), add a short explanation along these lines:

> **Catch-up coverage:** If a rule runs late, it automatically extends its search window backward in time - up to four additional intervals - to cover any missed period. A gap is only recorded when the delay exceeds this catch-up capacity (4 × interval). A small scheduling delay with an empty gap duration is therefore expected behavior, not a sign of missed detections.

## References

- SDH ticket: elastic/sdh-security-team#1770
- Kibana source: `MAX_RULE_GAP_RATIO = 4` in [`utils.ts`](https://github.com/elastic/kibana/blob/f4a49f3df5d3d78aacb27004c22a7e8a69688187/x-pack/solutions/security/plugins/security_solution/server/lib/detection_engine/rule_types/utils/utils.ts#L222)
- Existing docs pages to update:
- https://www.elastic.co/docs/solutions/security/detect-and-alert/monitor-rule-executions#scheduling-and-gaps
- https://www.elastic.co/docs/solutions/security/detect-and-alert/fill-rule-gaps

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the Scheduling and gaps section of the Monitor rule executions page and the Fill rule gaps page, then review the referenced Kibana utils.ts location and SDH ticket for context. Add a concise explanation of the four-window catch-up behavior, using the provided example, and verify that the pages explain why small delays can show empty gaps.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.