Dépannage des erreurs courantes

Hub

Le Hub s’arrête immédiatement au démarrage

Consultez les journaux :

docker compose logs watchflare

journalctl -u watchflare-hub -n 50

Le tableau de bord est injoignable

Docker :

• Vérifiez que le conteneur tourne : docker compose ps
• Vérifiez le port exposé : 8080 par défaut. Définissez HUB_PORT=80 dans .env pour utiliser le port 80.
• Derrière un pare-feu, assurez-vous que le port 8080 (ou votre HUB_PORT) est ouvert.

Binaire :

• Vérifiez que le service tourne : sudo systemctl status watchflare-hub
• Le Hub écoute sur le port 8080 par défaut. Assurez-vous qu’il est ouvert dans le pare-feu.
• Consultez les journaux : journalctl -u watchflare-hub -n 30

Cookie de session non marqué Secure après la configuration HTTPS

Consultez le guide de configuration HTTPS. La cause la plus fréquente est que TRUSTED_PROXIES n’inclut pas l’IP du reverse proxy.

Agent

L’hôte reste pending après l’installation de l’agent

Le jeton d’enrôlement a expiré. Les jetons sont valables 24 heures à compter de leur création.

Correctif : ouvrez la page de détail de l’hôte → ⋯ menu → Regenerate token, puis relancez la commande d’installation avec le nouveau jeton.

L’hôte reste offline après le démarrage de l’agent

Consultez les journaux de l’agent :

# Linux
journalctl -u watchflare-agent -n 30

# macOS
tail -30 $(brew --prefix)/var/log/watchflare-agent.log

Bannière Clock desync sur la page de détail de l’hôte

L’horloge de l’agent diffère de celle du Hub de plus de 5 minutes. Le Hub refuse toutes les requêtes gRPC de cet agent.

Correctif : synchronisez l’horloge de l’agent avec NTP.

# Linux : vérifiez l'état
timedatectl status

# Linux : synchronisez immédiatement
sudo systemctl restart systemd-timesyncd

La bannière disparaît automatiquement dès qu’un heartbeat valide est reçu.

configuration error au démarrage

Le binaire de l’agent est installé mais n’est pas enrôlé. Le journal affiche configuration error avec error="config file not found...". Enrôlez-le :

sudo watchflare-agent register \
  --token wf_reg_YOUR_TOKEN \
  --host YOUR_HUB_IP \
  --port 50051

Métriques

Les métriques n’apparaissent pas sur un hôte nouvellement installé

Le premier lot de métriques arrive dans les 30 secondes après le démarrage de l’agent. Si rien n’apparaît après 60 secondes, consultez les journaux de l’agent pour y trouver les erreurs de connexion (voir L’hôte reste offline).

Trous dans les graphiques de métriques (métriques abandonnées)

Les trous dans les graphiques indiquent que l’agent n’a pas pu envoyer les métriques pendant cette période. Deux causes distinctes :

Hub injoignable, WAL saturé :

Si le Hub était injoignable pendant une période prolongée, le Write-Ahead Log de l’agent a pu saturer. Par défaut, le WAL contient 10 Mo de données (~3 000 échantillons de métriques). Une fois plein, les enregistrements les plus anciens sont abandonnés sans notification à mesure que les nouveaux sont écrits.

L’agent consigne un avertissement lorsque cela se produit :

WARN   WAL exceeds max size, truncating  max_mb=10
WARN   WAL exceeds max size on startup, truncating  max_mb=10

Pour réduire le risque de perte de données pendant les longues coupures, augmentez wal_max_size_mb dans agent.conf et redémarrez l’agent. Voir wal_max_size_mb.

WAL désactivé :

Si wal_enabled = false dans agent.conf, les métriques sont envoyées directement et ne sont pas mises en tampon. Tout envoi en échec est perdu définitivement :

ERROR  send failed, metrics lost (WAL disabled)  error="..."

Réactivez le WAL (wal_enabled = true) et redémarrez l’agent.

La température affiche toujours 0

La collecte de température ne tourne que sur les hôtes physiques. Elle est omise sur :

• les machines virtuelles (pas d’accès aux capteurs physiques)
• les conteneurs Docker

C’est le comportement attendu. Voir Métriques système.

Métriques disque ou réseau manquantes

Ces métriques sont omises lorsque l’agent tourne à l’intérieur d’un conteneur Docker (pas sur l’hôte). Installez l’agent directement sur l’OS hôte pour collecter les métriques disque et réseau.

Si l’agent tourne sur l’hôte mais que les métriques disque manquent, vérifiez que l’agent n’est pas mal catégorisé comme un conteneur :

journalctl -u watchflare-agent -n 5
# Recherchez : environment detected  type="Physical Host"

L’onglet Containers n’est pas visible

L’onglet Containers n’apparaît qu’après activation des métriques conteneur et réception d’au moins un lot.

Vérifiez :

1. container_metrics = true est défini dans agent.conf
2. L’utilisateur watchflare est dans le groupe docker : groups watchflare
3. Docker tourne : docker ps
4. L’agent a été redémarré après le changement de groupe : sudo systemctl restart watchflare-agent

Voir Métriques de conteneurs Docker pour la configuration complète.

Inventaire de paquets

Les paquets n’apparaissent pas après l’installation de l’agent

Le premier scan de paquets s’exécute 60 secondes après le démarrage de l’agent, pas immédiatement. Attendez au moins 90 secondes après l’installation, puis consultez l’onglet Packages.

Pour déclencher un scan immédiatement : page de détail de l’hôte → onglet Packages → Collect now.

L’inventaire quotidien ne se met pas à jour

Le scan programmé s’exécute à 03:00, heure locale de l’hôte surveillé. Si l’hôte était hors ligne à 03:00, le scan est omis jusqu’au lendemain.

Pour forcer un scan immédiat : page de détail de l’hôte → onglet Packages → Collect now.

Consultez les journaux de l’agent pour y trouver les erreurs de collecte :

journalctl -u watchflare-agent -n 50 | grep -i package

Il manque des paquets dans l’inventaire

Chaque collecteur ne s’active que si son outil est installé. Si npm n’est pas dans le PATH de l’utilisateur de service watchflare, le collecteur npm est omis sans notification.

Activez le journal de débogage pour voir quels collecteurs ont tourné :

WATCHFLARE_DEBUG=1 sudo -u watchflare watchflare-agent run

Alertes et notifications

Aucun e-mail d’alerte reçu

1. Vérifiez que le SMTP est configuré et activé : Settings → Notifications
2. Utilisez Send test email pour vérifier que la connexion fonctionne
3. Vérifiez la fenêtre de durée de l’alerte. Une métrique doit dépasser le seuil en continu pendant la durée configurée (5 minutes par défaut) avant qu’un e-mail soit envoyé
4. Les notifications vont à l’adresse configurée dans Settings → Notifications. Vérifiez qu’elle est correcte

L’e-mail de test échoue

Les canaux de notification ne reçoivent rien

1. Utilisez le bouton Test à côté du canal dans Settings > Notifications. S’il renvoie une erreur, l’URL ou la destination est injoignable
2. Vérifiez que le canal est activé (l’interrupteur est allumé)
3. Vérifiez la fenêtre de durée de l’alerte. Comme pour l’e-mail, un dépassement de seuil doit être maintenu pendant toute la durée avant qu’une notification ne se déclenche
4. Vérifiez que l’URL suit le format Shoutrrr de ce service (voir Canaux de notification pour les modèles d’URL pris en charge)
5. Le Hub consigne les échecs de livraison au niveau ERROR. Consultez les journaux du Hub si un canal spécifique échoue en silence

TLS et certificats

Les agents refusent de se connecter après un redémarrage du Hub

Si vous avez retiré server.pem pour forcer le renouvellement du certificat, le Hub a régénéré à la fois la CA et le certificat serveur. Les agents ont épinglé l’ancienne CA et rejettent désormais la nouvelle.

Correctif : réenrôlez chaque agent concerné.

# Linux
sudo systemctl stop watchflare-agent
sudo rm /etc/watchflare/agent.conf /etc/watchflare/ca.pem
sudo watchflare-agent register --token wf_reg_YOUR_TOKEN --host YOUR_HUB_IP
sudo systemctl start watchflare-agent

Le port gRPC est injoignable via un reverse proxy

Le port gRPC (50051) doit être proxifié au niveau TCP, sans terminaison TLS. Les agents épinglent la CA du Hub. Si un proxy présente un autre certificat, tous les agents refuseront de se connecter.

Consultez le guide Reverse proxy pour la configuration de passthrough TCP Traefik, Nginx et Caddy.