> ## 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.

# Tâches courantes de la supervision

> Modifiez les dashboards, ajoutez des alertes, déployez la stack et diagnostiquez un panneau vide. Procédures pas à pas pour les opérations quotidiennes.

Cette page recense les quatre procédures que vous répétez le plus souvent sur la stack de supervision : modifier un dashboard, ajouter une alerte, déployer une mise à jour sur le serveur, et comprendre pourquoi un panneau reste vide. Chaque procédure est découpée en étapes concrètes avec les commandes exactes du Makefile.

## Modifier un dashboard

> [!WARNING]
>
> Les dashboards sont **générés**. Vous ne touchez **jamais** au JSON Grafana à la main, et vous ne modifiez **pas** l'interface Grafana directement. La source de vérité est le code Python du générateur.

**1. 1. Éditer la source de vérité**

```bash theme={null}
$EDITOR scripts/build-dashboards.py
```

**2. 2. Régénérer**

```bash theme={null}
make dashboards
```

Cette commande régénère les dashboards, valide la structure, dessine les aperçus textuels et met à jour la documentation embarquée.

**3. 3. Juger la mise en page**

```bash theme={null}
make apercu
```

Affiche un rendu textuel de la grille sans déployer quoi que ce soit sur le serveur.

> [!NOTE]
>
> Le générateur refuse de produire un dashboard si deux panneaux se recouvrent, si une largeur n'est pas un diviseur de 24, ou si un message d'absence de données pointe vers un titre de panneau qui n'existe plus. Ces garde-fous évitent de déployer des dashboards cassés.

## Ajouter une alerte

**1. 1. Éditer le fichier de règles**

```bash theme={null}
$EDITOR vmalert/rules/XX-domaine.yml
```

**2. 2. Valider**

```bash theme={null}
make valider
```

Vérifie la syntaxe PromQL, détecte les doublons de nom, et s'assure que chaque métrique référencée est réellement collectée.

**3. 3. Recharger vmalert**

```bash theme={null}
make reload
```

Recharge la configuration sans redémarrer le processus vmalert.

**4. 4. Vérifier qu'elle s'évalue**

```bash theme={null}
make regles-erreurs
```

> [!WARNING]
>
> La dernière étape n'est **pas** optionnelle. Une règle peut être syntaxiquement parfaite et échouer à chaque évaluation sans produire le moindre message d'erreur visible. `make regles-erreurs` détecte ces règles silencieusement cassées.

## Déployer sur le serveur

```bash Depuis votre poste theme={null}
COPYFILE_DISABLE=1 tar czf maj.tar.gz scripts vmalert grafana Makefile
scp maj.tar.gz admin@<serveur>:~/install/monitoring-stack/
```

```bash Sur le serveur theme={null}
ssh admin@<serveur>
cd ~/install/monitoring-stack && tar xzf maj.tar.gz
make ranger && make valider && make reload
```

> [!WARNING]
>
> `COPYFILE_DISABLE=1` n'est **pas** décoratif si vous travaillez sur macOS. Sans ce flag, tar embarque des fichiers parasites (`.DS_Store`, attributs étendus) qui perturbent le déploiement. Pour plus de détails, consultez la page [Pièges connus](https://infra-docs.kaeyros.org/supervision/pieges.md).

## Trouver pourquoi un panneau est vide

Un panneau vide n'est jamais anodin. Il signale soit une absence de données, soit une requête mal formée, soit un problème d'appariement de vecteurs. Le Makefile fournit trois outils de diagnostic.

```bash Diagnostic global theme={null}
make diagnostic
```

```bash Règle silencieuse ? theme={null}
make regles-erreurs
```

```bash Appariement de vecteurs theme={null}
make appariement A='<metrique>' B='<metrique>' SUR=<etiquette>
```

Le diagnostic global (`make diagnostic`) vérifie l'état des composants, la connectivité vers VictoriaMetrics et la présence des séries attendues. Si une alerte est concernée, `make regles-erreurs` révèle les règles qui échouent silencieusement. Enfin, `make appariement` vous aide à déboguer les requêtes PromQL où deux séries temporelles ne s'alignent pas sur leurs étiquettes.

Si vous bloquez sur un cas étrange, écrivez à [devops@kaeyros-analytics.com](mailto:devops@kaeyros-analytics.com).


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