How Significant Events works

This page describes the pipeline behavior for engineers and adopters who need to understand how Significant Events processes data, what runs where, and how to trace results across the system.

The pipeline has four sequential phases, each building on the outputs of the previous:

KIs are stable, evidence-backed facts about the services and infrastructure present in a stream's log data. The LLM that generates detection operates entirely on KIs. This keeps rule generation deterministic and decouples detection logic from data format specifics.

The pipeline runs up to five iterations, sampling up to 20 documents per round from entity-filtered, diverse, and random buckets. KIs found in one iteration are excluded from the next, steering each round toward undiscovered patterns. LLM analysis and deterministic code generators run in parallel; deterministic KIs always score 100 confidence. See KI extraction for the full extraction flow.

KIs cover five types: Entity, Infrastructure, Technology, Dependency, and Schema. The model is instructed to prioritize services and databases over individual instances like pods or hosts. See KI types for the full data model.

KIs are written to .significant_events-knowledge_indicators and deduplicated on type, subtype, and properties. KIs expire after 30 days if they aren't re-observed. See KI lifecycles for lifecycle and continuous extraction details.

Once a stream has KIs, the LLM generates detection rules using the KIs as input. The generated rule is an ES|QL query with conditions derived from the stream's KIs:

FROM {stream},{stream}.* METADATA _id | WHERE <esql_expression>

The LLM operates in a reasoning loop: it calls get_stream_features to retrieve KIs for the stream, analyzes what entities and technologies are present, then calls add_queries to submit a batch of rules. This means rules are scoped to the specific services and failure modes present in each stream.

Each promoted MATCH rule runs as an alerting rule on a single shared cadence of every 5 minutes with a 7-minute lookback. Each run writes compact metric series ({ bucket, metric_value } pairs) to .rule-events, not copies of matching source documents.

The 7-minute lookback on a 5-minute cadence means adjacent runs cover the same minutes. Readers use MAX(metric_value) per minute when building occurrence charts and change-point input, so overlapping runs don't double-count.

Severity and cadence: All MATCH rules share the same 5-minute cadence with a 7-minute lookback schedule. Severity drives the detection analysis profile applied in Phase 4: the lookback window and bucket size used for change-point analysis (critical: ~40m window / 1m buckets; default: ~125m window / 5m buckets).

STATS rules: STATS KIs are generated but not yet backed as alerting rules.

Discovery converts raw alert signals into confirmed significant events in two stages:

  • Detection Workflow: Change point aggregation per alerting rule, written to the detections index
  • Discovery Workflow: Discovery agent generates hypotheses, performs triage, and promotes confirmed significant events

A Detection workflow reads .rule-events, buckets each rule's alerts by time, and runs the change point aggregation function against those counts to detect statistically significant shifts. When a shift is found, a document is appended to the detections index. The most recent detection document for a rule reflects its current state, for example, whether it's still producing an unusual rate of alerts or has returned to normal.

Change point detection is per-rule. A stream can have many independent rules, and one rule recovering doesn't collapse the signal from others still anomalous on the same stream.

A Discovery workflow reads unhandled detection documents and calls the Discovery agent. The Discovery agent reads detection signals, produces structured discovery documents describing what is happening, and performs triage on its own findings: it verifies each hypothesis and sets the event status to open (page on-call), closed (confirmed settled), or dismissed (low severity and low confidence). Status transitions are written as alert documents to .rule-events.

Significant events are also written as alerts, so they can be managed, routed, and acted on like any other Elastic alert.

ES|QL is the exclusive query language across the pipeline. Every rule is expressed as ES|QL. Every artifact is stored as an Elasticsearch document. This means any point in the pipeline is queryable without leaving ES|QL.

What to query ES|QL target
Knowledge Indicators FROM .significant_events-knowledge_indicators
Alert documents (rule execution results) FROM .rule-events
Detection state per rule FROM .significant_events-detections
Significant events FROM .rule-events

Traceability: Significant-event alert documents are stored in .rule-events. Use group_hash to group versions of the same event. Queries must filter to alert documents from the Significant Events source.