4NK_env/IA_agents/troubleshooting-monitoring.md

Guide de Dépannage - Monitoring LeCoffre Node

Problèmes Courants et Solutions

1. Services en État "unhealthy"

Symptômes

• Service affiché comme "unhealthy" dans docker compose ps
• Healthcheck échoue constamment
• Service ne répond pas aux requêtes

Diagnostic

# Vérifier le statut du healthcheck
docker inspect --format='{{.State.Health.Status}}' <service>

# Vérifier les logs du healthcheck
docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' <service>

# Vérifier les logs du service
docker logs <service> --tail 50

Solutions

1. Vérifier la connectivité réseau

   # Vérifier que le service écoute sur le bon port
   docker exec <service> netstat -tlnp
   
   # Vérifier la connectivité depuis l'extérieur
   curl -f http://localhost:<port>/health
   

2. Vérifier les dépendances

   # Vérifier que les services de dépendance sont "healthy"
   docker compose --env-file .env.master ps
   

3. Redémarrer le service

   docker compose --env-file .env.master restart <service>
   

2. Progression Bitcoin Bloquée

Symptômes

• Bitcoin IBD reste à un pourcentage fixe
• Pas de nouveaux blocs téléchargés
• Messages d'erreur dans les logs

Diagnostic

# Vérifier l'état de la blockchain
docker exec bitcoin-signet bitcoin-cli -conf=/etc/bitcoin/bitcoin.conf getblockchaininfo

# Vérifier les connexions
docker exec bitcoin-signet bitcoin-cli -conf=/etc/bitcoin/bitcoin.conf getpeerinfo

# Vérifier les logs
docker logs bitcoin-signet --tail 100 | grep -E "(ERROR|error|Error|WARN|warn|Warn)"

Solutions

1. Vérifier la connectivité réseau

   # Vérifier que Tor fonctionne
   docker logs tor-proxy --tail 20
   
   # Vérifier la connectivité Bitcoin
   docker exec bitcoin-signet bitcoin-cli -conf=/etc/bitcoin/bitcoin.conf getnetworkinfo
   

2. Vérifier l'espace disque

   # Vérifier l'espace disponible
   df -h
   
   # Vérifier la taille du volume Bitcoin
   docker volume inspect 4nk_node_bitcoin_data
   

3. Redémarrer Bitcoin

   docker compose --env-file .env.master restart bitcoin
   

3. Services en Attente de Dépendances

Symptômes

• Services affichés comme "Stopped"
• Messages "dependency failed to start"
• Services ne démarrent pas

Diagnostic

# Vérifier les dépendances dans docker-compose.yml
grep -A 5 -B 5 "depends_on" docker-compose.yml

# Vérifier le statut des services de dépendance
docker compose --env-file .env.master ps

Solutions

1. Démarrer les services dans l'ordre correct

   # Utiliser le script de démarrage ordonné
   ./scripts/start-with-progress.sh
   

2. Vérifier les conditions de dépendance

   # Vérifier que les services de dépendance sont "healthy"
   docker inspect --format='{{.State.Health.Status}}' <service-dependance>
   

3. Modifier temporairement les dépendances

   # Changer condition: service_healthy en condition: service_started
   # (Attention : à remettre en place après résolution)
   

4. Erreurs de Connexion WebSocket

Symptômes

• SDK Relay ne répond pas sur le port 8091
• Erreurs 502 Bad Gateway pour les WebSockets
• Messages "TLS support not compiled in"

Diagnostic

# Vérifier que le service écoute sur le bon port
docker exec sdk_relay netstat -tlnp

# Vérifier les logs du service
docker logs sdk_relay --tail 50

# Tester la connectivité locale
curl -f http://localhost:8091/

Solutions

1. Vérifier la configuration Nginx

   # Vérifier la configuration WebSocket
   sudo grep -A 10 -B 5 "ws/" /etc/nginx/sites-enabled/dev4.4nkweb.com-https.conf
   
   # Tester la configuration Nginx
   sudo nginx -t
   

2. Vérifier les variables d'environnement

   # Vérifier la configuration du SDK Relay
   docker exec sdk_relay env | grep SDK_RELAY
   

3. Redémarrer le service

   docker compose --env-file .env.master restart sdk_relay
   

5. Problèmes de Permissions

Symptômes

• Erreurs "Permission denied"
• Services ne peuvent pas écrire dans les volumes
• Erreurs de montage de volumes

Diagnostic

# Vérifier les permissions des volumes
docker volume inspect <volume-name>

# Vérifier les permissions des dossiers locaux
ls -la logs/
ls -la conf/

Solutions

1. Corriger les permissions des volumes

   # Corriger les permissions des logs
   sudo chown -R 1000:1000 logs/
   sudo chmod -R 755 logs/
   

2. Vérifier la configuration des volumes

   # Vérifier la configuration dans docker-compose.yml
   grep -A 5 -B 5 "volumes:" docker-compose.yml
   

3. Redémarrer les services

   docker compose --env-file .env.master down
   docker compose --env-file .env.master up -d
   

6. Problèmes de Configuration

Symptômes

• Services ne démarrent pas
• Erreurs de configuration dans les logs
• Variables d'environnement manquantes

Diagnostic

# Vérifier la configuration Docker Compose
docker compose --env-file .env.master config

# Vérifier les variables d'environnement
docker exec <service> env | grep <VARIABLE>

# Vérifier les fichiers de configuration
cat .env.master | grep <VARIABLE>

Solutions

1. Vérifier le fichier .env.master

   # Vérifier que toutes les variables sont définies
   docker compose --env-file .env.master config --services
   

2. Corriger les variables manquantes

   # Ajouter les variables manquantes dans .env.master
   echo "VARIABLE=valeur" >> .env.master
   

3. Redémarrer les services

   docker compose --env-file .env.master down
   docker compose --env-file .env.master up -d
   

Outils de Diagnostic

Scripts de Diagnostic

# Diagnostic complet
./scripts/monitor-progress.sh

# Logs avec progression
./scripts/logs-with-progress.sh <service> -p -n 100

# Surveillance en temps réel
./scripts/watch-progress.sh

Commandes Docker Utiles

# Informations détaillées sur un service
docker inspect <service>

# Logs en temps réel
docker logs -f <service>

# Exécuter une commande dans un conteneur
docker exec -it <service> /bin/bash

# Vérifier l'utilisation des ressources
docker stats <service>

Commandes Système

# Vérifier l'espace disque
df -h

# Vérifier la mémoire
free -h

# Vérifier les processus
ps aux | grep docker

# Vérifier les ports
netstat -tlnp | grep <port>

Procédures de Récupération

Récupération Complète

# Arrêter tous les services
docker compose --env-file .env.master down

# Nettoyer le système Docker
docker system prune -af --volumes

# Redémarrer avec le script de progression
./scripts/start-with-progress.sh

Récupération d'un Service

# Arrêter le service
docker compose --env-file .env.master stop <service>

# Supprimer le conteneur
docker compose --env-file .env.master rm <service>

# Redémarrer le service
docker compose --env-file .env.master up -d <service>

Récupération des Volumes

# Arrêter tous les services
docker compose --env-file .env.master down

# Supprimer les volumes
docker volume rm <volume-name>

# Redémarrer les services
docker compose --env-file .env.master up -d

Logs et Monitoring

Logs Importants

# Logs Bitcoin
docker logs bitcoin-signet --tail 100

# Logs SDK Relay
docker logs sdk_relay --tail 100

# Logs BlindBit
docker logs blindbit-oracle --tail 100

# Logs Nginx
sudo tail -f /var/log/nginx/error.log

Monitoring des Ressources

# Utilisation des ressources
docker stats

# Espace disque
df -h

# Mémoire
free -h

# CPU
top

Prévention des Problèmes

Vérifications Régulières

1. Vérifier l'espace disque : df -h
2. Vérifier la mémoire : free -h
3. Vérifier les logs : ./scripts/monitor-progress.sh
4. Vérifier la connectivité : Tester les URLs externes

Maintenance Préventive

1. Nettoyer les logs : docker system prune -f
2. Vérifier les mises à jour : docker images
3. Sauvegarder les configurations : Copier .env.master
4. Tester les sauvegardes : Vérifier les volumes

Surveillance Continue

1. Utiliser les scripts de monitoring : ./scripts/watch-progress.sh
2. Configurer des alertes : Surveiller les logs d'erreur
3. Vérifier les performances : docker stats
4. Tester la connectivité : Vérifier les URLs externes

Ce guide de dépannage permet aux agents IA de diagnostiquer et résoudre rapidement les problèmes courants du système de monitoring LeCoffre Node.