L’alerting de Grafana comporte quatre éléments : les règles d’alerte décident quand quelque chose ne va pas, les points de contact indiquent où envoyer une notification, les politiques de notification acheminent les alertes vers les points de contact, et les mute timings (plages de mise en sourdine) et modèles (templates) déterminent quand et comment les messages partent. Les quatre peuvent être provisionnés depuis du YAML dans le dossier provisioning/alerting, ce qui rend l’alerting relisible au lieu d’être un tas de paramètres d’interface. Ce guide construit une petite chaîne fonctionnelle.

Les ressources d’alerting provisionnées ne peuvent pas être modifiées dans l’interface, et importer une ressource qui existe déjà provoque un conflit ; supprimez donc d’abord les doublons créés à la main. Chaque fichier commence par apiVersion: 1.

Points de contact

provisioning/alerting/contact-points.yaml :

apiVersion: 1

contactPoints:
  - orgId: 1
    name: team-slack
    receivers:
      - uid: team-slack-1
        type: slack
        disableResolveMessage: false
        settings:
          url: ${SLACK_WEBHOOK_URL}
          recipient: '#alerts'

  - orgId: 1
    name: oncall-email
    receivers:
      - uid: oncall-email-1
        type: email
        settings:
          addresses: oncall@example.com

Remarques :

• uid sur chaque récepteur doit être unique et stable. Grafana l’utilise pour mettre à jour le récepteur sur place.
• type est l’intégration, comme slack, email, webhook, pagerduty, opsgenie ou prometheus-alertmanager. Les clés sous settings dépendent du type ; consultez la documentation du vôtre.
• Les secrets proviennent de variables d’environnement avec $VAR ou ${VAR}, de sorte que l’URL du webhook ne vit jamais dans Git. Utilisez $$ pour conserver un signe dollar littéral.
• Pour en supprimer un, ajoutez deleteContactPoints avec son orgId et son uid.

Politiques de notification

L’arbre des politiques décide quel point de contact traite quelle alerte. Tout l’arbre est une seule ressource, et le provisionner écrase toutes les politiques existantes.

provisioning/alerting/policies.yaml :

apiVersion: 1

policies:
  - orgId: 1
    receiver: team-slack            # par défaut pour tout ce qui ne correspond pas ci-dessous
    group_by: ['alertname', 'namespace']
    group_wait: 30s
    group_interval: 5m
    repeat_interval: 4h
    routes:
      - receiver: oncall-email
        object_matchers:
          - ['severity', '=', 'critical']
        repeat_interval: 1h
      - receiver: team-slack
        object_matchers:
          - ['team', '=', 'platform']
        mute_time_intervals:
          - weekends

• receiver au sommet est le point de contact de repli.
• group_by regroupe les alertes liées en une seule notification.
• group_wait, group_interval, repeat_interval contrôlent la rapidité d’envoi du premier message, la fréquence des mises à jour pour un groupe, et la fréquence de répétition d’une alerte non résolue.
• routes sont des politiques enfants utilisant les mêmes champs. La première route correspondante l’emporte, sauf si vous définissez continue: true.
• object_matchers sont des triplets [label, opérateur, valeur]. Les opérateurs sont =, !=, =~ et !~.

Pour réinitialiser l’arbre à celui par défaut de Grafana, utilisez resetPolicies: [1] avec l’ID de l’organisation.

Mute timings

apiVersion: 1

muteTimes:
  - orgId: 1
    name: weekends
    time_intervals:
      - weekdays: ['saturday', 'sunday']
        location: 'UTC'

times (avec start_time et end_time), weekdays, months, years et days_of_month peuvent être combinés, et les plages utilisent les deux-points, comme 'monday:friday'. Supprimez avec deleteMuteTimes. Les mute timings ne peuvent pas utiliser l’interpolation de variables dans leurs noms ou leurs intervalles.

Modèles de notification

apiVersion: 1

templates:
  - orgId: 1
    name: slack_title
    template: |
      {{ define "slack_title" }}
        [{{ .Status | toUpper }}] {{ .CommonLabels.alertname }}
      {{ end }}

Référencez un modèle depuis les paramètres d’un point de contact (par exemple le champ title de Slack) sous la forme {{ template "slack_title" . }}. Les noms et le contenu des modèles ne prennent pas en charge l’interpolation de variables ; écrivez-les donc littéralement.

Règles d’alerte

Les règles sont organisées en groupes qui partagent un intervalle d’évaluation et résident dans un dossier. Chaque règle comporte une liste d’étapes de requête et d’expression, et une condition nommant l’étape qui décide si elle se déclenche.

provisioning/alerting/rules.yaml :

apiVersion: 1

groups:
  - orgId: 1
    name: webapp
    folder: Applications
    interval: 1m
    rules:
      - uid: webapp-down
        title: Webapp targets down
        condition: C
        for: 5m
        noDataState: NoData
        execErrState: Error
        labels:
          severity: critical
          team: platform
        annotations:
          summary: 'No healthy webapp targets for 5 minutes'
          runbook_url: https://runbooks.example.com/webapp-down
        data:
          - refId: A
            relativeTimeRange:
              from: 600
              to: 0
            datasourceUid: prometheus
            model:
              refId: A
              expr: sum(up{job="webapp"})
              instant: true
          - refId: B
            datasourceUid: __expr__
            model:
              refId: B
              type: reduce
              expression: A
              reducer: last
              datasource:
                type: __expr__
                uid: __expr__
          - refId: C
            datasourceUid: __expr__
            model:
              refId: C
              type: threshold
              expression: B
              conditions:
                - evaluator:
                    type: lt
                    params: [1]
              datasource:
                type: __expr__
                uid: __expr__

Comment le lire :

• L’étape A interroge Prometheus (via l’uid de la source de données que vous avez provisionnée) pour obtenir le nombre de cibles saines sur les dix dernières minutes. relativeTimeRange est en secondes.
• L’étape B réduit le résultat à une valeur unique. Les expressions utilisent l’UID spécial de source de données __expr__.
• L’étape C est un seuil : elle se déclenche quand la valeur est inférieure à 1. condition: C la désigne comme l’étape décisive.
• for: 5m exige que la condition tienne cinq minutes avant que l’alerte ne se déclenche, ce qui évite les oscillations.
• noDataState et execErrState indiquent quoi faire quand la requête ne renvoie rien ou échoue : NoData, Alerting ou OK pour le premier, et Error, Alerting ou OK pour le second.
• labels alimentent l’arbre des politiques de notification : severity: critical est ce qui a envoyé cette alerte sur la route oncall-email ci-dessus.
• uid (jusqu’à 40 caractères parmi lettres, chiffres, - et _) doit être unique et stable. Ajoutez éventuellement dashboardUid et panelId pour lier une règle à un panneau.
• Dossier : utilisez un dossier qui existe. Le plus simple est de réutiliser le titre d’un dossier créé par votre fournisseur de tableaux de bord.

L’interpolation de variables ne fonctionne pas dans les annotations de règles, relativeTimeRange, le model de la requête ni le contenu des modèles ; écrivez donc ces valeurs en toutes lettres.

Pour supprimer une règle, ajoutez deleteRules avec son orgId et son uid :

apiVersion: 1

deleteRules:
  - orgId: 1
    uid: webapp-down

Appliquer et vérifier

Les ressources d’alerting sont lues au démarrage ; redémarrez donc Grafana après avoir modifié les fichiers :

docker compose restart grafana

curl -s -u admin:$GRAFANA_ADMIN_PASSWORD \
  http://localhost:3000/api/v1/provisioning/alert-rules | jq '.[] | {uid, title, folderUID}'
curl -s -u admin:$GRAFANA_ADMIN_PASSWORD \
  http://localhost:3000/api/v1/provisioning/contact-points | jq '.[].name'
curl -s -u admin:$GRAFANA_ADMIN_PASSWORD \
  http://localhost:3000/api/v1/provisioning/policies | jq .receiver

Testez ensuite la livraison en abaissant temporairement un seuil, ou en envoyant une notification de test depuis l’API du point de contact.

Écrire les règles plus vite

Le YAML des règles est verbeux. Construisez une règle une fois dans une instance de test, exportez-la au format de provisionnement via l’API de provisionnement de l’alerting (les routes export sous /api/v1/provisioning/, avec ?format=yaml), puis commitez le résultat avec un uid stable. Pour de nombreuses règles similaires, générez le YAML à partir d’un modèle en CI, ou gérez-les avec Terraform ou le Grafana Operator, qui disposent tous deux de ressources de règles d’alerte.