Mapping

Keep's Alert Mapping enrichment feature provides a powerful mechanism for dynamically enhancing alert data by leveraging external data sources, such as CSV files and topology data. This feature allows for the matching of incoming alerts to specific records in these data sources based on predefined attributes (matchers) and enriching those alerts with additional information from the matched records.

For more information on the base feature, you can refer to the official Keep documentation.

Introduction ¶

In complex monitoring environments, raw alert data often lacks the necessary context for effective analysis and response. Keep's Alert Mapping and Enrichment enables you to define rules that match alerts to rows in a CSV file or topology data, appending or modifying alert attributes with values from the matching rows. This process adds significant value to each alert, providing deeper insights and enabling more precise, informed decision-making.

How It Works ¶

Mapping with CSV Files ¶

1. Rule Definition: Users define mapping rules that specify which alert attributes (matchers) should be used for matching alerts to rows in a CSV file.
2. CSV File Specification: A CSV file is associated with each mapping rule. This file contains the additional data that should be added to alerts matching the rule.
3. Alert Matching: When an alert is received, the system checks if it matches the conditions of any mapping rule based on the specified matchers.
4. Data Enrichment: If a match is found, the alert is enriched with additional data from the corresponding row in the CSV file.

CSV Mapping: Matchers vs Enrichment ¶

Example CSV

How it works:

1. Match row: - Matcher columns = lookup keys. - Here: region. - Alert.region must match a row. No match = no change.

2. Enrich: - All non-matcher columns in the matched row are added or overwrite existing fields (unless rule is add-if-missing). - Blank cells skipped.

3. Example: - Input: { "region": "us-east-1" } - Output: { "region": "us-east-1", "responsible_team": "team-alpha", "severity_override": "high" }

Notes: - Multiple matchers = all must match (AND). - Pre-formatting on: added fields (e.g. responsible_team) can be used immediately for dedupe/routing.

In short: - Matcher columns choose the row. - Enrichment columns supply the data you inject.

Mapping with Topology Data ¶

The process is similar when using topology data, allowing you to enrich alerts with information about service dependencies, component relationships, and more.

1. Rule Definition: Define mapping rules with matchers that correspond to attributes in your topology data.
2. Topology Data Association: The rule is linked to your environment's topology data.
3. Alert Matching & Enrichment: When an alert matches, it is enriched with contextual data from the corresponding topology entity.

What is Pre-formatting? ¶

Think of Pre-formatting as a "first step" for your alerts.

Normally, Keep does this:

1. Deduplicate: Checks if an incoming alert is a duplicate of an existing one.
2. Enrich: Adds extra information (like a team name) to the alert.

When you enable Pre-formatting, Keep reverses this order:

1. Enrich: Immediately adds extra information to the incoming alert.
2. Deduplicate: Then utilizes the enriched tags to check if the newly enriched alert is a duplicate.

This is useful because you can group alerts based on information that wasn't in the original alert.

Simple Example: Grouping Alerts by Team ¶

Imagine you want to group all alerts for "Team-A" together, but your alerts only contain a server name.

The Problem: You receive two alerts from different servers, but both servers belong to Team-A.

• Alert 1: {"server": "web-01", "error": "CPU high"}
• Alert 2: {"server": "web-02", "error": "Memory low"}

Without Pre-formatting, Keep sees these as two different alerts because the server names are different.

The Solution with Pre-formatting:

1. Create a simple mapping file (teams.csv): This file links servers to teams.

2. Create a Mapping Rule in Keep:

• Matcher: Use the server field from the alert.
• Data Source: Use the teams.csv file.
• Enable the "Pre-formatting" option.

3. Set Deduplication:

• Group alerts by the responsible_team field.

How It Works Now:

1. Alert 1 (server: "web-01") arrives. * Pre-formatting runs first: Keep looks up web-01 in the CSV and adds responsible_team: "Team-A" to the alert. * Deduplication runs: Keep creates a new alert for Team-A.

2. Alert 2 (server: "web-02") arrives. * Pre-formatting runs first: Keep looks up web-02 and also adds responsible_team: "Team-A". * Deduplication runs: Keep sees this alert is also for Team-A. It finds the existing alert and merges this new event into it.

The Result:

You get one single, consolidated alert for Team-A that contains information from both web-01 and web-02, instead of two separate alerts. This makes it much easier for Team-A to see the full picture.

Core Concepts ¶

• Matchers: Attributes within the alert (e.g., service, region) used to find a matching row in the CSV file or topology data.
• Enrichment: The process of adding new attributes or modifying existing ones in an alert based on the matched data.
• Pre-formatting: An optional setting that applies mapping enrichment before deduplication, enabling enriched data to be used in deduplication logic.