From 290612e366ea7b363174fdbd45249e0719842bdc Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Wed, 6 Nov 2024 15:28:44 +0100 Subject: [PATCH] Alerting docs: specify using multiple contact point integrations in the UI and HTTP API (#95890) * Sort list of contact points on the sidebar * Update `Configure contact points` to clarify contact point integrations * Alerting HTTP API: fix `EmbeddedContactPoint` properties table * HTTP Alerting API: clarify how `ContactPoint.name` groups contact points * Update docs/sources/alerting/configure-notifications/manage-contact-points/_index.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> --------- Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> --- .../manage-contact-points/_index.md | 79 ++++++++++--------- .../integrations/configure-amazon-sns.md | 2 +- .../integrations/configure-discord.md | 2 +- .../integrations/configure-email.md | 2 +- .../integrations/configure-google-chat.md | 2 +- .../integrations/configure-mqtt.md | 4 +- .../integrations/configure-oncall.md | 2 +- .../integrations/configure-opsgenie.md | 2 +- .../integrations/configure-slack.md | 2 +- .../integrations/configure-teams.md | 2 +- .../integrations/configure-telegram.md | 2 +- .../integrations/pager-duty.md | 2 +- .../integrations/webhook-notifier.md | 4 +- .../shared/alerts/alerting_provisioning.md | 25 +++--- 14 files changed, 68 insertions(+), 64 deletions(-) diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/_index.md b/docs/sources/alerting/configure-notifications/manage-contact-points/_index.md index 7ab9ffe5385..3daab96de2e 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/_index.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/_index.md @@ -26,6 +26,16 @@ labels: title: Configure contact points weight: 410 refs: + sns: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/configure-notifications/manage-contact-points/integrations/configure-amazon-sns/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/manage-contact-points/integrations/configure-amazon-sns/ + gchat: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/configure-notifications/manage-contact-points/integrations/configure-google-chat/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/manage-contact-points/integrations/configure-google-chat/ email: - pattern: /docs/grafana/ destination: /docs/grafana//alerting/configure-notifications/manage-contact-points/integrations/configure-email/ @@ -81,27 +91,28 @@ refs: destination: /docs/grafana//alerting/configure-notifications/manage-contact-points/integrations/configure-mqtt/ - pattern: /docs/grafana-cloud/ destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/manage-contact-points/integrations/configure-mqtt/ + manage-notification-templates: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/configure-notifications/template-notifications/manage-notification-templates/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/template-notifications/manage-notification-templates/ --- # Configure contact points -Use contact points to select your preferred communication channel for receiving notifications when your alert rules are firing. You can add, edit, delete, export, and test a contact point. +Use contact points to specify where to receive alert notifications. Contact points contain the configuration for sending alert notifications, including destinations like email, Slack, OnCall, webhooks, and their notification messages. -Testing a contact point is only available for Grafana Alertmanager. +A contact point can have one or multiple destinations, known as [contact point integrations](#list-of-supported-integrations). Alert notifications are sent to each integration within the chosen contact point. On the **Contact Points** tab, you can: +- Add, edit, and view contact points and integrations. - Search for name and type of contact points and integrations. -- View all existing contact points and integrations. - View how many notification policies each contact point is being used for and navigate directly to the linked notification policies. - View the status of notification deliveries. - Export individual contact points or all contact points in JSON, YAML, or Terraform format. - Delete contact points. Note that you cannot delete contact points that are in use by a notification policy. To proceed, either delete the notification policy or update it to use another contact point. -On the **Notification templates** tab, you can: - -- View, edit, copy or delete existing notification templates. - ## Add a contact point Complete the following steps to add a contact point. @@ -114,41 +125,23 @@ Complete the following steps to add a contact point. 1. From **Integration**, select a type and fill out mandatory fields. For example, if you choose email, enter the email addresses. Or if you choose Slack, enter the Slack channel and users who should be contacted. 1. Some contact point integrations, like email or Webhook, have optional settings. In **Optional settings**, specify additional settings for the selected contact point integration. 1. In Notification settings, optionally select **Disable resolved message** if you do not want to be notified when an alert resolves. -1. To add another contact point integration, click **Add contact point integration** and repeat steps 6 through 8. 1. Save your changes. -## Use notification templates - -Use templates in contact points to customize your notifications. - -Complete the following steps to add templates to your contact point. - -1. Click an existing contact point or create a new one -1. In **Optional settings**, click any field that contains templates. - - For example, if you are creating an email contact point integration, click **Message** or **Subject**. - -1. Click **Edit**. - A dialog box opens where you can select templates. -1. [Optional] Click **Select existing template** to select a template and preview it using the default payload. - - Click **Save** to use just a single template in the field. +## Add another contact point integration - You can also copy the selected template and use it in the custom tab. +A contact point can have multiple integrations, or destinations for sending notifications. -1. [Optional] Click **Enter custom message** to customize and edit the field directly. Note that the title changes depending on the field you are editing. +To add another integration to a contact point, complete the following steps. - Click **Save** to use just a single template in the field. - -1. You can switch between the two tabs to access the list of available templates and copy them across to the customized version. - -1. Click **Save contact point**. +1. Add or edit an existing contact point. +1. Click **Add contact point integration** and repeat the same steps as [Add a contact point](#add-a-contact-point). + - From **Integration**, select a type and fill out mandatory fields. + - In **Optional settings**, specify additional settings for the selected contact point integration. +1. Save your changes. ## Test a contact point -** For Grafana Alertmanager only.** - -Complete the following steps to test a contact point. +Testing a contact point is only available for Grafana Alertmanager. Complete the following steps to test a contact point. 1. In the left-side menu, click **Alerts & IRM** and then **Alerting**. 1. Click **Contact points** to view a list of existing contact points. @@ -166,17 +159,17 @@ The following table lists the contact point integrations supported by Grafana. | Name | Type | | ---------------------------- | ------------------------- | | Alertmanager | `prometheus-alertmanager` | -| Amazon SNS | `sns` | +| [Amazon SNS](ref:sns) | `sns` | | Cisco Webex Teams | `webex` | | DingDing | `dingding` | | [Discord](ref:discord) | `discord` | | [Email](ref:email) | `email` | -| Google Chat | `googlechat` | +| [Google Chat](ref:gchat) | `googlechat` | | [Grafana Oncall](ref:oncall) | `oncall` | | Kafka REST Proxy | `kafka` | -| [MQTT](ref:mqtt) | `mqtt` | | Line | `line` | | [Microsoft Teams](ref:teams) | `teams` | +| [MQTT](ref:mqtt) | `mqtt` | | [Opsgenie](ref:opsgenie) | `opsgenie` | | [Pagerduty](ref:pagerduty) | `pagerduty` | | Pushover | `pushover` | @@ -185,7 +178,17 @@ The following table lists the contact point integrations supported by Grafana. | [Telegram](ref:telegram) | `telegram` | | Threema Gateway | `threema` | | VictorOps | `victorops` | -| WeCom | `wecom` | | [Webhook](ref:webhook) | `webhook` | +| WeCom | `wecom` | Some of these integrations are not compatible with [external Alertmanagers](ref:external-alertmanager). For the list of Prometheus Alertmanager integrations, refer to the [Prometheus Alertmanager receiver settings](https://prometheus.io/docs/alerting/latest/configuration/#receiver-integration-settings). + +## Customize notification messages + +In contact points, you can also customize notification messages. For example, when setting up an email contact point integration, click **Message** or **Subject** to modify it. + +By default, notification messages include common alert details, which are usually sufficient for most cases. + +If necessary, you can customize the content and format of notification messages. You can create a custom notification template, which can then be applied to one or more contact points. + +On the **Notification templates** tab, you can view, edit, copy or delete notification templates. Refer to [manage notification templates](ref:manage-notification-templates) for instructions on selecting or creating a template for a contact point. diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-amazon-sns.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-amazon-sns.md index e0209ac8f50..84274e64043 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-amazon-sns.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-amazon-sns.md @@ -13,7 +13,7 @@ labels: - oss menuTitle: Amazon SNS title: Configure Amazon SNS for Alerting -weight: 0 +weight: 100 --- # Configure Amazon SNS for Alerting diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-discord.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-discord.md index 399c3b31579..354fed75faf 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-discord.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-discord.md @@ -13,7 +13,7 @@ labels: - oss menuTitle: Discord title: Configure Discord for Alerting -weight: 0 +weight: 105 --- # Configure Discord for Alerting diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-email.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-email.md index a8aacba6623..02db8cf0172 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-email.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-email.md @@ -13,7 +13,7 @@ labels: - oss menuTitle: Email title: Configure email for Alerting -weight: 0 +weight: 110 refs: notification-templates: - pattern: /docs/grafana/ diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-google-chat.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-google-chat.md index b0440d06ff2..712bd1b0cbc 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-google-chat.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-google-chat.md @@ -13,7 +13,7 @@ labels: - oss menuTitle: Google Chat title: Configure Google Chat for Alerting -weight: 0 +weight: 115 --- # Configure Google Chat for Alerting diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-mqtt.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-mqtt.md index 666ea653e18..1c3e06c1243 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-mqtt.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-mqtt.md @@ -12,9 +12,9 @@ labels: - cloud - enterprise - oss -menuTitle: MQTT notifier +menuTitle: MQTT title: Configure the MQTT notifier for Alerting -weight: 0 +weight: 140 --- # Configure the MQTT notifier for Alerting diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-oncall.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-oncall.md index 31c3a028a0b..4052fe57007 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-oncall.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-oncall.md @@ -17,7 +17,7 @@ labels: - oss menuTitle: Grafana OnCall title: Configure Grafana OnCall for Alerting -weight: 0 +weight: 120 --- # Configure Grafana OnCall for Alerting diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-opsgenie.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-opsgenie.md index e1f455af2dc..feb4d406caa 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-opsgenie.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-opsgenie.md @@ -13,7 +13,7 @@ labels: - oss menuTitle: Opsgenie title: Configure Opsgenie for Alerting -weight: 0 +weight: 145 --- # Configure Opsgenie for Alerting diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-slack.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-slack.md index e5821985bf9..8f56174ed60 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-slack.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-slack.md @@ -13,7 +13,7 @@ labels: - oss menuTitle: Slack title: Configure Slack for Alerting -weight: 0 +weight: 155 refs: notification-templates: - pattern: /docs/grafana/ diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-teams.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-teams.md index b788f21c5ff..0dae7c4d038 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-teams.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-teams.md @@ -13,7 +13,7 @@ labels: - oss menuTitle: Microsoft Teams title: Configure Microsoft Teams for Alerting -weight: 0 +weight: 135 refs: notification-templates: - pattern: /docs/grafana/ diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-telegram.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-telegram.md index 1c86f94d0cc..260e05717cc 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-telegram.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-telegram.md @@ -13,7 +13,7 @@ labels: - oss menuTitle: Telegram title: Configure Telegram for Alerting -weight: 0 +weight: 160 --- # Configure Telegram for Alerting diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/pager-duty.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/pager-duty.md index ebfdec1f364..ac5f381464c 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/pager-duty.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/pager-duty.md @@ -14,7 +14,7 @@ labels: - oss menuTitle: PagerDuty title: Configure PagerDuty for Alerting -weight: 0 +weight: 150 --- # Configure PagerDuty for Alerting diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md index f08319ecd50..6562b948095 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md @@ -19,9 +19,9 @@ labels: - cloud - enterprise - oss -menuTitle: Webhook notifier +menuTitle: Webhook title: Configure the webhook notifier for Alerting -weight: 0 +weight: 165 refs: notification-templates: - pattern: /docs/grafana/ diff --git a/docs/sources/shared/alerts/alerting_provisioning.md b/docs/sources/shared/alerts/alerting_provisioning.md index 1ec0fb133f2..a927ae4ce7a 100644 --- a/docs/sources/shared/alerts/alerting_provisioning.md +++ b/docs/sources/shared/alerts/alerting_provisioning.md @@ -1152,6 +1152,8 @@ Status: Bad Request POST /api/v1/provisioning/contact-points ``` +When creating a contact point, the `EmbeddedContactPoint.name` property determines if the new contact point is added to an existing one. In the UI, contact points with the same name are grouped together under a single contact point. + #### Parameters {{% responsive-table %}} @@ -1658,23 +1660,22 @@ Status: Accepted ### EmbeddedContactPoint -> EmbeddedContactPoint is the contact point type that is used -> by grafanas embedded alertmanager implementation. +EmbeddedContactPoint is the contact point type used by Grafana-managed alerts. + +When creating a contact point, the `EmbeddedContactPoint.name` property determines if the new contact point is added to an existing one. In the UI, contact points with the same name are grouped together under a single contact point. **Properties** {{% responsive-table %}} -| Name | Type | Go type | Required | Default | Description | Example | -| ------------------------------------ | ----------------------- | -------- | :------: | ------- | ----------------------------------------------------------------- | --------- | -| disableResolveMessage | boolean | `bool` | | | | `false` | -| name | string | `string` | | | Name is used as grouping key in the UI. Contact points with the | -| same name will be grouped in the UI. | `webhook_1` | -| provenance | string | `string` | | | | | -| settings | [JSON](#json) | `JSON` | ✓ | | | | -| type | string | `string` | ✓ | | | `webhook` | -| uid | string | `string` | | | UID is the unique identifier of the contact point. The UID can be | -| set by the user. | `my_external_reference` | +| Name | Type | Go type | Required | Default | Description | Example | +| --------------------- | ------------- | -------- | :------: | ------- | ---------------------------------------------------------------------------------- | ----------------------- | +| disableResolveMessage | boolean | `bool` | | | | `false` | +| name | string | `string` | | | `name` groups multiple contact points with the same name in the UI. | `webhook_1` | +| provenance | string | `string` | | | | | +| settings | [JSON](#json) | `JSON` | ✓ | | | | +| type | string | `string` | ✓ | | | `webhook` | +| uid | string | `string` | | | UID is the unique identifier of the contact point. The UID can be set by the user. | `my_external_reference` | {{% /responsive-table %}}