From 1dcb62d36905c46a89f6410e68c8ba69bc334b70 Mon Sep 17 00:00:00 2001 From: "grafana-delivery-bot[bot]" <132647405+grafana-delivery-bot[bot]@users.noreply.github.com> Date: Fri, 13 Jun 2025 10:35:34 +0200 Subject: [PATCH] [release-12.0.2] docs(alerting): enhancements for MQTT docs (#106697) docs(alerting): enhancements for MQTT docs (#106566) * docs(alerting): enhancements for MQTT docs * Update docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-mqtt.md --------- (cherry picked from commit 493e7ba75ff31758eb0e87805a2af3a886c00e6b) Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com> Co-authored-by: Simon Prickett --- .../integrations/configure-mqtt.md | 139 +++++++++++------- .../integrations/webhook-notifier.md | 15 +- .../alerts/table-for-json-alert-object.md | 18 +++ 3 files changed, 102 insertions(+), 70 deletions(-) create mode 100644 docs/sources/shared/alerts/table-for-json-alert-object.md 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 1c3e06c1243..8e58e619f00 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 @@ -13,41 +13,69 @@ labels: - enterprise - oss menuTitle: MQTT -title: Configure the MQTT notifier for Alerting +title: Configure MQTT notifications weight: 140 +refs: + notification-template-examples: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/configure-notifications/template-notifications/examples/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/template-notifications/examples/ + notification-templates: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/configure-notifications/template-notifications/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/template-notifications/ + configure-contact-points: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/configure-notifications/manage-contact-points/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/manage-contact-points/ --- -# Configure the MQTT notifier for Alerting +# Configure MQTT notifications -Use the Grafana Alerting - MQTT integration to send notifications to an MQTT broker when your alerts are firing. +Use the MQTT integration in contact points to send alert notifications to your MQTT broker. -## Procedure +## Configure MQTT for a contact point -To configure the MQTT integration for Alerting, complete the following steps. +To create a contact point with MQTT integration, complete the following steps. -1. In the left-side menu, click **Alerts & IRM** and then **Alerting**. -1. On the **Contact Points** tab, click **+ Add contact point**. -1. Enter a descriptive name for the contact point. -1. From the Integration list, select **MQTT**. +1. Navigate to **Alerts & IRM** -> **Alerting** -> **Contact points**. +1. Click **+ Add contact point**. +1. Enter a name for the contact point. +1. From the **Integration** list, select **MQTT**. 1. Enter your broker URL in the **Broker URL** field. Supports `tcp`, `ssl`, `mqtt`, `mqtts`, `ws`, `wss` schemes. For example: `tcp://127.0.0.1:1883`. 1. Enter the MQTT topic name in the **Topic** field. -1. In **Optional MQTT settings**, specify additional settings for the MQTT integration if needed. -1. Click **Test** to check that your integration works. +1. (Optional) Configure [additional settings](#optional-settings). +1. Click **Save contact point**. - ** For Grafana Alertmanager only.** +For more details on contact points, including how to test them and enable notifications, refer to [Configure contact points](ref:configure-contact-points). - A test alert notification should be sent to the MQTT broker. +### Required Settings -1. Click **Save** contact point. +| Option | Description | +| ---------- | -------------------------------------------- | +| Broker URL | The URL of the MQTT broker. | +| Topic | The topic to which the message will be sent. | -The integration sends data in JSON format by default. You can change that using **Message format** field in the **Optional MQTT settings** section. There are two supported formats: +### Optional Settings -- **JSON**: Sends the alert notification in JSON format. -- **Text**: Sends the rendered alert notification message in plain text format. +| Option | Description | +| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Message format | If set to `json` (default), the notification message uses the [default JSON payload](#default-json-payload).
If set to `text`, the notification message is fully customizable. | +| Message | Depends on the **Message format** option.
In `json` format, defines only the `message` field of the [default JSON payload](#default-json-payload).
In `text` format, defines the [entire custom payload](#custom-payload).
This field supports [notification templates](ref:notification-templates). | +| Client ID | The client ID to use when connecting to the MQTT broker. If blank, a random client ID is used. | +| Username | The username to use when connecting to the MQTT broker. | +| Password | The password to use when connecting to the MQTT broker. | +| QoS | The quality of service to use when sending the message. Options are `At most once`, `At least once`, and `Exactly once`. | +| Retain | If set to true, the message will be retained by the broker. | +| TLS | TLS configuration options, including CA certificate, client certificate, and client key, and disable certificate verification. | +| Disable resolved message | Enable this option to prevent notifications when an alert resolves. | -## MQTT JSON payload +## Default JSON payload -If the JSON message format is selected in **Optional MQTT settings**, the payload is sent in the following structure. +If the **Message format** option is `json` (the default), the payload is like this example. ```json { @@ -116,43 +144,42 @@ If the JSON message format is selected in **Optional MQTT settings**, the payloa } ``` -### Payload fields - -Each notification payload contains the following fields. - -| Key | Type | Description | -| ----------------- | ------------------------------------------- | ------------------------------------------------------------------------------- | -| receiver | string | Name of the contact point | -| status | string | Current status of the alert, `firing` or `resolved` | -| orgId | number | ID of the organization related to the payload | -| alerts | array of [alert instances](#alert-instance) | Alerts that are triggering | -| groupLabels | object | Labels that are used for grouping, map of string keys to string values | -| commonLabels | object | Labels that all alarms have in common, map of string keys to string values | -| commonAnnotations | object | Annotations that all alarms have in common, map of string keys to string values | -| externalURL | string | External URL to the Grafana instance sending this webhook | -| version | string | Version of the payload | -| groupKey | string | Key that is used for grouping | -| message | string | Rendered message of the alerts | - -### Alert instance - -Each alert instance in the `alerts` array has the following fields. - -| Key | Type | Description | -| ------------ | ------ | ---------------------------------------------------------------------------------- | -| status | string | Current status of the alert, `firing` or `resolved` | -| labels | object | Labels that are part of this alert, map of string keys to string values | -| annotations | object | Annotations that are part of this alert, map of string keys to string values | -| startsAt | string | Start time of the alert | -| endsAt | string | End time of the alert, default value when not resolved is `0001-01-01T00:00:00Z` | -| values | object | Values that triggered the current status | -| generatorURL | string | URL of the alert rule in the Grafana UI | -| fingerprint | string | The labels fingerprint, alarms with the same labels will have the same fingerprint | -| silenceURL | string | URL to silence the alert rule in the Grafana UI | -| dashboardURL | string | A link to the Grafana Dashboard if the alert has a Dashboard UID annotation | -| panelURL | string | A link to the panel if the alert has a Panel ID annotation | -| imageURL | string | URL of a screenshot of a panel assigned to the rule that created this notification | +### Body + +If the **Message format** option is `json` (the default), the payload contains the following fields. + +| Key | Type | Description | +| ------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `receiver` | string | Name of the contact point | +| `status` | string | Current status of the alert, `firing` or `resolved` | +| `orgId` | number | ID of the organization related to the payload | +| `alerts` | array of [alerts](#alert-object) | Alerts that are triggering | +| `groupLabels` | object | Labels that are used for grouping, map of string keys to string values | +| `commonLabels` | object | Labels that all alarms have in common, map of string keys to string values | +| `commonAnnotations` | object | Annotations that all alarms have in common, map of string keys to string values | +| `externalURL` | string | External URL to the Grafana instance sending this webhook | +| `version` | string | Version of the payload | +| `groupKey` | string | Key that is used for grouping | +| `message` | string | Custom message configured in **Message** (**Optional Settings**).
Supports [notification templates](ref:notification-templates); the output is formatted as a string. | {{< admonition type="note" >}} -Alert rules are not coupled to dashboards anymore. The fields related to dashboards `dashboardId` and `panelId` have been removed. + +When using the `json` **Message format**, only the **message** field of the JSON payload is customizable, and its output is formatted as a string. + +To customize the full payload in text or JSON format, use the `text` format and define a [custom payload](#custom-payload). + {{< /admonition >}} + +### Alert object + +The Alert object represents an alert included in the notification group, as provided by the [`alerts` field](#body). + +{{< docs/shared lookup="alerts/table-for-json-alert-object.md" source="grafana" version="" >}} + +## Custom payload + +When you set the **Message format** option to `text`, you can customize the entire payload of the MQTT message. + +In this mode, the **Message** option defines the entire payload. It supports [notification templates](ref:notification-templates) and can generate notification messages in plain text, JSON, or any custom format. + +For examples of templates that produce plain text or JSON messages, refer to [notification template examples](ref:notification-template-examples). 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 898b2ae98b5..b8050bc6f05 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 @@ -237,20 +237,7 @@ The following key-value pairs are also included in the JSON payload and can be c The Alert object represents an alert included in the notification group, as provided by the [`alerts` field](#body). -| Key | Type | Description | -| -------------- | ------ | ----------------------------------------------------------------------------------- | -| `status` | string | Current status of the alert, `firing` or `resolved`. | -| `labels` | object | Labels that are part of this alert, map of string keys to string values. | -| `annotations` | object | Annotations that are part of this alert, map of string keys to string values. | -| `startsAt` | string | Start time of the alert. | -| `endsAt` | string | End time of the alert, default value when not resolved is `0001-01-01T00:00:00Z`. | -| `values` | object | Values that triggered the current status. | -| `generatorURL` | string | URL of the alert rule in the Grafana UI. | -| `fingerprint` | string | The labels fingerprint, alarms with the same labels will have the same fingerprint. | -| `silenceURL` | string | URL to silence the alert rule in the Grafana UI. | -| `dashboardURL` | string | A link to the Grafana Dashboard if the alert has a Dashboard UID annotation. | -| `panelURL` | string | A link to the panel if the alert has a Panel ID annotation. | -| `imageURL` | string | URL of a screenshot of a panel assigned to the rule that created this notification. | +{{< docs/shared lookup="alerts/table-for-json-alert-object.md" source="grafana" version="" >}} ## Custom Payload diff --git a/docs/sources/shared/alerts/table-for-json-alert-object.md b/docs/sources/shared/alerts/table-for-json-alert-object.md new file mode 100644 index 00000000000..a4f53e2dccd --- /dev/null +++ b/docs/sources/shared/alerts/table-for-json-alert-object.md @@ -0,0 +1,18 @@ +--- +title: 'JSON alert object' +--- + +| Key | Type | Description | +| -------------- | ------ | ----------------------------------------------------------------------------------- | +| `status` | string | Current status of the alert, `firing` or `resolved`. | +| `labels` | object | Labels that are part of this alert, map of string keys to string values. | +| `annotations` | object | Annotations that are part of this alert, map of string keys to string values. | +| `startsAt` | string | Start time of the alert. | +| `endsAt` | string | End time of the alert, default value when not resolved is `0001-01-01T00:00:00Z`. | +| `values` | object | Values that triggered the current status. | +| `generatorURL` | string | URL of the alert rule in the Grafana UI. | +| `fingerprint` | string | The labels fingerprint, alarms with the same labels will have the same fingerprint. | +| `silenceURL` | string | URL to silence the alert rule in the Grafana UI. | +| `dashboardURL` | string | A link to the Grafana Dashboard if the alert has a Dashboard UID annotation. | +| `panelURL` | string | A link to the panel if the alert has a Panel ID annotation. | +| `imageURL` | string | URL of a screenshot of a panel assigned to the rule that created this notification. |