> ## Documentation Index
> Fetch the complete documentation index at: https://infra-docs.kaeyros.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Pièges connus de la stack de supervision

> Les douze pièges rencontrés en production sur la stack VictoriaMetrics, vmalert et Grafana. Aucun ne produit de message d'erreur. Chacun est maintenant bloqué par un test.

Chacun des douze pièges suivants a été rencontré en production sur la stack de supervision. Chacun est maintenant refusé par un test ou une règle quand c'était possible. Lisez-les attentivement: ils ont tous en commun de ne produire AUCUN message d'erreur apparent. Le silence est leur signature.

> **1. Le nom du backend Traefik est dans exported\_service, pas service**
>
> Le job de collecte pose déjà un label `service` sur la cible. Face à la collision, vmagent renomme celui de Traefik en `exported_service`. Agréger par `service` regroupe donc les 300 backends en une seule courbe nommée `traefik`, sans erreur.
>
> **Ce qui l'empêche maintenant**: `make valider` refuse toute expression citant `traefik_*` et agrégeant par `service`.

> **2. A or vector(0) ajoute une série fantôme**
>
> Ce n'est PAS "A, ou zéro si A est vide". L'opérateur `or` fait l'UNION sur les jeux d'étiquettes: `vector(0)` n'en porte aucune, donc il s'ajoute dès que A en porte une. Le panneau affiche la vraie valeur ET un zéro parasite.
>
> **Ce qui l'empêche maintenant**: écrire `or on() vector(0)`. Avec un jeu d'étiquettes vide, le zéro n'apparaît que si A est vraiment vide.

> **3. Une règle ne doit pas lire un enregistrement de son propre groupe**
>
> vmalert évalue un groupe règle par règle et publie de façon asynchrone. La valeur lue est celle du cycle précédent, vieille d'un intervalle entier. À 5 minutes, c'est la limite de péremption de VictoriaMetrics: la règle renvoie le vide une fois sur deux, sans erreur ni message.
>
> **Ce qui l'empêche maintenant**: `make valider` refuse ce motif. Consommer dans un autre groupe, ou écrire la valeur en clair.

> **4. Docker Compose interprète les \$ lus dans .env**
>
> Un hash bcrypt comme `$apr1$hC/bEyZf$faHem...` devient `admin:/bEyZf.` en silence, et le basic auth casse sans que rien ne le dise.
>
> **Ce qui l'empêche maintenant**: les apostrophes simples sont OBLIGATOIRES dans `.env` pour toute valeur contenant un `$`.

> \**5. vmagent refuse refresh\_interval dans un *\_sd\_configs**
>
> C'est valide chez Prometheus, pas chez vmagent: il rejette la configuration ENTIÈRE et sort en code 255. Le conteneur redémarre en boucle et le serveur ne se surveille plus.
>
> **Ce qui l'empêche maintenant**: utiliser `-promscrape.fileSDCheckInterval`. Un test le vérifie.

> **6. vmauth ajoute le chemin de la requête à url\_prefix**
>
> Un `url_prefix` contenant déjà `/api/v1/write` produit `/api/v1/write/api/v1/write`, un 400, et la perte silencieuse de toutes les métriques d'un cluster.
>
> **Ce qui l'empêche maintenant**: ne jamais mettre de chemin dans `url_prefix`. Un test le vérifie.

> **7. Alertmanager tourne sous nobody**
>
> Un `alertmanager.yml` en 0600 appartenant à l'administrateur le fait échouer en permission denied et redémarrer en boucle. Zéro alerte pendant une journée entière.
>
> **Ce qui l'empêche maintenant**: les configurations générées sont en 0644. Un test le vérifie.

> **8. promtool query instant NE VALIDE PAS la syntaxe**
>
> Il envoie la requête au serveur sans l'analyser localement: l'erreur de connexion arrive toujours en premier et masque l'erreur de syntaxe. Un contrôle bâti dessus rapporte "valide" sur du PromQL délibérément cassé.
>
> **Ce qui l'empêche maintenant**: utiliser `promtool check rules`, qui analyse réellement.

> **9. cmd | grep -q FAILED && false || true renvoie toujours vrai**
>
> Si grep trouve FAILED, `false` s'exécute puis `|| true` le rattrape: sortie 0. Sinon `|| true` renvoie 0 aussi. Le test des 261 règles a affiché OK sur des règles fausses pendant des semaines.
>
> **Ce qui l'empêche maintenant**: lire le code de sortie de l'outil, jamais la présence d'un mot dans sa sortie.

> **10. Du Python en ligne dans le Makefile casse à l'exécution**
>
> Entre make, le shell et Python, les guillemets échappés ne survivent pas. Trois cibles sortaient en SyntaxError sans que personne ne l'ait jamais remarqué, parce que l'erreur survient dans un tube et que make renvoie quand même 0.
>
> **Ce qui l'empêche maintenant**: tout Python de plus d'une ligne va dans `scripts/`. `make valider` refuse le reste.

> **11. tar sur macOS crée des jumeaux .\_**\*
>
> Ils sont recréés à l'extraction, y compris sur Linux. Grafana provisionne TOUS les `.json` d'un dossier et vmalert charge TOUS les `.yml`: un jumeau au mauvais endroit est lu comme une configuration.
>
> **Ce qui l'empêche maintenant**: préfixer par `COPYFILE_DISABLE=1`. `make ranger` nettoie ceux qui sont déjà là.

> **12. Les regex de vmagent sont entièrement ancrées**
>
> `coredns.*` ne correspond PAS à `rke2-coredns-rke2-coredns-abc`. Sur RKE2, les noms portent des préfixes de distribution, et cinq panneaux sont restés vides à cause de ça.
>
> **Ce qui l'empêche maintenant**: envelopper les filtres de nom: `.*coredns.*`.

## Point commun à retenir

> [!TIP]
>
> Aucun de ces douze pièges ne produit d'erreur visible. Le silence n'est jamais une bonne nouvelle sur cette stack. Si un panneau est vide, un test passe bizarrement, ou une alerte ne part pas, suspectez un piège avant de suspecter une panne.

Pour toute question ou pour signaler un nouveau piège, contactez l'équipe DevOps: [devops@kaeyros-analytics.com](mailto:devops@kaeyros-analytics.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.