Alert and Incident Enrichment#

Enrichment is the mechanism for attaching arbitrary key/value metadata to an alert or incident after it has been received. Status changes, ticket links, comments, environment tags, and any custom field are all modeled as enrichments. Enrichments are stored in the AlertEnrichment table — a shared table for both alerts and incidents despite the name — and merged on top of the raw alert event at read time.

Data Model#

AlertEnrichment is the single persistence table for enrichment data:

Each Alert row has a one-to-one relationship back to AlertEnrichment via fingerprint 4. Incidents reuse the same table with the incident UUID as alert_fingerprint 5.

REST API#

POST /alerts/enrich#

The primary enrichment endpoint is enrich_alert in keep/api/routes/alerts.py. Requires write:alert scope.

Request body: { "fingerprint": "<str>", "enrichments": { "<key>": "<value>", ... } }

Query param: dispose_on_new_alert=true makes the enrichment disposable — it is automatically removed when the alert fires again.

Post-enrichment side effects (via _enrich_alert):

1. Calls EnrichmentsBl.enrich_entity() (or disposable_enrich_entity() when dispose_on_new_alert=true) to persist the enrichment 6
2. Re-indexes the enriched alert to Elasticsearch 7
3. Pushes a poll-alerts Pusher event to connected clients 8
4. Triggers workflow evaluation via WorkflowManager.insert_events() when status changes 9
5. Checks incident auto-resolution when status becomes resolved 10

get_enrichment_metadata() classifies each enrichment as one of: MANUAL_RESOLVE, API_AUTOMATIC_RESOLVE, COMMENT, TICKET_ASSIGNED, or GENERIC_ENRICH, and determines whether to trigger workflows or check incident resolution.

POST /alerts/batch_enrich#

Bulk version. Accepts either an explicit fingerprints list or a CEL expression (not both) to resolve target alerts 11. Follows the same side-effect chain as the single endpoint.

POST /alerts/unenrich#

Removes specific enrichment keys from an alert 12.

Business Logic Layer#

EnrichmentsBl (keep/api/bl/enrichments_bl.py) wraps all enrichment DB operations:

• enrich_entity — upserts enrichments persistently.
• disposable_enrich_entity — stores enrichments with a disposable_ prefix and timestamp; they are automatically discarded when a new alert arrives on the same fingerprint.

The actual SQL upserts are delegated to enrich_entity and batch_enrich in keep/api/core/db.py.

Workflow-Driven Enrichment#

Provider actions and steps in workflows can write enrichments back to the triggering entity using enrich_alert or enrich_incident inside with:. Both fields are validated by WithSchema.

enrich_alert supports an optional disposable: bool flag per key-value pair 13. enrich_incident does not 14.

The provider base class extracts these kwargs in notify() and query(), then calls _enrich() which 15:

1. Detects entity type (alert vs. incident) from execution context
2. Resolves the fingerprint/UUID of the entity
3. Evaluates value expressions against the provider result (e.g. results.body.name)
4. Routes to enrich_entity() or disposable_enrich_entity() based on the disposable flag

Example Workflows#

HTTP call → alert enrichment — fetches an external API and maps a response field back to the alert 16:

actions:
  - name: http-action
    provider:
      type: http
      with:
        url: https://api.restful-api.dev/objects/7
        method: GET
        enrich_alert:
          - key: computerName
            value: results.body.name

OpenAI structured output → alert enrichment — uses GPT-4 to infer missing fields, then writes them back to the alert 17:

actions:
  - name: enrich-alert
    provider:
      type: mock
      with:
        enrich_alert:
          - key: environment
            value: "{{ steps.get-enrichments.results.response.environment }}"
          - key: impacted_customer_name
            value: "{{ steps.get-enrichments.results.response.impacted_customer_name }}"

Incident tier escalation — enriches the incident with a current_tier value after each Slack notification, enabling conditional branching on subsequent triggers 18:

enrich_incident:
  - key: current_tier
    value: 0

Static incident metadata — sets fixed fields (environment, incident_id, incident_url, incident_provider) on every incident created/updated event 19.

Key Source Files#