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
```yaml
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
```yaml
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
```yaml
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 :**
```bash
./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 :**
```bash
./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 :**
```bash
# 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 :**
```bash
./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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Arrêter tous les services
docker compose --env-file .env.master down

# ✅ Démarrage services applicatifs avec phases
./scripts/start-with-progress.sh

# ✅ Démarrage monitoring indépendant
./scripts/start-monitoring.sh

# ❌ JAMAIS utiliser directement
# docker compose --env-file .env.master up -d
```

### Vérification Rapide
```bash
# 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.