veza/veza-backend-api/scripts/ops_drills/README.md

Operational Drills - veza-backend-api

Scripts de validation opérationnelle pour prouver que l'observabilité fonctionne en conditions réelles.

Scripts Disponibles

1. db_down_drill.sh - DB Down Drill

Objectif: Vérifier que /readyz retourne 503 + status not_ready quand DB est down.

Usage:

./scripts/ops_drills/db_down_drill.sh [API_URL] [PROMETHEUS_URL]

Exemple:

./scripts/ops_drills/db_down_drill.sh http://localhost:8080 http://localhost:9090

Déroulé:

1. État initial - Vérifie /readyz et métriques DB
2. Simulation DB down - 3 options (arrêter PostgreSQL, DSN invalide, firewall)
3. Vérification /readyz - Doit retourner 503 + not_ready
4. Vérification métriques Prometheus - DB pool stats
5. Vérification alertes - VezaDBPoolExhausted, VezaReadinessFailed
6. Restauration - Option pour restaurer DB

Critères de succès:

• ✅ /readyz retourne 503 Service Unavailable
• ✅ Status = "not_ready"
• ✅ DB check status = "error"
• ✅ Métriques Prometheus exposées
• ✅ Alertes déclenchées (si seuils atteints)

2. circuit_breaker_drill.sh - Circuit Breaker Drill

Objectif: Simuler dépendance externe en 5xx/timeout pour ouvrir circuit breaker.

Usage:

./scripts/ops_drills/circuit_breaker_drill.sh [API_URL] [PROMETHEUS_URL] [SERVICE_URL]

Exemple:

./scripts/ops_drills/circuit_breaker_drill.sh http://localhost:8080 http://localhost:9090 http://localhost:8082

Déroulé:

1. État initial - Vérifie état circuit breaker (CLOSED)
2. Simulation dépendance externe - 4 options (mock server, arrêter service, firewall, service de test)
3. Génération requêtes - Pour déclencher échecs consécutifs
4. Vérification état - Circuit breaker doit passer en OPEN (après 5 échecs)
5. Vérification alertes - VezaCircuitBreakerOpen
6. Vérification comportement API - Requêtes rejetées quand OPEN
7. Restauration - Attendre timeout pour HALF_OPEN

Critères de succès:

• ✅ Circuit breaker détecté dans Prometheus
• ✅ État = 2 (OPEN) après 5 échecs consécutifs
• ✅ Métriques veza_circuit_breaker_* exposées
• ✅ Alerte VezaCircuitBreakerOpen déclenchée (après 5 min)

Prérequis

Outils Requis

• curl - Pour requêtes HTTP
• jq - Pour parsing JSON
• bash - Shell (version 4+)
• Accès à Prometheus (pour vérifier métriques/alertes)

Installation jq (si manquant)

# Ubuntu/Debian
sudo apt-get install jq

# macOS
brew install jq

# CentOS/RHEL
sudo yum install jq

Configuration

1. Prometheus doit être configuré et accessible
2. Alertes doivent être chargées (ops/prometheus/alerts.yml)
3. API doit être démarrée et accessible
4. Permissions - Certaines options nécessitent sudo (arrêter PostgreSQL, firewall)

Exécution en Staging

Avant le Drill

1. Notifier l'équipe - Les drills peuvent affecter le service
2. Vérifier backups - S'assurer que DB peut être restaurée
3. Planifier fenêtre - Prévoir 15-30 minutes par drill
4. Documenter état initial - Capturer métriques avant drill

Pendant le Drill

1. Suivre le script - Le script guide étape par étape
2. Vérifier logs - Surveiller logs application en parallèle
3. Vérifier Prometheus UI - Ouvrir http://prometheus:9090 pour voir métriques en temps réel
4. Documenter observations - Noter tout comportement inattendu

Après le Drill

1. Vérifier restauration - S'assurer que tout est revenu à la normale
2. Analyser logs - Vérifier logs pour patterns intéressants
3. Documenter résultats - Noter dans le log du drill (/tmp/*_drill_*.log)
4. Post-mortem - Si échecs, documenter causes et actions correctives

Logs

Chaque drill génère un log timestampé dans /tmp/:

• db_down_drill_YYYYMMDD_HHMMSS.log
• circuit_breaker_drill_YYYYMMDD_HHMMSS.log

Les logs contiennent:

• Toutes les étapes exécutées
• Résultats des vérifications
• Métriques Prometheus capturées
• Résumé final (succès/échec)

Dépannage

Drill DB Down échoue

Problème: /readyz ne retourne pas 503

• Vérifier que DB est vraiment down: psql -h localhost -U veza -d veza_db -c "SELECT 1;"
• Vérifier logs application pour erreurs DB
• Vérifier que health handler vérifie bien la DB

Problème: Métriques non trouvées

• Vérifier que Prometheus scrape /metrics: curl http://localhost:8080/metrics | grep veza_db_pool
• Vérifier configuration Prometheus (prometheus.yml)

Drill Circuit Breaker échoue

Problème: Circuit breaker reste CLOSED

• Vérifier que le circuit breaker est utilisé par l'endpoint testé
• Vérifier que les requêtes échouent vraiment (5xx/timeout)
• Vérifier configuration circuit breaker (seuil = 5 échecs consécutifs)

Problème: Métriques non trouvées

• Vérifier que le circuit breaker est initialisé
• Vérifier que les métriques sont mises à jour dans CircuitBreakerHTTPClient.Do()

Intégration CI/CD

Ces scripts peuvent être intégrés dans un pipeline CI/CD pour validation automatique:

# .github/workflows/ops-drills.yml
name: Operational Drills
on:
  schedule:
    - cron: '0 2 * * 0'  # Dimanche 2h du matin
  workflow_dispatch:

jobs:
  db-down-drill:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run DB Down Drill
        run: ./scripts/ops_drills/db_down_drill.sh

Note: En CI/CD, utiliser des mocks/services de test plutôt que couper de vrais services.

Références

• Runbooks: docs/runbooks/
• Alertes Prometheus: ops/prometheus/alerts.yml
• Documentation observabilité: docs/PROD_WEEK1_HARDENING_REPORT.md