root
/
grafana
mirror of https://github.com/grafana/grafana.git
1
0
Fork 0
Code Issues Actions 142 Packages Projects Releases Wiki Activity

docs(alerting): enhancements for MQTT docs (#106566)
Actionlint / Lint GitHub Actions files (push) Waiting to run Details
Backend Code Checks / Validate Backend Configs (push) Waiting to run Details
Backend Unit Tests / Grafana (${{ matrix.shard }}) (1/8) (push) Waiting to run Details
Backend Unit Tests / Grafana (${{ matrix.shard }}) (2/8) (push) Waiting to run Details
Backend Unit Tests / Grafana (${{ matrix.shard }}) (3/8) (push) Waiting to run Details
Backend Unit Tests / Grafana (${{ matrix.shard }}) (4/8) (push) Waiting to run Details
Backend Unit Tests / Grafana (${{ matrix.shard }}) (5/8) (push) Waiting to run Details
Backend Unit Tests / Grafana (${{ matrix.shard }}) (6/8) (push) Waiting to run Details
Backend Unit Tests / Grafana (${{ matrix.shard }}) (7/8) (push) Waiting to run Details
Backend Unit Tests / Grafana (${{ matrix.shard }}) (8/8) (push) Waiting to run Details
Backend Unit Tests / Grafana Enterprise (${{ matrix.shard }}) (1/8) (push) Waiting to run Details
Backend Unit Tests / Grafana Enterprise (${{ matrix.shard }}) (2/8) (push) Waiting to run Details
Backend Unit Tests / Grafana Enterprise (${{ matrix.shard }}) (3/8) (push) Waiting to run Details
Backend Unit Tests / Grafana Enterprise (${{ matrix.shard }}) (4/8) (push) Waiting to run Details
Backend Unit Tests / Grafana Enterprise (${{ matrix.shard }}) (5/8) (push) Waiting to run Details
Backend Unit Tests / Grafana Enterprise (${{ matrix.shard }}) (6/8) (push) Waiting to run Details
Backend Unit Tests / Grafana Enterprise (${{ matrix.shard }}) (7/8) (push) Waiting to run Details
Backend Unit Tests / Grafana Enterprise (${{ matrix.shard }}) (8/8) (push) Waiting to run Details
CodeQL checks / Analyze (actions) (push) Waiting to run Details
CodeQL checks / Analyze (go) (push) Waiting to run Details
CodeQL checks / Analyze (javascript) (push) Waiting to run Details
Lint Frontend / Verify i18n (push) Waiting to run Details
Lint Frontend / Lint (push) Waiting to run Details
Lint Frontend / Typecheck (push) Waiting to run Details
Lint Frontend / Betterer (push) Waiting to run Details
golangci-lint / lint-go (push) Waiting to run Details
Documentation / Build & Verify Docs (push) Waiting to run Details
End-to-end tests / Build & Package Grafana (push) Waiting to run Details
End-to-end tests / Build E2E test runner (push) Waiting to run Details
End-to-end tests / ${{ matrix.suite }} (--flags="--env dashboardScene=false", e2e/old-arch/dashboards-suite, dashboards-suite (old arch)) (push) Blocked by required conditions Details
End-to-end tests / ${{ matrix.suite }} (--flags="--env dashboardScene=false", e2e/old-arch/panels-suite, panels-suite (old arch)) (push) Blocked by required conditions Details
End-to-end tests / ${{ matrix.suite }} (--flags="--env dashboardScene=false", e2e/old-arch/smoke-tests-suite, smoke-tests-suite (old arch)) (push) Blocked by required conditions Details
End-to-end tests / ${{ matrix.suite }} (--flags="--env dashboardScene=false", e2e/old-arch/various-suite, various-suite (old arch)) (push) Blocked by required conditions Details
End-to-end tests / ${{ matrix.suite }} (e2e/dashboards-suite, dashboards-suite) (push) Blocked by required conditions Details
End-to-end tests / ${{ matrix.suite }} (e2e/panels-suite, panels-suite) (push) Blocked by required conditions Details
End-to-end tests / ${{ matrix.suite }} (e2e/smoke-tests-suite, smoke-tests-suite) (push) Blocked by required conditions Details
End-to-end tests / ${{ matrix.suite }} (e2e/various-suite, various-suite) (push) Blocked by required conditions Details
Frontend tests / Unit tests (${{ matrix.chunk }} / 8) (1) (push) Waiting to run Details
Frontend tests / Unit tests (${{ matrix.chunk }} / 8) (2) (push) Waiting to run Details
Frontend tests / Unit tests (${{ matrix.chunk }} / 8) (3) (push) Waiting to run Details
Frontend tests / Unit tests (${{ matrix.chunk }} / 8) (4) (push) Waiting to run Details
Frontend tests / Unit tests (${{ matrix.chunk }} / 8) (5) (push) Waiting to run Details
Frontend tests / Unit tests (${{ matrix.chunk }} / 8) (6) (push) Waiting to run Details
Frontend tests / Unit tests (${{ matrix.chunk }} / 8) (7) (push) Waiting to run Details
Frontend tests / Unit tests (${{ matrix.chunk }} / 8) (8) (push) Waiting to run Details
Integration Tests / Sqlite (${{ matrix.shard }}) (1/8) (push) Waiting to run Details
Integration Tests / Sqlite (${{ matrix.shard }}) (2/8) (push) Waiting to run Details
Integration Tests / Sqlite (${{ matrix.shard }}) (3/8) (push) Waiting to run Details
Integration Tests / Sqlite (${{ matrix.shard }}) (4/8) (push) Waiting to run Details
Integration Tests / Sqlite (${{ matrix.shard }}) (5/8) (push) Waiting to run Details
Integration Tests / Sqlite (${{ matrix.shard }}) (6/8) (push) Waiting to run Details
Integration Tests / Sqlite (${{ matrix.shard }}) (7/8) (push) Waiting to run Details
Integration Tests / Sqlite (${{ matrix.shard }}) (8/8) (push) Waiting to run Details
Integration Tests / MySQL (${{ matrix.shard }}) (1/8) (push) Waiting to run Details
Integration Tests / MySQL (${{ matrix.shard }}) (2/8) (push) Waiting to run Details
Integration Tests / MySQL (${{ matrix.shard }}) (3/8) (push) Waiting to run Details
Integration Tests / MySQL (${{ matrix.shard }}) (4/8) (push) Waiting to run Details
Integration Tests / MySQL (${{ matrix.shard }}) (5/8) (push) Waiting to run Details
Integration Tests / MySQL (${{ matrix.shard }}) (6/8) (push) Waiting to run Details
Integration Tests / MySQL (${{ matrix.shard }}) (7/8) (push) Waiting to run Details
Integration Tests / MySQL (${{ matrix.shard }}) (8/8) (push) Waiting to run Details
Integration Tests / Postgres (${{ matrix.shard }}) (1/8) (push) Waiting to run Details
Integration Tests / Postgres (${{ matrix.shard }}) (2/8) (push) Waiting to run Details
Integration Tests / Postgres (${{ matrix.shard }}) (3/8) (push) Waiting to run Details
Integration Tests / Postgres (${{ matrix.shard }}) (4/8) (push) Waiting to run Details
Integration Tests / Postgres (${{ matrix.shard }}) (5/8) (push) Waiting to run Details
Integration Tests / Postgres (${{ matrix.shard }}) (6/8) (push) Waiting to run Details
Integration Tests / Postgres (${{ matrix.shard }}) (7/8) (push) Waiting to run Details
Integration Tests / Postgres (${{ matrix.shard }}) (8/8) (push) Waiting to run Details
publish-technical-documentation-next / sync (push) Waiting to run Details
Reject GitHub secrets / reject-gh-secrets (push) Waiting to run Details
Run dashboard schema v2 e2e / dashboard-schema-v2-e2e (push) Waiting to run Details
Dispatch sync to mirror / dispatch-job (push) Waiting to run Details 

* docs(alerting): enhancements for MQTT docs

* Update docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-mqtt.md

Co-authored-by: Simon Prickett <simon@crudworks.org>

---------

Co-authored-by: Simon Prickett <simon@crudworks.org>
This commit is contained in:
Pepe Cano 2025-06-13 10:27:08 +02:00 committed by GitHub
parent 98ea0193e4
commit 493e7ba75f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 100 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

135
docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-mqtt.md
View File

@ -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/<GRAFANA_VERSION>/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/<GRAFANA_VERSION>/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/<GRAFANA_VERSION>/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). <br/> If set to `text`, the notification message is fully customizable. |
| Message | Depends on the **Message format** option. <br/> In `json` format, defines only the `message` field of the [default JSON payload](#default-json-payload). <br/> In `text` format, defines the [entire custom payload](#custom-payload). <br/> 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
### Body
Each notification payload contains the following fields.
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 [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 |
| 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**). <br/> 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="<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).

15
docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md
View File

@ -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="<GRAFANA_VERSION>" >}}
## Custom Payload

18
docs/sources/shared/alerts/table-for-json-alert-object.md Normal file
View File

@ -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. |