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**:
```bash
./scripts/ops_drills/db_down_drill.sh [API_URL] [PROMETHEUS_URL]
```

**Exemple**:
```bash
./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**:
```bash
./scripts/ops_drills/circuit_breaker_drill.sh [API_URL] [PROMETHEUS_URL] [SERVICE_URL]
```

**Exemple**:
```bash
./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)

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

```yaml
# .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`