4NK_env/IA_agents/monitoring-progress.md

Documentation du Système de Monitoring et Progression

Vue d'ensemble

Ce document décrit le système de monitoring et de progression mis en place pour le déploiement LeCoffre Node. Le système permet de suivre en temps réel la progression des différents processus (IBD Bitcoin, scans BlindBit, synchronisation SDK Relay, etc.) et d'afficher des informations détaillées sur l'état de tous les services.

Architecture du Système

1. Healthchecks Informatifs dans docker-compose.yml

Chaque service dispose maintenant d'un healthcheck qui affiche des informations de progression au lieu de simples codes de retour.

Bitcoin Signet

healthcheck:
  test: ["CMD", "sh", "-c", "info=$(bitcoin-cli -conf=/etc/bitcoin/bitcoin.conf getblockchaininfo 2>/dev/null || echo '{}'); blocks=$(echo \"$info\" | jq -r '.blocks // 0'); headers=$(echo \"$info\" | jq -r '.headers // 0'); if [ \"$blocks\" -eq \"$headers\" ] && [ \"$blocks\" -gt 0 ]; then echo \"Bitcoin sync complete: $blocks blocks\"; exit 0; else echo \"Bitcoin IBD: $blocks/$headers blocks ($(($headers - $blocks)) remaining)\"; exit 1; fi"]
  interval: 30s
  timeout: 10s
  retries: 3

Messages affichés :

• Bitcoin sync complete: 136548 blocks (quand synchronisé)
• Bitcoin IBD: 34729/136548 blocks (101819 remaining) (pendant la synchronisation)

BlindBit Oracle

healthcheck:
  test: ["CMD", "sh", "-c", "code=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:8000/tweaks/1); if [ \"$code\" = \"200\" ]; then echo \"BlindBit ready: Oracle service responding\"; exit 0; elif [ \"$code\" = \"000\" ]; then echo \"BlindBit starting: Oracle service not yet ready\"; exit 1; else echo \"BlindBit scanning: Oracle responding with code $code\"; exit 1; fi"]
  interval: 15s
  timeout: 5s
  retries: 10

Messages affichés :

• BlindBit ready: Oracle service responding (prêt)
• BlindBit starting: Oracle service not yet ready (démarrage)
• BlindBit scanning: Oracle responding with code 404 (scan en cours)

SDK Relay

healthcheck:
  test: ["CMD", "sh", "-c", "if curl -f http://localhost:8091/ >/dev/null 2>&1; then echo 'SDK Relay ready: WebSocket server responding'; exit 0; else echo 'SDK Relay IBD: Waiting for Bitcoin sync to complete'; exit 1; fi"]
  interval: 30s
  timeout: 10s
  retries: 3

Messages affichés :

• SDK Relay ready: WebSocket server responding (prêt)
• SDK Relay IBD: Waiting for Bitcoin sync to complete (en attente)

Autres Services

Tous les autres services (SDK Storage, SDK Signer, LeCoffre Backend/Frontend, IHM Client, Grafana, Loki, Promtail, Status API) ont des healthchecks similaires avec des messages informatifs.

2. Scripts de Monitoring

monitor-progress.sh

Script principal pour afficher un aperçu complet de tous les services.

Fonctionnalités :

• Statut de tous les services avec codes couleur
• Progression Bitcoin avec pourcentage et barre de progression
• Progression BlindBit avec état du scan
• Progression SDK Relay avec état WebSocket
• Statut des autres services

Utilisation :

./scripts/monitor-progress.sh

Exemple de sortie :

========================================
  LeCoffre Node - Monitoring Progress
========================================

Service Status:
  ✓ Bitcoin Signet: Ready
  ✓ BlindBit Oracle: Ready
  ✓ SDK Storage: Ready
  ⚠ SDK Relay: Starting/Processing
  ✗ LeCoffre Backend: Stopped
  ✗ LeCoffre Frontend: Stopped
  ✓ IHM Client: Ready

Bitcoin Progress:
  ⏳ Bitcoin IBD: 34729/136548 blocks (101819 remaining) - 25%

BlindBit Progress:
  ✓ BlindBit ready: Oracle service responding

SDK Relay Progress:
  ⏳ SDK Relay starting: WebSocket server not yet ready

Other Services Progress:
  ✓ SDK Storage ready: API responding
  ✓ SDK Signer ready: WebSocket server responding
  ✓ IHM Client ready: Vite dev server responding
  ✓ Grafana ready: Dashboard service responding

watch-progress.sh

Script de surveillance en temps réel avec rafraîchissement automatique.

Fonctionnalités :

• Mise à jour automatique toutes les 10 secondes
• Barre de progression Bitcoin
• Statut des services en temps réel
• Services en attente de dépendances

Utilisation :

./scripts/watch-progress.sh

Contrôles :

• Ctrl+C pour arrêter la surveillance

logs-with-progress.sh

Script pour afficher les logs des services avec informations de progression.

Fonctionnalités :

• Logs en temps réel ou statiques
• Informations de progression selon le service
• Support de tous les services
• Options de personnalisation

Utilisation :

# Logs Bitcoin avec progression
./scripts/logs-with-progress.sh bitcoin -p -n 10

# Logs SDK Relay avec progression
./scripts/logs-with-progress.sh sdk_relay -p -f

# Logs BlindBit avec progression
./scripts/logs-with-progress.sh blindbit -p -n 50

Options :

• -f, --follow : Suivre les logs en temps réel
• -n, --lines N : Afficher les N dernières lignes
• -p, --progress : Afficher la progression
• -h, --help : Aide

start-with-progress.sh

Script de démarrage ordonné avec suivi de progression.

Fonctionnalités :

• Démarrage des services dans l'ordre correct
• Attente de la santé de chaque service
• Affichage de la progression pendant l'attente
• Test de l'accès externe à la fin

Utilisation :

./scripts/start-with-progress.sh

Ordre de démarrage :

1. Tor
2. Bitcoin (avec suivi IBD)
3. BlindBit (avec suivi scan)
4. SDK Storage
5. SDK Relay (avec suivi IBD)
6. SDK Signer
7. IHM Client
8. LeCoffre Backend
9. LeCoffre Frontend
10. Services de monitoring

Codes Couleur et Symboles

Symboles de Statut

• ✓ : Service prêt et fonctionnel
• ⚠ : Service en cours de traitement
• ⏳ : Service en cours de démarrage
• ✗ : Service arrêté ou en erreur
• ℹ : Service en cours d'exécution (pas de healthcheck)

Codes Couleur

• Vert : Service prêt et fonctionnel
• Jaune : Service en cours de traitement/démarrage
• Rouge : Service arrêté ou en erreur
• Bleu : Informations générales
• Cyan : Progression spécifique
• Violet : En-têtes de sections

Progression des Services

Bitcoin IBD (Initial Block Download)

• Affichage : Bitcoin IBD: 34729/136548 blocks (101819 remaining) - 25%
• Barre de progression : [████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 25%
• Condition de santé : blocks == headers && blocks > 0

BlindBit Oracle

• États : Starting → Scanning → Ready
• Codes HTTP : 000 (non prêt), 404 (scan), 200 (prêt)
• Messages : État du scan et réponse du service

SDK Relay

• Dépendance : Bitcoin synchronisé
• États : IBD → WebSocket Ready
• Messages : Progression du scan et état WebSocket

Intégration avec Docker Compose

Variables d'Environnement

Le système utilise les variables du fichier .env.master :

• SDK_RELAY_* : Configuration du service relay
• SIGNER_* : Configuration du service signer
• VITE_* : Configuration des applications frontend

Commandes Docker Compose

# Démarrage avec variables centralisées
docker compose --env-file .env.master up -d

# Redémarrage d'un service
docker compose --env-file .env.master restart bitcoin

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

Surveillance et Maintenance

Vérification de l'État

# Statut de tous les services
docker compose --env-file .env.master ps

# Logs d'un service spécifique
docker logs bitcoin-signet --tail 50

# Healthcheck d'un service
docker inspect --format='{{.State.Health.Status}}' bitcoin-signet

Dépannage

1. Service en état "unhealthy" : Vérifier les logs avec docker logs <service>
2. Progression bloquée : Vérifier la connectivité réseau et les dépendances
3. Services en attente : Vérifier que les services de dépendance sont "healthy"

Exemples d'Utilisation

Surveillance Continue

# Démarrer la surveillance en temps réel
./scripts/watch-progress.sh

# Dans un autre terminal, afficher les logs
./scripts/logs-with-progress.sh bitcoin -p -f

Démarrage Complet

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

# Démarrer avec suivi de progression
./scripts/start-with-progress.sh

Vérification Rapide

# Aperçu rapide de tous les services
./scripts/monitor-progress.sh

# Logs récents avec progression
./scripts/logs-with-progress.sh sdk_relay -p -n 20

Personnalisation

Ajout de Nouveaux Services

1. Ajouter le healthcheck dans docker-compose.yml
2. Mettre à jour monitor-progress.sh avec le nouveau service
3. Ajouter la logique de progression dans logs-with-progress.sh

Modification des Intervalles

• Healthchecks : Modifier interval dans docker-compose.yml
• Surveillance : Modifier le sleep dans watch-progress.sh
• Logs : Utiliser l'option -n pour le nombre de lignes

Bonnes Pratiques

1. Utiliser les scripts plutôt que les commandes Docker directes
2. Surveiller la progression pendant les déploiements
3. Vérifier les dépendances avant de démarrer les services
4. Consulter les logs en cas de problème
5. Utiliser les variables centralisées du fichier .env.master

Dépannage Courant

Bitcoin IBD Lent

• Vérifier la connectivité réseau
• Vérifier l'espace disque disponible
• Consulter les logs pour les erreurs de connexion

Services en Attente

• Vérifier que les services de dépendance sont "healthy"
• Consulter les logs des services de dépendance
• Vérifier la configuration des dépendances dans docker-compose.yml

Healthchecks Échoués

• Vérifier que les ports sont accessibles
• Consulter les logs du service
• Vérifier la configuration du healthcheck

Ce système de monitoring et de progression permet une surveillance complète et en temps réel du déploiement LeCoffre Node, facilitant le diagnostic et la maintenance des services.