# Content-Based Alert Grouping

Use alert content to group incoming alerts into open incidents

Content-Based Alert Grouping enables custom alert grouping on services with predictable, homogenous alert data, without the need to train an algorithm. Alerts that share an exact match on a set of chosen fields group together into the most recent open incident. Grouped alerts mean fewer incidents and noise reduction, richer context on incidents that do trigger, and lower resolution times.

> **AIOps / Signal Intelligence Feature:** This feature is included with the [PagerDuty AIOps](/ai-automation/aiops/overview) add-on, or included as Signal Intelligence in PD Reliability Platform plans. To sign up for a trial of PagerDuty AIOps features, read [PagerDuty AIOps Trials](/ai-automation/aiops/overview#pagerduty-aiops-trials).

> **AIOps Service Configuration:** Your service configuration must have AIOps enabled to use this feature. AIOps Service Configuration is in Limited General Availability — see [Configurable Service Settings](/incident-management/services/configurable-service-settings#manage-aiops) for more information and enablement steps.

> **Legacy Availability:** Content-Based Alert Grouping is also available with [Legacy Event Intelligence](/ai-automation/aiops/legacy-event-intelligence).
>
>   Note that newer features (e.g., [Global Content-Based Alert Grouping](/ai-automation/aiops/noise-reduction/alert-grouping/global-alert-grouping#alert-content)) are only available to PagerDuty AIOps customers, and are not available on Legacy Event Intelligence plans.
>
>   Contact the [Sales Team](https://www.pagerduty.com/contact-us/#contact-sales) to upgrade your account's pricing plan.

> **Required User Permissions:** Users with the following roles can edit a service's Alert Grouping settings:
>
>   - Account Owner
>   - Admin and Global Admin
>   - User
>   - Manager base role and team roles
>     - Manager team roles can only manage services associated with their team.

## Enable Content-Based Alert Grouping

> **Important Notes:** - Content-Based Alert Grouping requires data to be in [Common Event Format (PD-CEF)](/developer/api/pd-cef).
>   - Alerts only group when all selected fields have an _exact_ match.

1. Select **Services**  →  **Service Directory**  →  click the **name** of the service where you would like to use Content-Based Alert Grouping.
2. Select the **Settings** tab and click **New Grouping** _OR_  **Edit** under the **Reduce Noise** section.
3. Select **Alert Content**.
   1. _Optional_: To group alerts across multiple services, select additional services in the dropdown **Select Services to group the alerts** at the top of the page. Read [Global Alert Grouping](/ai-automation/aiops/noise-reduction/alert-grouping/global-alert-grouping#alert-content) for more information.
4. Select whether you want alerts to group if **All** or **Any** specified fields match.
   - If you select **All**, alerts group when there is an exact match on _every specified field_.
   - If you select **Any**, alerts group when there is an exact match on _at least one of the specified fields_.
5. There are two methods for specifying alert grouping fields:

- Click **See Recent Alerts** to open a pane on the right side of the screen. Select a recently-received alert to see its payload. Click the fields you want to add to your grouping criteria and they are added to your configuration. _OR_
- Select your preferred **Field Name(s)** from dropdown:
  - **Class**
  - **Component**
  - **Group**
  - **Severity**
  - **Source**
  - **Summary**
  - **Custom Details**: To group on the value in a custom field, select **Custom Details** from the dropdown, and enter your **custom field name**. Be sure that your spelling and capitalization exactly match the alert's field. See the [FAQ below](#how-do-i-use-a-nested-custom-details-field-as-part-of-my-content-based-alert-grouping-configuration) for more information on using dot notation to access nested custom detail fields.

![Nested custom details example](/images/kb/634adf5390d5099e639bdff309c3c785ef47a67f78ab496ab933c8391ccf2704-custom_details.webp)
*Nested custom details example*

6. _Optional_: If required, select **Add Field** to add an additional field to match on.
7. Select the [time window](#flexible-time-window) that you would like to group alerts in.
8. Click **Save**.

### Flexible Time Window

You can configure the grouping time window as part of the Content-Based Alert Grouping setting. The time window can be between five minutes and 24 hours. The time window is a rolling window and counted from the most recently grouped alert. The window extends each time an alert is grouped, up to 24 hours, or until the incident is resolved. If an alert comes in after 24 hours, it triggers a new incident.

## Update Content-Based Alert Grouping

After [enabling Content-Based Alert Grouping](#enable-content-based-alert-grouping), you can adjust the grouping criteria at any time.

> **Previously-Saved Criteria will be Ignored:** Note that Content-Based Alert Grouping will ignore any previously-saved criteria and will start grouping alerts into a new incident every time you save. In other words, Content-Based Alert Grouping does not consider any previously-saved criteria when determining whether to group an alert or trigger a new incident.

1. Select **Services**  →  **Service Directory**  →  click the **name** of the service where Content-Based Alert Grouping is in use.
2. Select the **Settings** tab and click  **Edit** under the **Reduce Noise** section.
3. Select **Alert Content**.
4. Make the required changes and click **Save**.

## Disable Content-Based Alert Grouping

To select a different grouping method, or to disable Alert Grouping altogether:

1. In the web app, navigate to **Services**  →  **Service Directory**  →  select the **name** of your desired service.
2. Select the **Settings** tab and click  **Edit** next to **Reduce Noise**.
3. Select the desired grouping method and click **Save**.
   1. Alternatively, you can entirely disable alert grouping on the service by clicking **Delete** and confirming **Delete** again in the modal.

### Delete a Field from Your Matching Criteria

If you have configured more than one field as part of your matching criteria, there is an option to delete the individual fields.

1. Navigate to **Services**  →  **Service Directory**  →  select the **name** of your desired service.
2. Select the **Settings** tab and click  **Edit** next to **Reduce Noise**.
3. To the right of the field(s) you wish to delete, click .

![Delete criteria](/images/kb/5a912b37f08578871313b9fceceb867a9c9d2d3d76317a46026a84fd05c402ad-remove_grouping_field.webp)
*Delete criteria*

4. Click **Save**.

## Email Events

Content-Based Alert Grouping supports email alerts generated through service-level email integrations, as well as [Event Orchestration](/ai-automation/aiops/event-orchestration#send-events-to-global-orchestrations). This includes any alerts that have their `custom_details` field transformed in Event Orchestration's [Event Fields](/ai-automation/aiops/event-orchestration#event-fields) feature. Since email events are not structured in JSON, the format that [Common Event Format (PD-CEF)](/developer/api/pd-cef) requires, there are some differences in how these alerts are handled while configuring Content-Based Alert Grouping on incidents.

### Configuration

While configuring Content-Based Alert Grouping or [Unified Alert Grouping](/ai-automation/aiops/noise-reduction/alert-grouping/unified-alert-grouping), the **See Recent Alerts** option displays a preview of recent alerts. However, if the alert contains a `custom_details` field that was transformed in [Event Orchestration](/ai-automation/aiops/event-orchestration), this field's updated value does not appear in the **See Recent Alerts** preview. The **See Recent Alerts** preview always displays the `custom_details` field as it appeared in the email headers.

### Alerts Table

The [Alerts Table](/incident-management/incidents/alerts/alerts-table) displays email events with its [fields mapped](#field-mapping) to corresponding PD-CEF fields, but does not convert them into CEF events. If you would like to view the email alert in a formatted view, click **View Message** below an expanded alert in the Alerts Table.

### Field Mapping

Content-Based Alert Grouping maps some email fields to a corresponding [Common Event Format (PD-CEF)](/developer/api/pd-cef) field. For example, if you are grouping based on **Source**, Content-Based Alert Grouping uses the email event's **From** field to consider a match. With this in mind, it shows in the incident timeline that the alert was added based on **Source**. The table below shows a complete list of email fields and their corresponding PD-CEF fields:

| Email Field                     | PD-CEF Field                                                                                                                                        |
| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
| From                            | Source                                                                                                                                              |
| Subject                         | Summary                                                                                                                                             |
| Subject                         | `custom_details.subject` (This field always contains the original email subject, even if the Summary field was transformed in Event Orchestration.) |
| Text Body                       | `custom_details.plain_body`                                                                                                                         |
| HTML Body (in multipart emails) | `custom_details.html_body`                                                                                                                          |
| To                              | `custom_details.to` (i.e., an array of 1  or more recipients)                                                                                       |
| CCs                             | `custom_details.cc`                                                                                                                                 |
| Email Headers                   | `custom_details.<header_name>` (e.g., `message-id`, `from`, `received` `content-type`, as well as an any custom headers the mailer adds)            |

## FAQ

**If I select `Any` for field matching criteria and the following occurs: Alert A has an exact match with Alert B on one specified field; Alert B has an exact match with Alert C on a different field; Alert C has no matching fields with Alert A. How are alerts grouped?**

Alert A and B would group into one incident. It would create a new incident for Alert C. Content-Based Alert Grouping does not chain fields with subsequent alerts, and alerts group into the most recent incident where there is an exact match.

**How do I use a nested Custom Details field as part of my Content-Based Alert Grouping configuration?**

Use dot notation to specify nested **Custom Details** fields, such as `field_name.nested_field1`. **Note**: Dot notation will only work if your field is nested within an object (not a string). For example, if your custom details look like `{"field_name": "nested_field1 = value, nested_field2 = value"}` , entering `field_name.nested_field1` will _not_ allow you to group on the nested field. If you want to group on a value from a string, you can extract it using [Event Orchestration](/ai-automation/aiops/event-orchestration#event-fields).

**Can I manipulate or merge content of different fields to use as alert grouping criteria?**

Yes, with [Event Orchestration](/ai-automation/aiops/event-orchestration).

**Can I use Content-Based Alert Grouping to group across multiple services?**

Yes, read [Global Alert Grouping](/ai-automation/aiops/noise-reduction/alert-grouping/global-alert-grouping) for more information about how to group alerts from multiple services into a single incident.

<br />