Alert aggregation

Introduction

The alert aggregation functionality is a powerful feature that enables you to obtain a comprehensive count of various alert types stored in metrics. This feature is particularly useful when dealing with large volumes of alerts, as it allows for a more organized and efficient way of managing them.

In addition to providing a total count, the alert aggregation functionality also allows filtering this aggregation based on the tags associated with the alerts and metrics. This means you can narrow your results to specific categories, making it easier to analyze and respond to the most relevant alerts.

Before you begin

To use the alert aggregation feature, your environment configuration must enable 'Metrics' and 'Aggregation'. If not, the feature will be disabled. Additionally, in the ruleset where you're generating the alerts, you must enable 'save metrics' in the version settings.

Calling the alert aggregation API

The request to the api/alert/aggregate endpoint should be a POST request with a JSON object in the body containing the RuleSetId. The request's header must include an 'Authorization' field with a system API key and a 'Content-Type' field set to 'application/json'.

Here's an example of how to call the API using cURL:

curl -X POST http://localhost:53770/api/alert/aggregate \
-H 'Content-Type: application/json' \
-H 'Authorization: your-api-key' \
-d '{
    "ruleSetId": "your-rule-set-id"
}'

Filtering the aggregation using tags

When executing a ruleset, you have the option to add tags. These tags are then stored with the metrics and can be used to filter the aggregated alerts. It is important to note that metrics are saved for a unique set of tags. This means that if you execute the ruleset with the same tags multiple times, the metrics will be overwritten and not added.

Tags are an ordered list with a maximum of 5 strings, and the order in which they appear in the list matters. The aggregation will match alerts based on the order of the tags in the list. For instance, if your tag list is ['customer-id', 'customer-group-1'], the aggregation will only include alerts with both tags in the same order.

Here's an example of a cURL command to call the API with tags:

curl -X POST http://localhost:53770/api/alert/aggregate \
-H 'Content-Type: application/json' \
-H 'Authorization: your-api-key' \
-d '{
    "ruleSetId": "your-rule-set-id",
    "tags": [null, "customer-group-1"]
}'

Note that the first tag in the list is null. This means that the aggregation will include all alerts with the second tag in the list, regardless of the first tag.

Additionally, a tag can be pipe-separated to include multiple values. For example, if you have a tag list of ['customer-id-1|customer-id-2', 'customer-group-1'], the aggregation will consist of alerts that have either "customer-id-1" or "customer-id-2" as the first tag, and "customer-group-1" as the second tag.

Using tags in a workflow

You can also incorporate tags within your workflow to improve the management of metrics and alerts. This is achieved by assigning values to Workflow.tags within the specific workflow step that generates the alerts.

For example:

Workflow.tags = ['customer-id-1', 'customer-group-1']

In this example, the tags "customer-id-1" and "customer-group-1" are assigned within the workflow step and added to the metric after execution. This allows you to set tags based on the rules defined within the workflow, providing a dynamic way to categorize and manage the alerts.