anchorage_layer_simple/api-anchorage/README-MONITORING.md

# Monitoring et Maintenance de l'API d'Ancrage

**Auteur:** Équipe 4NK
**Date:** 2026-01-28

## Vue d'ensemble

Ce document décrit les outils de monitoring et de maintenance pour l'API d'ancrage Bitcoin Signet.

## Endpoints de Monitoring

### GET `/health`

Vérifie l'état de base de l'API et de la connexion Bitcoin.

**Exemple:**
```bash
curl https://anchorage.certificator.4nkweb.com/health
```

**Réponse:**
```json
{
  "ok": true,
  "service": "anchor-api",
  "bitcoin": {
    "connected": true,
    "blocks": 10833
  },
  "timestamp": "2026-01-28T11:45:00.000Z"
}
```

### GET `/health/detailed`

Vérifie l'état détaillé de l'API, incluant l'état du mutex, des UTXOs verrouillés et de la connexion Bitcoin.

**Exemple:**
```bash
curl https://anchorage.certificator.4nkweb.com/health/detailed
```

**Réponse (200 OK):**
```json
{
  "ok": true,
  "service": "anchor-api",
  "mutex": {
    "locked": false,
    "waiting": 0,
    "timeout": 180000
  },
  "utxos": {
    "locked": 0,
    "locked_since": null,
    "stale_locks": 0,
    "stale_locks_details": []
  },
  "bitcoin": {
    "connected": true,
    "blocks": 10833,
    "chain": "signet",
    "rpc_timeout": 60000
  },
  "timestamp": "2026-01-28T11:45:00.000Z"
}
```

**Codes de statut:**
- `200` - Tout fonctionne correctement
- `200` - Warning si 5-10 UTXOs verrouillés (mais < 10 min)
- `503` - Service Unavailable si UTXOs verrouillés depuis > 10 min ou > 10 UTXOs verrouillés
- `503` - Service Unavailable si Bitcoin non connecté

### GET `/api/anchor/locked-utxos`

Liste tous les UTXOs actuellement verrouillés.

**Exemple:**
```bash
curl https://anchorage.certificator.4nkweb.com/api/anchor/locked-utxos
```

**Réponse:**
```json
{
  "locked": [
    {
      "txid": "abc123...",
      "vout": 0
    }
  ],
  "count": 1
}
```

## Scripts de Maintenance

### 1. `unlock-utxos.mjs`

Déverrouille tous les UTXOs verrouillés dans la base de données.

**Utilisation:**
```bash
cd /home/ncantu/Bureau/code/bitcoin/api-anchorage
node unlock-utxos.mjs
```

**Sortie:**
```
✅ UTXOs déverrouillés: 22
```

### 2. `cleanup-stale-locks.mjs`

Déverrouille automatiquement les UTXOs verrouillés depuis plus de 10 minutes.

**Utilisation:**
```bash
cd /home/ncantu/Bureau/code/bitcoin/api-anchorage
node cleanup-stale-locks.mjs
```

**Sortie:**
```
✅ UTXOs déverrouillés: 5
```

**Cron job recommandé (toutes les 5 minutes):**
```bash
*/5 * * * * cd /home/ncantu/Bureau/code/bitcoin/api-anchorage && node cleanup-stale-locks.mjs >> /var/log/anchorage-cleanup.log 2>&1
```

### 3. `diagnose.mjs`

Affiche un diagnostic complet de l'état des UTXOs verrouillés.

**Utilisation:**
```bash
cd /home/ncantu/Bureau/code/bitcoin/api-anchorage
node diagnose.mjs
```

**Sortie:**
```
📊 UTXOs verrouillés: 3

Détails des UTXOs verrouillés:
🔒 [1] abc123... vout:0 amount:0.000025 locked_for:5.2min
⚠️  STALE [2] def456... vout:1 amount:0.000025 locked_for:15.5min

⚠️  UTXOs verrouillés depuis plus de 10 minutes: 1
   Action recommandée: Exécuter cleanup-stale-locks.mjs

📈 Statistiques UTXOs:
   Total: 150
   Verrouillés: 3
   Dépensés: 50
   Disponibles: 97
```

## Monitoring des Logs

### Timeouts de mutex

**Vérification:**
```bash
sudo journalctl -u anchorage-api --since "1 hour ago" | grep -c "Mutex acquisition timeout"
```

**Alerte recommandée:** Si > 1 timeout par heure

### Erreurs RPC Bitcoin

**Vérification:**
```bash
sudo journalctl -u anchorage-api --since "1 hour ago" | grep -c "ESOCKETTIMEDOUT\|ETIMEDOUT"
```

**Alerte recommandée:** Si > 1 erreur RPC par heure

### Opérations longues

**Vérification:**
```bash
sudo journalctl -u anchorage-api --since "1 hour ago" | grep "took too long"
```

**Alerte recommandée:** Si > 1 opération > 30s par heure

## Alertes Recommandées

### Niveau Warning

- **UTXOs verrouillés > 5:** Plus de 5 UTXOs verrouillés
- **Timeout de mutex:** 1+ timeout par heure
- **Erreur RPC:** 1+ erreur RPC par heure

### Niveau Critical

- **UTXOs verrouillés > 10:** Plus de 10 UTXOs verrouillés
- **UTXOs stale:** UTXOs verrouillés depuis > 10 minutes
- **Timeout de mutex:** 5+ timeouts par heure
- **Erreur RPC:** 5+ erreurs RPC par heure

## Configuration Cron

### Nettoyage automatique (recommandé)

Créer un fichier `/etc/cron.d/anchorage-cleanup`:

```bash
# Nettoyage automatique des UTXOs verrouillés depuis plus de 10 minutes
# Toutes les 5 minutes
*/5 * * * * ncantu cd /home/ncantu/Bureau/code/bitcoin/api-anchorage && /usr/bin/node cleanup-stale-locks.mjs >> /var/log/anchorage-cleanup.log 2>&1
```

### Diagnostic périodique (optionnel)

Créer un fichier `/etc/cron.d/anchorage-diagnose`:

```bash
# Diagnostic de l'état des UTXOs
# Toutes les heures
0 * * * * ncantu cd /home/ncantu/Bureau/code/bitcoin/api-anchorage && /usr/bin/node diagnose.mjs >> /var/log/anchorage-diagnose.log 2>&1
```

## Procédure de Dépannage

### 1. Vérifier l'état actuel

```bash
# Health check détaillé
curl https://anchorage.certificator.4nkweb.com/health/detailed | jq .

# UTXOs verrouillés
curl https://anchorage.certificator.4nkweb.com/api/anchor/locked-utxos | jq '.count'
```

### 2. Si UTXOs verrouillés

```bash
# Diagnostic
cd /home/ncantu/Bureau/code/bitcoin/api-anchorage
node diagnose.mjs

# Déverrouiller manuellement
node unlock-utxos.mjs

# Ou nettoyer seulement les stale locks
node cleanup-stale-locks.mjs
```

### 3. Si mutex bloqué

```bash
# Redémarrer le service
sudo systemctl restart anchorage-api

# Vérifier les logs
sudo journalctl -u anchorage-api -n 50 --no-pager
```

### 4. Si erreurs RPC Bitcoin

```bash
# Vérifier la connexion Bitcoin
curl -s --user bitcoin:bitcoin --data-binary '{"jsonrpc":"1.0","id":"test","method":"getblockchaininfo","params":[]}' -H 'content-type: text/plain;' http://localhost:38332/

# Vérifier les logs
sudo journalctl -u anchorage-api --since "10 minutes ago" | grep "ESOCKETTIMEDOUT"
```

## Pages Affectées

- `api-anchorage/src/routes/health.js`: Endpoint `/health/detailed`
- `api-anchorage/src/bitcoin-rpc.js`: Monitoring de durée, timeout de sécurité, retry avec backoff
- `api-anchorage/src/server.js`: Déverrouillage automatique au démarrage
- `api-anchorage/unlock-utxos.mjs`: Script de déverrouillage (existant)
- `api-anchorage/cleanup-stale-locks.mjs`: Script de nettoyage automatique (nouveau)
- `api-anchorage/diagnose.mjs`: Script de diagnostic (nouveau)
- `api-anchorage/README-MONITORING.md`: Documentation (nouveau)