Trouvez les pièges d’import avant la mise en ligne du dashboard.

22 règles sur une véritable analyse du dashboard : 7 erreurs, 11 avertissements et 4 notes. Les erreurs sont celles qui changent ce que fait Grafana — une variable de template que rien ne déclare, un placeholder ${DS_…} sans bloc __inputs, un panneau AngularJS qui n’affiche rien sur Grafana 11–12, deux panneaux partageant un id, un repeat sur une variable inexistante, un panneau sans type, et une schemaVersion si ancienne que le JSON et l’affichage sont deux dashboards différents. Les avertissements sont les problèmes de portabilité et de relecture : un uid absent, un id de base de données laissé dans un fichier committé, une datasource référencée par nom, un panneau graph ou singlestat déprécié, un panneau invisible de largeur nulle, une plage de temps par défaut de plus d’un an, un refresh sous dix secondes. Chaque règle a sa propre sous-section sur cette page, et les puces de règle du playground y renvoient directement.

Non. Le parseur et toutes les règles sont du JavaScript exécuté dans votre onglet — pas de serveur, pas d’appel d’API, pas de journalisation, donc 0 octet envoyé. Cela compte plus ici que pour la plupart des outils : le JSON d’un dashboard est une carte de votre parc interne. Noms de métriques, uids de datasources, noms d’hôtes dans les formats de légende, noms de service dans les requêtes de variables, parfois une URL interne dans un lien de panneau. C’est exactement le fichier qu’il ne faut pas coller dans un formateur en ligne quelconque.

Non, et l’outil le dit plutôt que de le laisser croire. Le schéma de dashboard de Grafana est vaste, versionné et encore mouvant : une vérification partielle présentée comme une vérification de schéma serait pire que pas de vérification du tout. Ce qui est fait ici est un lint structurel : il lit les formes qui cassent les imports et les relectures — variables, références de datasource, types de panneau, ids, mise en page, temps et refresh — et nomme le chemin JSON de chaque résultat. Il n’analyse pas PromQL, ne connaît pas vos plugins et ne parle à aucun Grafana. La liste complète de ce qu’il passe volontairement sous silence est plus haut, dans « Ce qu’il ne signale pas volontairement ».

Parce que le fichier a été produit par « Export for sharing externally ». Cet export remplace chaque référence de datasource par un placeholder — ${DS_PROMETHEUS} — et ajoute un bloc « __inputs » décrivant ce dont chaque placeholder a besoin. Seule la boîte de dialogue Dashboards → Import lit ce bloc et vous demande de choisir une vraie datasource. Provisionner le même fichier, le POSTer à l’API ou le déposer dans un dossier synchronisé par Git contourne complètement la boîte de dialogue : le placeholder survit dans le dashboard enregistré et tous les panneaux échouent à le résoudre. Soit vous importez via la boîte de dialogue, soit vous substituez la vraie { type, uid } avant de provisionner. Ce linter signale le placeholder comme une erreur dans les deux cas, parce que le fichier n’est pas provisionnable en l’état.

Le uid est l’identifiant que vous choisissez. Il fait partie de l’URL du dashboard, c’est lui que le provisioning et l’API adressent, et il doit vivre dans le contrôle de version à côté du JSON. Le id est un numéro de ligne dans la base de données d’une seule instance Grafana : ailleurs, il ne signifie rien. Un fichier avec uid met à jour le même dashboard à chaque import ; un fichier sans uid crée une nouvelle copie à chaque fois. Un fichier avec un id périmé échoue à l’import ou cible un dashboard qui n’a rien à voir avec le vôtre : c’est pourquoi un export devrait porter « id » : null.

Les panneaux du cœur graph, singlestat et table-old sont migrés automatiquement au chargement du dashboard : ils continuent donc de fonctionner — mais le JSON de votre dépôt n’est pas migré, ce qui veut dire que le fichier que vous relisez et le panneau que Grafana affiche sont deux choses différentes. Réenregistrez le dashboard depuis Grafana 9 ou plus récent pour inscrire la migration dans le fichier. Les PLUGINS de panneau AngularJS sont une autre histoire : grafana-piechart-panel, grafana-worldmap-panel et les autres n’ont aucune migration automatique, et le support d’Angular a été déprécié dans Grafana 9 puis retiré au fil de Grafana 11–12. Ces panneaux n’affichent rien et doivent être remplacés à la main.

Le jeu de règles est épinglé à grafana-12 / schemaVersion 41, imprimé sur cette page et sur chaque rapport copié, pour qu’un rapport ne soit jamais ambigu sur ce qui l’a vérifié. Les règles sensibles à la version sont formulées comme des plages — « Grafana 9–12 », « retiré au fil de Grafana 11–12 » — plutôt que comme une version exacte, parce que votre instance se situe près de ce point et non exactement dessus. Si la schemaVersion de votre dashboard dépasse 41, vous recevez une NOTE qui le dit et les résultats propres au schéma sont marqués comme indicatifs. Un schéma inconnu est une limite de ce linter, pas un défaut de votre dashboard : il n’est donc jamais signalé comme une erreur.

Parce que Grafana n’échoue pas : il n’interpole rien et exécute la requête avec le texte littéral dedans. Un sélecteur PromQL {env="$env"} ne correspond à aucune série, le panneau est donc vide ; un sélecteur avec correspondance par regex peut correspondre à BIEN PLUS de séries que voulu, le panneau est donc rempli et faux. Aucun des deux cas ne produit de message où que ce soit dans l’interface. La seule exception que fait ce linter concerne une référence à l’intérieur d’une chaîne qui ressemble à une expression régulière, où « $ » est aussi une ancre de fin de ligne : là, le résultat descend à un avertissement, parce que le « $env » que vous avez écrit peut réellement avoir été une ancre suivie de texte.

Jusqu’à 5 000 000 caractères, ce qui couvre un dashboard généré de plusieurs milliers de panneaux ; un dashboard de 500 panneaux est analysé en quelques millisecondes. Au-delà, il refuse avec un message plutôt que de figer votre onglet, parce qu’une entrée de cette taille est un journal ou une archive, pas un dashboard. Les résultats sont plafonnés aussi : 50 par règle et 400 au total, et le panneau indique le plafond et le nombre réel dès que l’un s’applique — une liste tronquée qui ne dirait pas qu’elle est tronquée serait exactement le genre d’erreur silencieuse que cet outil existe pour attraper.