Alerting: Add MQTT notifications receiver (#91487)

* Alerting: Add MQTT notifications receiver
* Update alerting to 9daa6239cc41dc42bff0e916c8d0d27766caa8b9 (main)
---------

Co-authored-by: Jack Baldry <jack.baldry@grafana.com>
Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com>
This commit is contained in:
Alexander Akhmetov 2024-08-22 16:47:48 +02:00 committed by GitHub
parent 9c73916f09
commit 832bb01f36
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
12 changed files with 324 additions and 5 deletions

View File

@ -504,6 +504,18 @@ The following sections detail the supported settings and secure settings for eac
| ----- | -------------- |
| token | yes |
#### Alert notification `MQTT`
| Name | Secure setting |
| ------------------ | -------------- |
| brokerUrl | |
| clientId | |
| topic | |
| messageFormat |
| username | |
| password | yes |
| insecureSkipVerify | |
#### Alert notification `pagerduty`
| Name | Secure setting |

View File

@ -76,6 +76,11 @@ refs:
destination: /docs/grafana/<GRAFANA_VERSION>/alerting/set-up/configure-alertmanager/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/alerting-and-irm/alerting/set-up/configure-alertmanager/
mqtt:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/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/
---
# Configure contact points
@ -164,6 +169,7 @@ The following table lists the contact point integrations supported by Grafana.
| Google Chat | `googlechat` |
| [Grafana Oncall](ref:oncall) | `oncall` |
| Kafka REST Proxy | `kafka` |
| [MQTT](ref:mqtt) | `mqtt` |
| Line | `line` |
| [Microsoft Teams](ref:teams) | `teams` |
| [Opsgenie](ref:opsgenie) | `opsgenie` |

View File

@ -0,0 +1,154 @@
---
canonical: https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/configure-mqtt/
description: Configure the MQTT notifier integration for Alerting
keywords:
- grafana
- alerting
- guide
- contact point
- mqtt
labels:
products:
- cloud
- enterprise
- oss
menuTitle: MQTT notifier
title: Configure the MQTT notifier for Alerting
weight: 80
---
# Configure the MQTT notifier for Alerting
Use the Grafana Alerting - MQTT integration to send notifications to an MQTT broker when your alerts are firing.
## Procedure
To configure the MQTT integration for Alerting, 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. 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.
A test alert notification should be sent to the MQTT broker.
1. Click **Save** contact point.
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:
- **JSON**: Sends the alert notification in JSON format.
- **Text**: Sends the rendered alert notification message in plain text format.
## MQTT JSON payload
If the JSON message format is selected in **Optional MQTT settings**, the payload is sent in the following structure.
```json
{
"receiver": "My MQTT integration",
"status": "firing",
"orgId": 1,
"alerts": [
{
"status": "firing",
"labels": {
"alertname": "High memory usage",
"team": "blue",
"zone": "us-1"
},
"annotations": {
"description": "The system has high memory usage",
"runbook_url": "https://myrunbook.com/runbook/1234",
"summary": "This alert was triggered for zone us-1"
},
"startsAt": "2021-10-12T09:51:03.157076+02:00",
"endsAt": "0001-01-01T00:00:00Z",
"generatorURL": "https://play.grafana.org/alerting/1afz29v7z/edit",
"fingerprint": "c6eadffa33fcdf37",
"silenceURL": "https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT2%2Cteam%3Dblue%2Czone%3Dus-1",
"dashboardURL": "",
"panelURL": "",
"values": {
"B": 44.23943737541908,
"C": 1
}
},
{
"status": "firing",
"labels": {
"alertname": "High CPU usage",
"team": "blue",
"zone": "eu-1"
},
"annotations": {
"description": "The system has high CPU usage",
"runbook_url": "https://myrunbook.com/runbook/1234",
"summary": "This alert was triggered for zone eu-1"
},
"startsAt": "2021-10-12T09:56:03.157076+02:00",
"endsAt": "0001-01-01T00:00:00Z",
"generatorURL": "https://play.grafana.org/alerting/d1rdpdv7k/edit",
"fingerprint": "bc97ff14869b13e3",
"silenceURL": "https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT1%2Cteam%3Dblue%2Czone%3Deu-1",
"dashboardURL": "",
"panelURL": "",
"values": {
"B": 44.23943737541908,
"C": 1
}
}
],
"groupLabels": {},
"commonLabels": {
"team": "blue"
},
"commonAnnotations": {},
"externalURL": "https://play.grafana.org/",
"version": "1",
"groupKey": "{}:{}",
"message": "**Firing**\n\nLabels:\n - alertname = T2\n - team = blue\n - zone = us-1\nAnnotations:\n - description = This is the alert rule checking the second system\n - runbook_url = https://myrunbook.com\n - summary = This is my summary\nSource: https://play.grafana.org/alerting/1afz29v7z/edit\nSilence: https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT2%2Cteam%3Dblue%2Czone%3Dus-1\n\nLabels:\n - alertname = T1\n - team = blue\n - zone = eu-1\nAnnotations:\nSource: https://play.grafana.org/alerting/d1rdpdv7k/edit\nSilence: https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT1%2Cteam%3Dblue%2Czone%3Deu-1\n"
}
```
### 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 | **Deprecated. It will be removed in a future release.** |
| panelURL | string | **Deprecated. It will be removed in a future release.** |
| imageURL | string | URL of a screenshot of a panel assigned to the rule that created this notification |
{{< admonition type="note" >}}
Alert rules are not coupled to dashboards anymore. The fields related to dashboards `dashboardId` and `panelId` have been removed.
{{< /admonition >}}

View File

@ -99,6 +99,7 @@ Grafana supports a wide range of contact points with varied support for images i
| Google Chat | No | Yes |
| Kafka | No | No |
| Line | No | No |
| MQTT | No | No |
| Microsoft Teams | No | Yes |
| Opsgenie | No | Yes |
| Pagerduty | No | Yes |

View File

@ -343,6 +343,31 @@ settings:
{{< /collapse >}}
{{< collapse title="MQTT" >}}
#### MQTT
```yaml
type: mqtt
settings:
# <string, required>
brokerUrl: tcp://127.0.0.1:1883
# <string>
clientId: grafana
# <string, required>
topic: grafana/alerts
# <string>
messageFormat: json
# <string>
username: grafana
# <string>
password: password1
# <bool>
insecureSkipVerify: false
```
{{< /collapse >}}
{{< collapse title="Microsoft Teams" >}}
#### Microsoft Teams

3
go.mod
View File

@ -74,7 +74,7 @@ require (
github.com/googleapis/gax-go/v2 v2.13.0 // @grafana/grafana-backend-group
github.com/gorilla/mux v1.8.1 // @grafana/grafana-backend-group
github.com/gorilla/websocket v1.5.0 // @grafana/grafana-app-platform-squad
github.com/grafana/alerting v0.0.0-20240812131556-611a23ff0f7f // @grafana/alerting-backend
github.com/grafana/alerting v0.0.0-20240822131459-9daa6239cc41 // @grafana/alerting-backend
github.com/grafana/authlib v0.0.0-20240814074258-eae7d47f01db // @grafana/identity-access-team
github.com/grafana/authlib/claims v0.0.0-20240814074258-eae7d47f01db // @grafana/identity-access-team
github.com/grafana/codejen v0.0.3 // @grafana/dataviz-squad
@ -479,6 +479,7 @@ require (
require (
cloud.google.com/go/longrunning v0.5.12 // indirect
github.com/at-wat/mqtt-go v0.19.4 // indirect
github.com/grafana/grafana/pkg/semconv v0.0.0-20240808213237-f4d2e064f435 // indirect
github.com/hairyhenderson/go-which v0.2.0 // indirect
github.com/iancoleman/orderedmap v0.3.0 // indirect

6
go.sum
View File

@ -1542,6 +1542,8 @@ github.com/aryann/difflib v0.0.0-20170710044230-e206f873d14a/go.mod h1:DAHtR1m6l
github.com/asaskevich/govalidator v0.0.0-20190424111038-f61b66f89f4a/go.mod h1:lB+ZfQJz7igIIfQNfa7Ml4HSf2uFQQRzpGGRXenZAgY=
github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2 h1:DklsrG3dyBCFEj5IhUbnKptjxatkF07cF2ak3yi77so=
github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2/go.mod h1:WaHUgvxTVq04UNunO+XhnAqY/wQc+bxr74GqbsZ/Jqw=
github.com/at-wat/mqtt-go v0.19.4 h1:R2cbCU7O5PHQ38unbe1Y51ncG3KsFEJV6QeipDoqdLQ=
github.com/at-wat/mqtt-go v0.19.4/go.mod h1:AsiWc9kqVOhqq7LzUeWT/AkKUBfx3Sw5cEe8lc06fqA=
github.com/aws/aws-lambda-go v1.13.3/go.mod h1:4UKl9IzQMoD+QF79YdCuzCwp8VbmG4VAQwij/eHl5CU=
github.com/aws/aws-sdk-go v1.17.7/go.mod h1:KmX6BPdI08NWTb3/sm4ZGu5ShLoqVDhKgpiN924inxo=
github.com/aws/aws-sdk-go v1.27.0/go.mod h1:KmX6BPdI08NWTb3/sm4ZGu5ShLoqVDhKgpiN924inxo=
@ -2244,8 +2246,8 @@ github.com/gorilla/websocket v0.0.0-20170926233335-4201258b820c/go.mod h1:E7qHFY
github.com/gorilla/websocket v1.4.2/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
github.com/gorilla/websocket v1.5.0 h1:PPwGk2jz7EePpoHN/+ClbZu8SPxiqlu12wZP/3sWmnc=
github.com/gorilla/websocket v1.5.0/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
github.com/grafana/alerting v0.0.0-20240812131556-611a23ff0f7f h1:c8QAFXkilBiF29xc7oKO2IkbGE3bp9NIKgiNLazdooY=
github.com/grafana/alerting v0.0.0-20240812131556-611a23ff0f7f/go.mod h1:DLj8frbtCaITljC2jc0L85JQViPF3mPfOSiYhm1osso=
github.com/grafana/alerting v0.0.0-20240822131459-9daa6239cc41 h1:p+UsX43BoDH5YlG6xUd9xDS3M4sWouy8VJ+ODv5S6uE=
github.com/grafana/alerting v0.0.0-20240822131459-9daa6239cc41/go.mod h1:GMLi6d09Xqo96fCVUjNk//rcjP5NKEdjOzfWIffD5r4=
github.com/grafana/authlib v0.0.0-20240814074258-eae7d47f01db h1:z++X4DdoX+aNlZNT1ZY4cykiFay4+f077pa0AG48SGg=
github.com/grafana/authlib v0.0.0-20240814074258-eae7d47f01db/go.mod h1:ptt910z9KFfpVSIbSbXvTRR7tS19mxD7EtmVbbJi/WE=
github.com/grafana/authlib/claims v0.0.0-20240814074258-eae7d47f01db h1:mDk0bwRV6rDrLSmKXftcPf9kLA9uH6EvxJvzpPW9bso=

View File

@ -715,6 +715,9 @@ github.com/gorilla/mux v1.8.0/go.mod h1:DVbg23sWSpFRCP0SfiEN6jmj59UnW/n46BH5rLB7
github.com/grafana/authlib v0.0.0-20240730122259-a0d13672efb1/go.mod h1:YA9We4kTafu7mlMnUh3In6Q2wpg8fYN3ycgCKOK1TB8=
github.com/grafana/authlib/claims v0.0.0-20240809101159-74eaccc31a06/go.mod h1:r+F8H6awwjNQt/KPZ2GNwjk8TvsJ7/gxzkXN26GlL/A=
github.com/grafana/gomemcache v0.0.0-20240229205252-cd6a66d6fb56/go.mod h1:PGk3RjYHpxMM8HFPhKKo+vve3DdlPUELZLSDEFehPuU=
github.com/grafana/grafana-plugin-sdk-go v0.235.0/go.mod h1:6n9LbrjGL3xAATntYVNcIi90G9BVHRJjzHKz5FXVfWw=
github.com/grafana/prometheus-alertmanager v0.25.1-0.20240422145632-c33c6b5b6e6b h1:HCbWyVL6vi7gxyO76gQksSPH203oBJ1MJ3JcG1OQlsg=
github.com/grafana/prometheus-alertmanager v0.25.1-0.20240422145632-c33c6b5b6e6b/go.mod h1:01sXtHoRwI8W324IPAzuxDFOmALqYLCOhvSC2fUHWXc=
github.com/grafana/pyroscope-go/godeltaprof v0.1.6/go.mod h1:Tk376Nbldo4Cha9RgiU7ik8WKFkNpfds98aUzS8omLE=
github.com/gregjones/httpcache v0.0.0-20180305231024-9cad4c3443a7 h1:pdN6V1QBWetyv/0+wjACpqVH+eVULgEjkurDLq3goeM=
github.com/grpc-ecosystem/grpc-gateway/v2 v2.19.1/go.mod h1:5SN9VR2LTsRFsrEC6FHgRbTWrTHu6tqPeKxEQv15giM=

View File

@ -51,7 +51,7 @@ func ContactPointToContactPointExport(cp definitions.ContactPoint) (notify.APIRe
len(cp.Pagerduty) + len(cp.OnCall) + len(cp.Pushover) + len(cp.Sensugo) +
len(cp.Sns) + len(cp.Slack) + len(cp.Teams) + len(cp.Telegram) +
len(cp.Threema) + len(cp.Victorops) + len(cp.Webhook) + len(cp.Wecom) +
len(cp.Webex)
len(cp.Webex) + len(cp.Mqtt)
integration := make([]*notify.GrafanaIntegrationConfig, 0, contactPointsLength)
@ -105,6 +105,13 @@ func ContactPointToContactPointExport(cp definitions.ContactPoint) (notify.APIRe
}
integration = append(integration, el)
}
for _, i := range cp.Mqtt {
el, err := marshallIntegration(j, "mqtt", i, i.DisableResolveMessage)
if err != nil {
errs = append(errs, err)
}
integration = append(integration, el)
}
for _, i := range cp.Opsgenie {
el, err := marshallIntegration(j, "opsgenie", i, i.DisableResolveMessage)
if err != nil {
@ -274,6 +281,11 @@ func parseIntegration(json jsoniter.API, result *definitions.ContactPoint, recei
if err = json.Unmarshal(data, &integration); err == nil {
result.Line = append(result.Line, integration)
}
case "mqtt":
integration := definitions.MqttIntegration{DisableResolveMessage: disable}
if err = json.Unmarshal(data, &integration); err == nil {
result.Mqtt = append(result.Mqtt, integration)
}
case "opsgenie":
integration := definitions.OpsgenieIntegration{DisableResolveMessage: disable}
if err = json.Unmarshal(data, &integration); err == nil {

View File

@ -85,6 +85,19 @@ type LineIntegration struct {
Description *string `json:"description,omitempty" yaml:"description,omitempty" hcl:"description"`
}
type MqttIntegration struct {
DisableResolveMessage *bool `json:"-" yaml:"-" hcl:"disable_resolve_message"`
BrokerURL *string `json:"brokerUrl,omitempty" yaml:"brokerUrl,omitempty" hcl:"broker_url"`
ClientID *string `json:"clientId,omitempty" yaml:"clientId,omitempty" hcl:"client_id"`
Topic *string `json:"topic,omitempty" yaml:"topic,omitempty" hcl:"topic"`
Message *string `json:"message,omitempty" yaml:"message,omitempty" hcl:"message"`
MessageFormat *string `json:"messageFormat,omitempty" yaml:"messageFormat,omitempty" hcl:"message_format"`
Username *string `json:"username,omitempty" yaml:"username,omitempty" hcl:"username"`
Password *Secret `json:"password,omitempty" yaml:"password,omitempty" hcl:"password"`
InsecureSkipVerify *bool `json:"insecureSkipVerify,omitempty" yaml:"insecureSkipVerify,omitempty" hcl:"insecure_skip_verify"`
}
type OnCallIntegration struct {
DisableResolveMessage *bool `json:"-" yaml:"-" hcl:"disable_resolve_message"`
@ -299,6 +312,7 @@ type ContactPoint struct {
Googlechat []GooglechatIntegration `json:"googlechat" yaml:"googlechat" hcl:"googlechat,block"`
Kafka []KafkaIntegration `json:"kafka" yaml:"kafka" hcl:"kafka,block"`
Line []LineIntegration `json:"line" yaml:"line" hcl:"line,block"`
Mqtt []MqttIntegration `json:"mqtt" yaml:"mqtt" hcl:"mqtt,block"`
Opsgenie []OpsgenieIntegration `json:"opsgenie" yaml:"opsgenie" hcl:"opsgenie,block"`
Pagerduty []PagerdutyIntegration `json:"pagerduty" yaml:"pagerduty" hcl:"pagerduty,block"`
OnCall []OnCallIntegration `json:"oncall" yaml:"oncall" hcl:"oncall,block"`

View File

@ -5,6 +5,7 @@ import (
"os"
"strings"
alertingMqtt "github.com/grafana/alerting/receivers/mqtt"
alertingOpsgenie "github.com/grafana/alerting/receivers/opsgenie"
alertingPagerduty "github.com/grafana/alerting/receivers/pagerduty"
alertingTemplates "github.com/grafana/alerting/templates"
@ -1245,6 +1246,93 @@ func GetAvailableNotifiers() []*NotifierPlugin {
},
},
},
{
Type: "mqtt",
Name: "MQTT",
Description: "Sends notifications to an MQTT broker",
Heading: "MQTT settings",
Info: "The MQTT notifier sends messages to an MQTT broker. The message is sent to the topic specified in the configuration. ",
Options: []NotifierOption{
{
Label: "Broker URL",
Element: ElementTypeInput,
InputType: InputTypeText,
Placeholder: "tcp://localhost:1883",
Description: "The URL of the MQTT broker.",
PropertyName: "brokerUrl",
Required: true,
},
{
Label: "Topic",
Element: ElementTypeInput,
InputType: InputTypeText,
Placeholder: "grafana/alerts",
Description: "The topic to which the message will be sent.",
PropertyName: "topic",
Required: true,
},
{
Label: "Message format",
Element: ElementTypeSelect,
SelectOptions: []SelectOption{
{
Value: alertingMqtt.MessageFormatJSON,
Label: "json",
},
{
Value: alertingMqtt.MessageFormatText,
Label: "text",
},
},
InputType: InputTypeText,
Placeholder: "json",
Description: "The format of the message to be sent. If set to 'json', the message will be sent as a JSON object. If set to 'text', the message will be sent as a plain text string. By default json is used.",
PropertyName: "messageFormat",
Required: false,
},
{
Label: "Client ID",
Element: ElementTypeInput,
InputType: InputTypeText,
Placeholder: "",
Description: "The client ID to use when connecting to the MQTT broker. If blank, a random client ID is used.",
PropertyName: "clientId",
Required: false,
},
{
Label: "Message",
Element: ElementTypeTextArea,
Placeholder: alertingTemplates.DefaultMessageEmbed,
PropertyName: "message",
},
{
Label: "Username",
Description: "The username to use when connecting to the MQTT broker.",
Element: ElementTypeInput,
InputType: InputTypeText,
Placeholder: "",
PropertyName: "username",
Required: false,
},
{
Label: "Password",
Description: "The password to use when connecting to the MQTT broker.",
Element: ElementTypeInput,
InputType: InputTypeText,
Placeholder: "",
PropertyName: "password",
Required: false,
Secure: true,
},
{
Label: "Disable certificate verification",
Element: ElementTypeCheckbox,
Description: "Do not verify the broker's certificate chain and host name.",
PropertyName: "insecureSkipVerify",
Required: false,
},
},
},
{
Type: "opsgenie",
Name: "OpsGenie",

View File

@ -56,7 +56,8 @@ export type GrafanaNotifierType =
| 'pushover'
| 'LINE'
| 'kafka'
| 'wecom';
| 'wecom'
| 'mqtt';
export type CloudNotifierType =
| 'oncall' // Only FE implementation for now