Observabilité Grafana
Voici les pratiques issues d'une pile auto-hébergée de qualité production : environ 60 tableaux de bord, plus de 400 règles d'alerte, 50 jobs de scraping, ainsi que des logs et des traces, le tout géré comme du code. Chaque règle ci-dessous existe parce que sa violation a causé un incident réel. Le pourquoi est donné pour que vous puissiez juger des cas limites.
Choisissez d'abord le mode
- Apprentissage ("apprends-moi", "explique", "qu'est-ce que", "interroge-moi") : suivez references/learning-path.md. Enseignez une étape à la fois et exécutez le laboratoire dans assets/lab/. Vérifiez la compréhension avant de passer à l'étape suivante. Ne déversez pas toutes les étapes d'un coup.
- Construction (un tableau de bord, une alerte, un pipeline, du Terraform ou un déploiement) : suivez le flux de travail ci-dessous et ouvrez uniquement le fichier de référence nécessaire à la tâche.
- Planification d'un déploiement dans une organisation : references/implementation-plan.md.
La pile en une image
apps / hôtes / kit réseau / APIs cloud
│ métriques (exportateurs, /metrics) │ logs (fichiers, docker, syslog) │ traces (OTLP)
▼ ▼ ▼
Prometheus ◄── scrape ── Grafana Alloy (collecteur : découvrir, relabeliser, masquer, expédier)
│ │ │
│ Loki Tempo
└──────────────────┬─────────────────────┴──────────────────────────────────┘
▼
Grafana ── tableaux de bord, Explore, alerting ──► points de contact (chat, e-mail, astreinte)
▲
Terraform (dossiers, sources de données, règles, routage) + scripts (tableaux de bord) + git
Détails : references/architecture.md.
Les règles strictes
- Le code est la source de vérité. Modifiez l'alerting via Terraform et construisez les tableaux de bord avec un script générateur ou du JSON qui vit dans git. Un clic dans l'interface utilisateur est perdu lors du prochain apply, ou pire, le prochain apply le revert silencieusement.
- Avant tout apply, vérifiez les deux types de dérive. (a) Règles qui existent en direct mais pas dans le code : un apply non ciblé les supprime. (b) Règles qui sont dans le code mais ont été modifiées en direct : un apply les revert. Un plan "Aucune modification" ne prouve rien concernant les règles que Terraform n'a jamais vues. Voir references/as-code.md.
- Protégez le plan sauvegardé. Exécutez
terraform plan -out, puis refusez toute suppression/remplacement que vous n'avez pas intentionnellement prévue, sur toute ressource. Mettezprevent_destroysur les dossiers. Supprimer un dossier Grafana supprime tous les tableaux de bord et toutes les règles qu'il contient. - Utilisez un jeton de compte de service, jamais
admin:password. Si l'état a été créé avec une authentification par jeton, un apply en authentification basique planifie la suppression et la recréation des dossiers, des points de contact et de l'arbre de politiques. Cela a déjà effacé 59 tableaux de bord et tout l'arbre de routage en un seul apply. - Ne mettez jamais
notification_settings(un point de contact) sur une règle. Une règle qui en possède un contourne complètement l'arbre de politiques. Elle échappe au routage par sévérité, aux intervalles de répétition et aux périodes de silence. Dans un parc, 196 règles sur 217 faisaient cela et personne ne l'avait remarqué. - Mettez le seuil dans l'étape de seuil de Grafana, pas dans la PromQL. Avec
expr > 90, un hôte sain ne renvoie aucune série, ce que Grafana interprète comme NoData, pas OK. Interrogez la valeur brute ; comparez-la dans l'étape C. - Routez par actionnabilité et traitez les intervalles de répétition comme le véritable levier. Utilisez
severity(critical/warning/info) plusurgency=backlogpour les problèmes chroniques et connus. La plupart du bruit des alertes vient des re-notifications de quelque chose déjà connu. Répétez les alertes critiques quotidiennement et les avertissements hebdomadairement, pas toutes les heures. - L'escalade doit être un délai, et un silence est l'accusé de réception. La route d'astreinte utilise
group_waitd'environ 15 minutes, donc elle n'astreint que si l'alerte est toujours en cours et non silencée. Les règles de type événement ont besoin dekeep_firing_for≥ ce délai, sinon elles se résolvent avant même de pouvoir escalader. - Surveillez la surveillance. Surveillez les échecs d'évaluation, les échecs de livraison de notifications, les alertes supprimées (silencées), les exportateurs obsolètes et les sauvegardes qui se sont arrêtées. Un système d'alerting silencieux ressemble exactement à un système sain. Voir references/meta-monitoring.md.
- Vérifiez, ne faites pas confiance. Exécutez chaque requête de panneau ou d'alerte sur la source de données avant de l'écrire. Après toute écriture API, relisez l'objet et affirmez que votre modification s'y trouve : la réponse POST ne vous dit pas quel contenu a été mis en ligne. Un accord entre deux personnes ou deux sessions n'est pas une vérification ; une commande l'est.
Flux de travail pour toute modification
- Énoncez la question à laquelle le panneau ou l'alerte répond, et qui agit dessus. Si personne n'agirait sur une alerte, c'est un panneau de tableau de bord, pas une alerte.
- Prouvez la requête dans Explore ou via l'API proxy de la source de données. Vérifiez qu'elle renvoie des données, que les étiquettes sont celles selon lesquelles vous allez grouper ou router, et comment elle se comporte en état sain (vide ? zéro ?).
- Écrivez-la dans le code : un groupe de règles Terraform, un générateur de tableaux de bord ou une configuration Alloy. Suivez references/alerting.md ou references/dashboards.md.
- Vérifiez la dérive, puis
terraform plan -out=tfplan. Lisez chaque bloc~réduit, en particulier surgrafana_notification_policy, car il décide où va chaque alerte. - Appliquez le plan sauvegardé avec un jeton de compte de service. Utilisez
-targeten cas de doute. - Relisez-le depuis l'API, confirmez que la règle s'évalue (l'état n'est pas Error/NoData), et pour les alertes, déclenchez un test de bout en bout jusqu'au véritable point de contact.
- Commitez avec le pourquoi. Laissez un commentaire dans le code chaque fois qu'un choix semble erroné mais est délibéré.
Définition de "terminé"
Règle d'alerte : dans Terraform ; étiquette severity définie ; les modèles de résumé et de description incluent l'hôte ou le service affecté ainsi que la valeur actuelle ; no_data_state choisi intentionnellement ; for suffisamment long pour ne pas osciller ; routée par l'arbre (pas de point de contact par règle) ; un lien vers un runbook ou une première étape dans la description ; testée de bout en bout ; elle ne double pas d'alerte avec une règle existante.
Tableau de bord : dans git (généré, ou exporté avec id/version supprimés) ; dans le bon dossier ; lié depuis le hub de vue d'ensemble et vice-versa ; variables pour env/hôte ; chaque panneau a un titre qui pose ou répond à une question ; unités et seuils définis ; keepTime sur les liens.
Nouvel exportateur ou nouvelle source de données : scrapé avec des étiquettes stables (env, team, service, role) ; couvert par la règle de flotte up == 0 (n'en ajoutez pas une séparée) ; s'il a une métrique de dernière exécution ou de fraîcheur, une règle de vétusté ; ajouté à l'audit de méta-surveillance ; la source de données a un uid fixe.
Index des références
| Fichier | Ouvrez-le quand... |
|---|---|
| learning-path.md | enseigner ou apprendre, étape par étape avec des laboratoires |
| architecture.md | choisir des composants, étiquettes, rétention, authentification, HA |
| queries.md | écrire du PromQL ou LogQL, ou une requête semble erronée |
| dashboards.md | construire ou réviser un tableau de bord |
| alerting.md | règles, routage, points de contact, silences, fatigue |
| as-code.md | Terraform, API, sauvegardes, dérive, restaurations |
| meta-monitoring.md | prouver que la surveillance elle-même fonctionne |
| implementation-plan.md | introduire Grafana à une équipe ou une entreprise |
Actifs : assets/lab/ est un laboratoire Docker Compose local. assets/terraform-starter/ est une pile Terraform de démarrage avec les paramètres sécurisés par défaut déjà câblés.