grafana-observabilité

Apprendre, concevoir, construire et exploiter une pile d'observabilité Grafana (métriques Prometheus, logs Loki, traces Tempo, collecte Alloy, tableaux de bord et alerting Grafana) gérée comme du code avec Terraform. À utiliser lorsqu'on vous demande d'apprendre ou d'enseigner Grafana, PromQL ou LogQL ; de mettre en place une surveillance ; d'écrire ou de réviser un tableau de bord, une règle d'alerte, une politique de notification, un point de contact, un pipeline Alloy ou du Terraform Grafana ; ou de déboguer des alertes bruyantes, silencieuses, bloquées en NoData ou qui n'atteignent personne.

Qu'est-ce que grafana-observabilité ?

Cette compétence est un guide complet de production pour la pile d'observabilité Grafana, basé sur une expérience réelle avec environ 60 tableaux de bord, plus de 400 règles d'alerte, 50 jobs de scraping, et la gestion des logs et des traces. Conçue pour les ingénieurs DevOps, les administrateurs système et les développeurs qui utilisent des outils comme Claude Code, Cursor ou Codex, elle met l'accent sur l'infrastructure as code (IaC) via Terraform pour garantir que toutes les alertes, tableaux de bord et configurations soient versionnés et reproductibles. La compétence propose un mode `Apprentissage` pour les débutants, avec des parcours étape par étape et un laboratoire Docker local, et un mode `Construction` pour créer ou modifier des composants existants. Elle énonce des règles strictes, notamment : le code est la seule source de vérité ; il faut toujours vérifier la dérive avant un apply ; utiliser un token de compte de service plutôt que les identifiants admin ; ne jamais mettre de paramètres de notification directement sur une règle d'alerte ; et router les alertes par sévérité et actionnabilité. Enfin, elle fournit un index de documents de référence détaillés (alerting, tableaux de bord, requêtes, architecture, méta-surveillance, etc.) pour creuser des sujets spécifiques.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/louij2/grafana-observability-skill/tree/HEAD/.github/skills/grafana-observability

Installed? Explore more Productivité et collaboration skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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

  1. 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.
  2. 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.
  3. 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. Mettez prevent_destroy sur les dossiers. Supprimer un dossier Grafana supprime tous les tableaux de bord et toutes les règles qu'il contient.
  4. 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.
  5. 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é.
  6. 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.
  7. Routez par actionnabilité et traitez les intervalles de répétition comme le véritable levier. Utilisez severity (critical/warning/info) plus urgency=backlog pour 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.
  8. L'escalade doit être un délai, et un silence est l'accusé de réception. La route d'astreinte utilise group_wait d'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 de keep_firing_for ≥ ce délai, sinon elles se résolvent avant même de pouvoir escalader.
  9. 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.
  10. 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

  1. É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.
  2. 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 ?).
  3. É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.
  4. Vérifiez la dérive, puis terraform plan -out=tfplan. Lisez chaque bloc ~ réduit, en particulier sur grafana_notification_policy, car il décide où va chaque alerte.
  5. Appliquez le plan sauvegardé avec un jeton de compte de service. Utilisez -target en cas de doute.
  6. 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.
  7. 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

FichierOuvrez-le quand...
learning-path.mdenseigner ou apprendre, étape par étape avec des laboratoires
architecture.mdchoisir des composants, étiquettes, rétention, authentification, HA
queries.mdécrire du PromQL ou LogQL, ou une requête semble erronée
dashboards.mdconstruire ou réviser un tableau de bord
alerting.mdrègles, routage, points de contact, silences, fatigue
as-code.mdTerraform, API, sauvegardes, dérive, restaurations
meta-monitoring.mdprouver que la surveillance elle-même fonctionne
implementation-plan.mdintroduire 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.

Skills associés