lecoffre_node/docs/MONITORING.md

# 📊 Monitoring LeCoffre Node

## Vue d'ensemble

Le système de monitoring LeCoffre Node utilise **Grafana**, **Loki** et **Promtail** pour centraliser, analyser et visualiser les logs de tous les services.

## 🏗️ Architecture du Monitoring

```
Services → Logs Centralisés → Promtail → Loki → Grafana
    ↓           ↓              ↓         ↓        ↓
  Docker    logs/          Collecte   Stockage  Dashboard
```

### Composants

| Composant | Port | Description |
|-----------|------|-------------|
| **Grafana** | 3000 | Interface de visualisation et dashboards |
| **Loki** | 3100 | Base de données de logs |
| **Promtail** | - | Agent de collecte des logs |
| **Nginx** | 80 | Proxy pour accès externe |

## 🚀 Déploiement

### Démarrage Rapide

```bash
# 1. Synchroniser la configuration
./scripts/sync-monitoring-config.sh

# 2. Démarrer le monitoring
./scripts/deploy-grafana.sh start

# 3. Tester la connectivité
./scripts/test-monitoring.sh
```

### Commandes de Gestion

```bash
# Démarrer
./scripts/deploy-grafana.sh start

# Arrêter
./scripts/deploy-grafana.sh stop

# Redémarrer
./scripts/deploy-grafana.sh restart

# Vérifier le statut
./scripts/deploy-grafana.sh status

# Voir les logs
./scripts/deploy-grafana.sh logs grafana
./scripts/deploy-grafana.sh logs loki
./scripts/deploy-grafana.sh logs promtail
```

## 🔗 Accès

### URLs Principales

| Service | URL | Description |
|---------|-----|-------------|
| **Grafana** | [https://dev4.4nkweb.com/grafana/](https://dev4.4nkweb.com/grafana/) | Interface principale |
| **Loki API** | [https://dev4.4nkweb.com/loki/](https://dev4.4nkweb.com/loki/) | API de logs |
| **Grafana Local** | [http://localhost:3000](http://localhost:3000) | Accès local |

### Identifiants

- **Utilisateur** : `admin`
- **Mot de passe** : `admin123`

## 📊 Dashboards Disponibles

### 1. Vue d'ensemble LeCoffre
- **ID** : `lecoffre-overview`
- **Description** : Dashboard principal avec vue d'ensemble de tous les services
- **Métriques** : Erreurs par service, volume de logs, logs d'erreur en temps réel

### 2. Bitcoin & Miner
- **ID** : `bitcoin-miner`
- **Description** : Monitoring spécialisé pour Bitcoin et le mineur
- **Métriques** : Nouveaux blocs, blocs minés, erreurs blockchain

### 3. Services Applications
- **ID** : `services-overview`
- **Description** : Monitoring des services applicatifs
- **Métriques** : Volume de logs par service, erreurs applications

## 📝 Collecte des Logs

### Structure des Logs

```
logs/
├── bitcoin/          # Logs Bitcoin Signet
├── blindbit/         # Logs Oracle Blindbit
├── sdk_relay/        # Logs Relay WebSocket
├── sdk_signer/       # Logs Service de signature
├── sdk_storage/      # Logs Stockage temporaire
├── lecoffre-back/    # Logs Backend API
├── lecoffre-front/   # Logs Frontend
├── ihm_client/       # Logs Interface de gestion
├── tor/              # Logs Proxy Tor
├── miner/            # Logs Mineur Bitcoin
└── nginx/            # Logs Proxy Nginx
```

### Scripts de Gestion

```bash
# Collecter les logs de tous les services
./scripts/collect-logs.sh

# Collecter les logs d'un service spécifique
./scripts/collect-logs.sh bitcoin-signet
./scripts/collect-logs.sh sdk_relay

# Configurer la centralisation des logs
./scripts/setup-logs.sh
```

## 🔧 Configuration

### Fichiers de Configuration

| Fichier | Description |
|---------|-------------|
| `conf/grafana/grafana.ini` | Configuration Grafana |
| `conf/grafana/provisioning/datasources/loki.yml` | Source de données Loki |
| `conf/grafana/provisioning/dashboards/dashboards.yml` | Configuration des dashboards |
| `conf/promtail/promtail.yml` | Configuration Promtail |
| `conf/nginx/grafana.conf` | Configuration Nginx pour Grafana |
| `conf/monitoring.conf` | Configuration centralisée |

### Variables d'Environnement

```bash
# Mot de passe admin Grafana
GRAFANA_ADMIN_PASSWORD=admin123

# Ports des services
GRAFANA_PORT=3000
LOKI_PORT=3100
```

## 🔍 Requêtes Logs Utiles

### Recherche d'Erreurs

```logql
# Erreurs de tous les services
{job=~".*"} |= "error"

# Erreurs Bitcoin spécifiques
{job="bitcoin"} |= "error"

# Erreurs des services applicatifs
{job=~"lecoffre-back|lecoffre-front|ihm_client"} |= "error"
```

### Métriques de Performance

```logql
# Volume de logs par service
sum by (service) (count_over_time({job=~".*"} [5m]))

# Erreurs par minute
sum by (service) (rate({job=~".*"} |= "error" [1m]))
```

### Monitoring Bitcoin

```logql
# Nouveaux blocs
{job="bitcoin"} |= "block"

# Transactions
{job="bitcoin"} |= "tx"

# Blocs minés
{job="miner"} |= "mined"
```

## 🚨 Alertes

### Configuration des Alertes

Les alertes sont configurées dans Grafana pour :

- **Erreurs critiques** : > 10 erreurs en 5 minutes
- **Services arrêtés** : Service non accessible
- **Problèmes Bitcoin** : Blocs non minés
- **Problèmes de connectivité** : Connexions WebSocket échouées

### Canaux de Notification

- **Email** : Configuration dans Grafana
- **Webhook** : Intégration avec systèmes externes
- **Slack** : Notifications en temps réel

## 🛠️ Maintenance

### Rotation des Logs

```bash
# Configuration automatique avec logrotate
conf/logrotate/*.conf

# Rotation quotidienne, rétention 7 jours
# Compression automatique
```

### Sauvegarde

```bash
# Sauvegarder les dashboards Grafana
docker exec grafana grafana-cli admin export-dashboard > dashboards-backup.json

# Sauvegarder la configuration
tar -czf monitoring-config-backup.tar.gz conf/grafana/ conf/promtail/
```

### Mise à Jour

```bash
# Mise à jour des images Docker
docker compose pull grafana loki promtail

# Redémarrage avec nouvelles images
docker compose up -d grafana loki promtail
```

## 🔐 Sécurité

### Authentification

- **Utilisateur unique** : `admin`
- **Mot de passe fort** : Configuré via variable d'environnement
- **Accès anonyme** : Désactivé
- **HTTPS** : Forcé via Nginx

### Réseau

- **Isolation Docker** : Services dans le réseau `btcnet`
- **Ports exposés** : Uniquement en localhost
- **Proxy Nginx** : Accès externe sécurisé

### Données Sensibles

- **Aucun secret** dans les logs
- **Rotation automatique** des logs
- **Chiffrement** des données au repos (optionnel)

## 📈 Métriques et KPIs

### Disponibilité des Services

- **Uptime** : Pourcentage de temps de fonctionnement
- **Healthchecks** : Statut des services
- **Restarts** : Nombre de redémarrages

### Performance

- **Temps de réponse** : Latence des API
- **Throughput** : Requêtes par seconde
- **Erreurs** : Taux d'erreur par service

### Bitcoin

- **Blocs minés** : Nombre de blocs par heure
- **Transactions** : Volume de transactions
- **Fees** : Frais de transaction moyens

## 🆘 Dépannage

### Problèmes Courants

1. **Grafana non accessible**
   ```bash
   # Vérifier le statut
   docker compose ps grafana

   # Vérifier les logs
   docker compose logs grafana
   ```

2. **Logs non collectés**
   ```bash
   # Vérifier Promtail
   docker compose logs promtail

   # Vérifier Loki
   docker compose logs loki
   ```

3. **Dashboards vides**
   ```bash
   # Vérifier la source de données
   # Aller dans Configuration > Data Sources > Loki
   ```

### Commandes de Diagnostic

```bash
# Test de connectivité complet
./scripts/test-monitoring.sh

# Vérification des services
./scripts/deploy-grafana.sh status

# Logs en temps réel
./scripts/deploy-grafana.sh logs grafana
```

## 📚 Documentation Associée

- **[`../IA_agents/flux.md`](../IA_agents/flux.md)** - Architecture générale
- **[`ARCHITECTURE.md`](ARCHITECTURE.md)** - Architecture détaillée
- **[`CONFIGURATION_SERVICES.md`](CONFIGURATION_SERVICES.md)** - Configuration des services

---

**💡 Conseil** : Commencez par le dashboard "Vue d'ensemble LeCoffre" pour avoir une vision globale du système !