Merge branch 'main' into feat-app-dynamics

docs/mint.json

@@ -33,7 +33,10 @@
         "overview/presets",
         {
           "group": "Enrichments",
-          "pages": ["overview/enrichment/mapping"]
+          "pages": [
+            "overview/enrichment/extraction",
+            "overview/enrichment/mapping"
+          ]
         },
         "overview/examples",
         "overview/comparison"
@@ -82,8 +85,7 @@
             "providers/documentation/aks-provider",
             "providers/documentation/axiom-provider",
             "providers/documentation/azuremonitoring-provider",
-            "providers/documentation/cloudwatch-logs",
-            "providers/documentation/cloudwatch-metrics",
+            "providers/documentation/cloudwatch-provider",
             "providers/documentation/console-provider",
             "providers/documentation/datadog-provider",
             "providers/documentation/ilert-provider",

docs/overview/enrichment/extraction.mdx

@@ -0,0 +1,47 @@
+---
+title: "Extraction"
+---
+
+# Alert Enrichment: Extraction
+
+Keep's Alert Extraction enrichment feature enables dynamic extraction of data from incoming alerts using regular expressions. This powerful tool allows users to define extraction rules that identify and extract data based on patterns, enriching alerts with additional structured data derived directly from alert content.
+
+## Introduction
+
+Handling a variety of alert formats and extracting relevant information can be challenging. Keep's Alert Extraction feature simplifies this process by allowing users to define regex-based rules that automatically extract key pieces of information from alerts. This capability is crucial for standardizing alert data and enhancing alert context, which facilitates more effective monitoring and response strategies.
+
+## How It Works
+
+1. **Rule Definition**: Users create extraction rules specifying the regex patterns to apply to certain alert attributes.
+2. **Attribute Specification**: Each rule defines which attribute of the alert should be examined by the regex.
+3. **Data Extraction**: When an alert is received, the system applies the regex to the specified attribute. If the pattern matches, named groups within the regex define new attributes to be extracted and added to the alert.
+4. **First Match Enforcement**: The extraction process is designed to stop after the first successful match. Once a rule successfully applies and enriches the alert, no further rules are processed. This ensures efficiency and prevents overlapping or redundant data extraction.
+5. **Alert Enrichment**: Extracted values are added to the alert, enhancing its data with additional attributes for improved analysis.
+
+## Practical Example
+
+Suppose you receive alerts with a message attribute formatted as "Error 404: Not Found - [UserID: 12345]". You can define an extraction rule with a regex such as `Error (?P<error_code>\d+): (?P<error_message>.+) - \[UserID: (?P<user_id>\d+)\]` to extract `error_code`, `error_message`, and `user_id` as separate attributes in the alert.
+
+## Core Concepts
+
+- **Regex (Regular Expression)**: A powerful pattern-matching syntax used to identify specific patterns within text. In the context of extraction rules, regex is used to define how data should be extracted from alert attributes. It is crucial that regex patterns adhere to [Python's regex syntax](https://docs.python.org/3.11/library/re.html#match-objects), especially concerning group matching using named groups.
+- **Attribute**: The part of the alert data (e.g., message, description) that the regex is applied to.
+- **Named Groups**: Part of the regex pattern that specifies placeholders for extracting specific data points into new alert attributes.
+
+## Creating an Extraction Rule
+
+To create an alert extraction rule:
+
+<Frame width="100" height="200">
+  <img height="10" src="/images/extraction-rule-creation.png" />
+</Frame>
+
+1. **Select the Attribute**: Choose which attribute of the alert should be examined by the regex.
+2. **Define the Regex**: Write a regex pattern with named groups that specify what information to extract. Ensure the regex is valid according to Python’s regex standards, particularly for group matching.
+3. **Configure Conditions**: Optionally, specify conditions under which this rule should apply, using CEL (Common Expression Language) for complex logic.
+
+## Best Practices
+
+- **Test Regex Patterns**: Before deploying a new extraction rule, thoroughly test the regex pattern to ensure it correctly matches and extracts data according to Python's regex standards.
+- **Monitor Extraction Performance**: Keep track of how extraction rules are performing and whether they are enriching alerts as expected. Adjust patterns as necessary based on incoming alert data.
+- **Use Specific Conditions**: When applicable, define conditions to limit when extraction rules apply, reducing unnecessary processing and focusing on relevant alerts.

docs/providers/documentation/cloudwatch-provider.mdx

@@ -0,0 +1,108 @@
+---
+title: "CloudWatch"
+sidebarTitle: "CloudWatch Provider"
+description: "CloudWatch provider enables seamless integration with AWS CloudWatch for alerting and monitoring, directly pushing alarms into Keep."
+---
+
+## Overview
+
+The CloudWatch Provider offers a direct integration with AWS CloudWatch, enabling Keep users to receive CloudWatch alarms within the Keep platform. This integration centralizes the monitoring and alerting capabilities, allowing for timely responses to changes in the infrastructure or application health.
+
+### Key Features:
+
+- **Webhook Integration**: Facilitates automatic subscription to AWS SNS topics linked with CloudWatch alarms, ensuring that Keep is notified of all relevant alarms.
+- **Support for Custom SNS Topics**: Allows the use of both pre-existing SNS topics and the specification of custom SNS topics for alarm notifications.
+- **Broad Monitoring Scope**: Utilizes CloudWatch's comprehensive alarm system to monitor application and infrastructure health.
+- **Adaptable Authentication**: Accommodates both permanent and temporary AWS credentials to suit various security and operational requirements.
+
+## Connecting with the Provider
+
+To integrate CloudWatch with Keep, you'll need the following:
+
+- An AWS account with permissions to access CloudWatch and SNS services.
+- A configured Keep account with API access.
+- Appropriate AWS IAM permissions for the CloudWatch provider.
+
+## Required AWS IAM Permissions (Scopes)
+
+To ensure the CloudWatch provider operates seamlessly, certain AWS IAM permissions (referred to as "scopes") are necessary. These scopes enable the provider to perform actions such as reading alarm details, updating alarm configurations, and subscribing to SNS topics. Below is a list of the required scopes along with explanations:
+
+### Mandatory Scopes
+
+- **`cloudwatch:DescribeAlarms`**
+  - **Description**: Necessary to retrieve information about CloudWatch alarms.
+  - **Documentation**: [API_DescribeAlarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_DescribeAlarms.html)
+  - **Alias**: Describe Alarms
+  - **Mandatory**: Yes
+  - This scope is crucial for the provider to fetch and list all CloudWatch alarms.
+
+### Optional Scopes
+
+- **`cloudwatch:PutMetricAlarm`**
+  - **Description**: Required to update alarm configurations, particularly to add Keep as an SNS action on alarms.
+  - **Documentation**: [API_PutMetricAlarm](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricAlarm.html)
+  - **Alias**: Update Alarms
+  - This scope allows the modification of existing CloudWatch alarms to integrate with Keep notifications.
+
+- **`sns:ListSubscriptionsByTopic`**
+  - **Description**: Allows listing all subscriptions for a given SNS topic, enabling Keep to subscribe itself.
+  - **Documentation**: [SNS Access Policy](https://docs.aws.amazon.com/sns/latest/dg/sns-access-policy-language-api-permissions-reference.html)
+  - **Alias**: List Subscriptions
+  - Essential for the provider to manage subscriptions to SNS topics for alarm notifications.
+
+- **`logs:GetQueryResults`**
+  - **Description**: Required for retrieving the results of CloudWatch Logs Insights queries.
+  - **Documentation**: [API_GetQueryResults](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_GetQueryResults.html)
+  - **Alias**: Read Query Results
+  - Enables the provider to fetch query results from CloudWatch Logs Insights.
+
+- **`logs:DescribeQueries`**
+  - **Description**: Necessary to describe the results of CloudWatch Logs Insights queries.
+  - **Documentation**: [API_DescribeQueries](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_DescribeQueries.html)
+  - **Alias**: Describe Query Results
+  - This scope is used to access detailed information about queries executed in CloudWatch Logs Insights.
+
+- **`logs:StartQuery`**
+  - **Description**: Allows starting CloudWatch Logs Insights queries.
+  - **Documentation**: [API_StartQuery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html)
+  - **Alias**: Start Logs Query
+  - Critical for initiating logs analysis and queries within CloudWatch Logs Insights.
+
+- **`iam:SimulatePrincipalPolicy`**
+  - **Description**: Permits Keep to test the scopes of the current IAM role without making any resource modifications.
+  - **Documentation**: [API_SimulatePrincipalPolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_SimulatePrincipalPolicy.html)
+  - **Alias**: Simulate IAM Policy
+  - This scope is useful for verifying the permissions associated with the IAM role used by Keep, ensuring it has the necessary access without altering any AWS resources.
+
+<Tip>While some scopes are optional, having them configured can enhance the integration capabilities and provide a more comprehensive monitoring solution within Keep.</Tip>
+
+### Authentication Configuration
+
+Connecting CloudWatch to Keep requires:
+
+- **AWS Access Key & Secret**: Your AWS credentials with access to CloudWatch and SNS.
+- **Region**: The AWS region your CloudWatch alarms and SNS topics reside in.
+- **Session Token** (optional): Necessary for temporary AWS credentials.
+- **CloudWatch SNS Topic** (optional): An ARN or name of the SNS topic for sending notifications. Optional if your alarms are already configured with an SNS topic.
+
+## Setting Up the Integration
+
+<Tip>For a seamless setup process, ensure your AWS IAM roles are properly configured with the necessary permissions for CloudWatch and SNS access.</Tip>
+
+### Steps:
+
+1. **Configure AWS IAM Roles**: Ensure the IAM role used by the CloudWatch provider has permissions for `cloudwatch:DescribeAlarms`, `cloudwatch:PutMetricAlarm`, `sns:ListSubscriptionsByTopic`, and other relevant actions.
+2. **Specify Authentication Details**: In the Keep platform, enter the AWS Access Key, Secret, and Region details in the CloudWatch provider configuration.
+3. **Set Up SNS Topic (Optional)**: If using a custom SNS topic, specify its ARN or name in the provider configuration. Keep will use this topic to listen for alarm notifications.
+4. **Activate the Provider**: Finalize the setup in Keep to start receiving CloudWatch alarms.
+
+## Troubleshooting
+
+- Ensure the AWS credentials provided have the correct permissions and are not expired.
+- Verify that the SNS topics are correctly configured to send notifications to Keep.
+- Check the CloudWatch alarms to ensure they are active and correctly configured to trigger under the desired conditions.
+
+## Useful Links
+
+- [AWS CloudWatch Documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)
+- [AWS SNS Documentation](https://docs.aws.amazon.com/sns/latest/dg/welcome.html)