# Staging Observability Checklist

**Objectif**: Vérifier que l'observabilité est opérationnelle en staging avant production.

**Date de validation**: _______________  
**Validateur**: _______________

---

## 1. Prometheus Scrape OK

### Vérification `/metrics`

- [ ] **Endpoint `/metrics` accessible**
  ```bash
  curl http://staging-api:8080/metrics
  ```
  **Attendu**: Retourne métriques Prometheus au format texte

- [ ] **Métriques veza_* présentes**
  ```bash
  curl http://staging-api:8080/metrics | grep "^veza_"
  ```
  **Attendu**: Au minimum:
  - `veza_db_pool_open_connections`
  - `veza_circuit_breaker_state`
  - `veza_gin_http_requests_total`
  - `veza_gin_http_request_duration_seconds`

- [ ] **Format Prometheus valide**
  ```bash
  curl http://staging-api:8080/metrics | promtool check metrics
  ```
  **Attendu**: Pas d'erreurs de format

### Configuration Prometheus

- [ ] **Job `veza-backend-api` configuré dans `prometheus.yml`**
  ```yaml
  scrape_configs:
    - job_name: 'veza-backend-api'
      scrape_interval: 15s
      metrics_path: '/metrics'
      static_configs:
        - targets: ['staging-api:8080']
  ```

- [ ] **Prometheus scrape actif**
  ```bash
  curl http://prometheus:9090/api/v1/targets | jq '.data.activeTargets[] | select(.labels.job == "veza-backend-api")'
  ```
  **Attendu**: Target avec `health: "up"`

- [ ] **Métriques visibles dans Prometheus UI**
  - Ouvrir: `http://prometheus:9090/graph`
  - Tester query: `veza_db_pool_open_connections`
  - **Attendu**: Graphique avec données

---

## 2. Règles d'Alerte Chargées

### Fichier `alerts.yml`

- [ ] **Fichier présent dans Prometheus**
  ```bash
  ls -la /etc/prometheus/rules/veza-backend-api.yml
  # ou
  ls -la /path/to/prometheus/rules/veza-backend-api.yml
  ```
  **Attendu**: Fichier existe

- [ ] **Règles chargées dans Prometheus**
  ```bash
  curl http://prometheus:9090/api/v1/rules | jq '.data.groups[] | select(.name == "veza_backend_critical")'
  ```
  **Attendu**: Groupe `veza_backend_critical` présent avec règles

- [ ] **Règles valides (syntaxe)**
  ```bash
  promtool check rules /etc/prometheus/rules/veza-backend-api.yml
  ```
  **Attendu**: Pas d'erreurs de syntaxe

### Vérification dans Prometheus UI

- [ ] **Règles visibles dans UI**
  - Ouvrir: `http://prometheus:9090/alerts`
  - **Attendu**: Alertes `Veza*` listées (état: inactive/pending/firing)

- [ ] **Groupes de règles présents**:
  - [ ] `veza_backend_critical` (8 alertes)
  - [ ] `veza_backend_errors` (2 alertes)
  - [ ] `veza_backend_latency` (2 alertes)
  - [ ] `veza_backend_health` (2 alertes)

---

## 3. Alerte Vue + Runbook Suivi

### Sélection d'une Alerte

**Choisir une alerte à tester** (exemple: `VezaDBPoolHighUsage`):

- [ ] **Alerte visible dans Prometheus UI**
  - Ouvrir: `http://prometheus:9090/alerts`
  - Chercher: `VezaDBPoolHighUsage`
  - **Attendu**: Alerte listée (peut être inactive si seuil non atteint)

- [ ] **Runbook correspondant existe**
  ```bash
  ls -la docs/runbooks/db_down.md
  ```
  **Attendu**: Fichier existe

- [ ] **Runbook lisible et complet**
  - Vérifier sections: Signal, Hypothèses, Vérifications, Actions
  - **Attendu**: Toutes les sections présentes

### Test d'Alerte (Optionnel)

**Pour tester une alerte, déclencher le seuil**:

- [ ] **Déclencher alerte** (ex: saturer DB pool, ouvrir circuit breaker)
  - Utiliser scripts de drill: `scripts/ops_drills/`
  - Ou modifier seuils temporairement pour test

- [ ] **Vérifier alerte passe en "pending" puis "firing"**
  - Prometheus UI: `http://prometheus:9090/alerts`
  - **Attendu**: État change: `inactive` → `pending` → `firing`

- [ ] **Vérifier annotation `runbook` dans alerte**
  ```bash
  curl http://prometheus:9090/api/v1/alerts | jq '.data.alerts[] | select(.labels.alertname == "VezaDBPoolHighUsage") | .annotations.runbook'
  ```
  **Attendu**: `"docs/runbooks/db_down.md"`

- [ ] **Suivre runbook**
  - Ouvrir runbook indiqué dans annotation
  - Suivre étapes: Signal → Hypothèses → Vérifications → Actions
  - **Attendu**: Runbook actionnable et complet

### Intégration Alertmanager (Si configuré)

- [ ] **Alertmanager configuré**
  ```bash
  curl http://alertmanager:9093/api/v1/alerts
  ```
  **Attendu**: Alertmanager accessible

- [ ] **Routes configurées**
  - Vérifier `alertmanager.yml` pour routes vers Slack/PagerDuty/etc.
  - **Attendu**: Routes configurées selon sévérité

- [ ] **Test notification** (optionnel)
  - Déclencher alerte warning
  - **Attendu**: Notification reçue (Slack/PagerDuty/etc.)

---

## 4. Métriques Clés Vérifiées

### DB Pool Stats

- [ ] **Métrique `veza_db_pool_open_connections`**
  ```bash
  curl -s "http://prometheus:9090/api/v1/query?query=veza_db_pool_open_connections" | jq
  ```
  **Attendu**: Valeur numérique (ex: 5)

- [ ] **Métrique `veza_db_pool_in_use`**
  ```bash
  curl -s "http://prometheus:9090/api/v1/query?query=veza_db_pool_in_use" | jq
  ```
  **Attendu**: Valeur ≤ `open_connections`

- [ ] **Métrique `veza_db_pool_wait_count_total`**
  ```bash
  curl -s "http://prometheus:9090/api/v1/query?query=veza_db_pool_wait_count_total" | jq
  ```
  **Attendu**: Valeur cumulative (augmente si pool saturé)

### Circuit Breaker

- [ ] **Métrique `veza_circuit_breaker_state`**
  ```bash
  curl -s "http://prometheus:9090/api/v1/query?query=veza_circuit_breaker_state" | jq
  ```
  **Attendu**: Valeur 0 (CLOSED), 1 (HALF_OPEN), ou 2 (OPEN)

- [ ] **Métrique `veza_circuit_breaker_requests_total`**
  ```bash
  curl -s "http://prometheus:9090/api/v1/query?query=veza_circuit_breaker_requests_total" | jq
  ```
  **Attendu**: Compteurs par `result` (success, failure, rejected)

### HTTP Requests

- [ ] **Métrique `veza_gin_http_requests_total`**
  ```bash
  curl -s "http://prometheus:9090/api/v1/query?query=veza_gin_http_requests_total" | jq
  ```
  **Attendu**: Compteurs par `method`, `path`, `status`

- [ ] **Métrique `veza_gin_http_request_duration_seconds`**
  ```bash
  curl -s "http://prometheus:9090/api/v1/query?query=veza_gin_http_request_duration_seconds" | jq
  ```
  **Attendu**: Histogram avec buckets

---

## 5. Validation Endpoints Health

### `/health`

- [ ] **Endpoint accessible**
  ```bash
  curl http://staging-api:8080/health
  ```
  **Attendu**: `200 OK` avec `{"success": true, "data": {"status": "ok"}}`

### `/readyz`

- [ ] **Endpoint accessible**
  ```bash
  curl http://staging-api:8080/readyz
  ```
  **Attendu**: `200 OK` avec status `"ready"` ou `"degraded"`

- [ ] **Checks détaillés présents**
  ```bash
  curl -s http://staging-api:8080/readyz | jq '.data.checks'
  ```
  **Attendu**: Objet avec `database`, `redis`, `rabbitmq`

### `/live`

- [ ] **Endpoint accessible**
  ```bash
  curl http://staging-api:8080/live
  ```
  **Attendu**: `200 OK` avec `{"success": true, "data": {"status": "alive"}}`

---

## 6. Tests Opérationnels (Drills)

### DB Down Drill

- [ ] **Script exécuté**
  ```bash
  ./scripts/ops_drills/db_down_drill.sh http://staging-api:8080 http://prometheus:9090
  ```
  **Attendu**: Drill réussi (exit code 0)

- [ ] **Résultats vérifiés**:
  - [ ] `/readyz` retourne `503` quand DB down
  - [ ] Status = `"not_ready"`
  - [ ] Métriques DB toujours exposées
  - [ ] Alertes déclenchées (si seuils atteints)

### Circuit Breaker Drill

- [ ] **Script exécuté**
  ```bash
  ./scripts/ops_drills/circuit_breaker_drill.sh http://staging-api:8080 http://prometheus:9090
  ```
  **Attendu**: Drill réussi ou partiel (circuit breaker peut ne pas s'ouvrir si pas utilisé)

- [ ] **Résultats vérifiés**:
  - [ ] Circuit breaker détecté dans Prometheus
  - [ ] Métriques `veza_circuit_breaker_*` exposées
  - [ ] Alerte configurée (peut ne pas se déclencher si pas OPEN)

---

## 7. Documentation

### Runbooks

- [ ] **Runbooks présents**
  ```bash
  ls -la docs/runbooks/
  ```
  **Attendu**: Au minimum:
  - `db_down.md`
  - `circuit_breaker_open.md`
  - `upload_stuck.md`

- [ ] **Runbooks actionnables**
  - Vérifier que chaque runbook contient:
    - [ ] Section "Signal"
    - [ ] Section "Hypothèses"
    - [ ] Section "Vérifications" (commandes)
    - [ ] Section "Actions Correctives"
    - [ ] Section "Post-Mortem Notes"

### Documentation Observabilité

- [ ] **Rapport hardening présent**
  ```bash
  ls -la docs/PROD_WEEK1_HARDENING_REPORT.md
  ```
  **Attendu**: Fichier existe

- [ ] **Documentation Prometheus présente**
  ```bash
  ls -la ops/prometheus/README.md
  ```
  **Attendu**: Fichier existe

---

## Résumé de Validation

### ✅ Checklist Complétée

- [ ] Prometheus scrape OK
- [ ] Règles d'alerte chargées
- [ ] Alerte vue + runbook suivi
- [ ] Métriques clés vérifiées
- [ ] Endpoints health validés
- [ ] Tests opérationnels (drills) exécutés
- [ ] Documentation complète

### Notes

**Problèmes rencontrés**:
- 

**Actions correctives**:
- 

**Recommandations**:
- 

---

## Signature

**Validé par**: _______________  
**Date**: _______________  
**Environnement**: Staging  
**Version API**: _______________

---

## Références

- Alertes Prometheus: `ops/prometheus/alerts.yml`
- Runbooks: `docs/runbooks/`
- Scripts drills: `scripts/ops_drills/`
- Rapport hardening: `docs/PROD_WEEK1_HARDENING_REPORT.md`
