elastic / elastic/docs-content
Docs: explain catch-up search window before gaps are recorded (monitor-rule-executions / fill-rule-gaps)
- 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