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:

curl https://anchorage.certificator.4nkweb.com/health

Réponse:

{
  "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:

curl https://anchorage.certificator.4nkweb.com/health/detailed

Réponse (200 OK):

{
  "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:

curl https://anchorage.certificator.4nkweb.com/api/anchor/locked-utxos

Réponse:

{
  "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:

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:

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):

*/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:

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:

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:

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:

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:

# 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:

# 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

# 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

# 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é

# 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

# 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)