4NK_node/docs/MONITORING.md

# Monitoring et Observabilité 4NK

## Vue d'ensemble

Le système de monitoring 4NK utilise une stack complète d'observabilité basée sur Grafana, Loki et Prometheus pour surveiller l'ensemble des services du projet.

## Architecture

### Services de monitoring

- **Grafana Central** (`grafana-central.local:3000`)
  - Tableau de bord central pour visualisation des métriques et logs
  - Accès : http://grafana-central.local:3000 (admin/admin)

- **Loki** (`loki.local:3100`)
  - Système de collecte et d'indexation des logs
  - Stockage des logs de tous les services 4NK

- **Prometheus** (`prometheus.local:9091`)
  - Collecte et stockage des métriques de performance
  - Surveillance des services et alertes

- **Promtail** (`promtail.local`)
  - Agent de collecte des logs
  - Envoi des logs vers Loki

## Configuration

### Datasources Grafana

- **Loki-4NK** : Logs des services 4NK
- **Prometheus-4NK** : Métriques des services 4NK
- **Loki-Infra** : Logs d'infrastructure (si disponible)
- **Prometheus-Infra** : Métriques d'infrastructure (si disponible)

### Collecte de logs

Promtail collecte automatiquement les logs de :

#### Services 4NK
- `4nk-bitcoin` : Logs Bitcoin
- `4nk-blindbit-oracle` : Logs BlindBit Oracle
- `4nk-sdk-storage` : Logs SDK Storage
- `4nk-sdk-relay1/2/3` : Logs des relais SDK
- `4nk-sdk-signer` : Logs SDK Signer
- `4nk-ihm-client` : Logs IHM Client
- `4nk-coffre-front/back` : Logs LeCoffre

#### Logs système
- Logs Docker containers
- Logs système
- Logs Grafana Central

### Collecte de métriques

Prometheus surveille les métriques de :

- Bitcoin Core (port 38332)
- BlindBit Oracle (port 8000)
- SDK Storage (port 8080)
- SDK Relay 1/2/3 (port 8090)
- SDK Signer (port 9090)
- IHM Client (port 80)
- Conteneurs Docker
- Node Exporter (si installé)

## Dashboards

### Organisation par module

Le système de monitoring est organisé par module avec des dashboards spécifiques :

#### Dashboards 4NK Global
- **4NK Overview** : Vue d'ensemble des services
- **4NK System Health** : Santé générale du système

#### Dashboards par Module
- **Bitcoin Module** : Monitoring spécifique au nœud Bitcoin
- **SDK Storage Module** : Surveillance du service de stockage SDK
- **SDK Signer Module** : Surveillance du service de signature SDK
- **SDK Relay Modules** : Monitoring des relais SDK
- **IHM Client Module** : Surveillance de l'interface client
- **LeCoffre Frontend** : Monitoring de l'interface LeCoffre

#### Dashboards Infrastructure
- **System Overview** : Vue d'ensemble du système
- **Docker Containers** : Surveillance des conteneurs

#### Dashboards System
- **Node Metrics** : Métriques du serveur
- **Network Monitoring** : Surveillance réseau

> **Note** : Chaque module dispose de sa propre structure de dashboards dans `modules/[module]/grafana/dashboards/`. Voir `docs/MONITORING_MODULES.md` pour plus de détails.

## Utilisation

### Accès aux services

```bash
# Grafana (tableau de bord principal)
http://grafana-central.local:3000

# Prometheus (métriques brutes)
http://prometheus.local:9091

# Loki (logs bruts)
http://loki.local:3100
```

### Requêtes de logs dans Grafana

```logql
# Tous les logs Bitcoin
{job="4nk-bitcoin"}

# Logs d'erreur de tous les services
{job=~"4nk-.*"} |= "error"

# Logs des dernières 5 minutes
{job="4nk-bitcoin"} |= "error" | json
```

### Requêtes de métriques dans Grafana

```promql
# Services en ligne
up{job=~"4nk-.*"}

# Utilisation CPU
rate(process_cpu_seconds_total[5m])

# Utilisation mémoire
process_resident_memory_bytes
```

## Maintenance

### Redémarrage des services

```bash
# Redémarrage complet du monitoring
docker-compose restart loki.local prometheus.local promtail.local grafana-central.local

# Redémarrage d'un service spécifique
docker-compose restart loki.local
```

### Sauvegarde des données

```bash
# Sauvegarde des volumes de monitoring
docker run --rm -v 4nk_node_loki_data:/data -v $(pwd):/backup alpine tar czf /backup/loki-backup.tar.gz /data
docker run --rm -v 4nk_node_prometheus_data:/data -v $(pwd):/backup alpine tar czf /backup/prometheus-backup.tar.gz /data
docker run --rm -v 4nk_node_grafana_central_data:/data -v $(pwd):/backup alpine tar czf /backup/grafana-backup.tar.gz /data
```

### Restauration des données

```bash
# Restauration Loki
docker run --rm -v 4nk_node_loki_data:/data -v $(pwd):/backup alpine tar xzf /backup/loki-backup.tar.gz -C /

# Restauration Prometheus
docker run --rm -v 4nk_node_prometheus_data:/data -v $(pwd):/backup alpine tar xzf /backup/prometheus-backup.tar.gz -C /

# Restauration Grafana
docker run --rm -v 4nk_node_grafana_central_data:/data -v $(pwd):/backup alpine tar xzf /backup/grafana-backup.tar.gz -C /
```

## Dépannage

### Problèmes courants

1. **Promtail ne collecte pas les logs**
   - Vérifier les chemins de logs dans `promtail-config.yml`
   - Vérifier les permissions sur les fichiers de logs

2. **Prometheus ne collecte pas les métriques**
   - Vérifier la configuration dans `prometheus.yml`
   - Vérifier que les services exposent des métriques sur `/metrics`

3. **Grafana ne peut pas se connecter aux datasources**
   - Vérifier la configuration dans `datasources.yml`
   - Vérifier que Loki et Prometheus sont accessibles

### Logs de diagnostic

```bash
# Logs Promtail
docker logs promtail.local

# Logs Loki
docker logs loki.local

# Logs Prometheus
docker logs prometheus.local

# Logs Grafana
docker logs grafana-central.local
```

## Évolutions futures

- Ajout d'AlertManager pour les alertes
- Intégration avec des services externes (Slack, email)
- Dashboards personnalisés pour chaque service
- Métriques personnalisées pour les services 4NK
- Intégration avec des outils de tracing distribués