veza/veza-backend-api/docs/BACKEND_STATUS_MONITORING.md

Backend Status & Monitoring - Documentation Complète

Version: 1.0
Date: 2025-12-05
Priorité: P1 - Monitoring Production

---

📋 Vue d'ensemble

Ce document décrit l'implémentation complète du système de monitoring et de health checks pour le backend Go de Veza. Cette implémentation inclut :

• ✅ Route /health simplifiée (stateless)
• ✅ Route /status complète avec vérifications de tous les services
• ✅ Intégration Sentry pour le tracking d'erreurs
• ✅ Logging structuré avec zap
• ✅ Métriques Prometheus pour les health checks
• ✅ Tests d'intégration

---

🔍 Endpoints de Health Check

1. /health - Health Check Simple

Route: GET /health ou GET /api/v1/health

Description: Endpoint stateless qui retourne toujours {status: "ok"}. Aucune vérification de dépendances externes.

Réponse:

{
  "status": "ok"
}

Status Code: 200 OK

Usage:

• Kubernetes liveness probe
• Load balancer health check
• Monitoring basique

Exemple:

curl http://localhost:8080/api/v1/health

---

2. /status - Status Complet

Route: GET /api/v1/status

Description: Endpoint complet qui vérifie l'état de tous les services dépendants (DB, Redis, Chat Server, Stream Server).

Réponse:

{
  "status": "ok",
  "uptime_seconds": 12345,
  "services": {
    "database": {
      "status": "ok",
      "latency_ms": 3.2
    },
    "redis": {
      "status": "ok",
      "latency_ms": 1.5
    },
    "chat_server": {
      "status": "ok",
      "latency_ms": 4.8
    },
    "stream_server": {
      "status": "ok",
      "latency_ms": 6.1
    }
  },
  "version": "v1.0.0",
  "git_commit": "abc123",
  "build_time": "2025-12-05T14:33:00Z",
  "environment": "production"
}

Status Codes:

• 200 OK: Tous les services sont opérationnels
• 503 Service Unavailable: Au moins un service est en erreur (status: "degraded")

Status des Services:

• ok: Service opérationnel avec latence normale
• slow: Service opérationnel mais latence élevée
• error: Service inaccessible ou en erreur

Seuils de Latence:

• Database: 100ms (au-delà = "slow")
• Redis: 50ms (au-delà = "slow")
• Chat Server: 100ms (au-delà = "slow")
• Stream Server: 100ms (au-delà = "slow")

Exemple:

curl http://localhost:8080/api/v1/status

Exemple avec service dégradé:

{
  "status": "degraded",
  "uptime_seconds": 12345,
  "services": {
    "database": {
      "status": "ok",
      "latency_ms": 3.2
    },
    "redis": {
      "status": "error",
      "latency_ms": 0,
      "message": "connection refused"
    },
    "chat_server": {
      "status": "ok",
      "latency_ms": 4.8
    },
    "stream_server": {
      "status": "ok",
      "latency_ms": 6.1
    }
  },
  "version": "v1.0.0",
  "git_commit": "abc123",
  "build_time": "2025-12-05T14:33:00Z",
  "environment": "production"
}

---

🔧 Configuration

Variables d'Environnement

Health Check

Aucune variable requise pour /health (stateless).

Status Endpoint

Les variables suivantes sont utilisées pour /status:

Variable	Description	Default	Requis
CHAT_SERVER_URL	URL du serveur de chat	http://localhost:8081	Non
STREAM_SERVER_URL	URL du serveur de streaming	http://localhost:8082	Non
APP_VERSION	Version de l'application	v1.0.0	Non
GIT_COMMIT	Commit Git	unknown	Non
BUILD_TIME	Date de build	(vide)	Non

Note: Si CHAT_SERVER_URL ou STREAM_SERVER_URL ne sont pas configurés, ces services ne seront pas vérifiés dans /status.

Sentry Configuration

Variable	Description	Default	Requis
SENTRY_DSN	DSN Sentry pour error tracking	(vide)	Non
SENTRY_ENV	Environnement Sentry	APP_ENV	Non
SENTRY_SAMPLE_RATE_ERRORS	Sample rate pour les erreurs (0.0-1.0)	1.0	Non
SENTRY_SAMPLE_RATE_TRANSACTIONS	Sample rate pour les transactions (0.0-1.0)	0.1	Non

Exemple:

export SENTRY_DSN="https://xxx@xxx.ingest.sentry.io/xxx"
export SENTRY_ENV="production"
export SENTRY_SAMPLE_RATE_ERRORS=1.0
export SENTRY_SAMPLE_RATE_TRANSACTIONS=0.1

---

📊 Métriques Prometheus

Health Check Metrics

Les métriques suivantes sont exposées pour les health checks:

veza_health_check_duration_ms

Histogramme de la durée des health checks par service.

Labels:

• service: database, redis, chat_server, stream_server

Buckets: 1, 5, 10, 25, 50, 100, 250, 500, 1000 (ms)

Exemple:

veza_health_check_duration_ms_bucket{service="database",le="10"} 45
veza_health_check_duration_ms_bucket{service="database",le="50"} 98
veza_health_check_duration_ms_sum{service="database"} 1234.5
veza_health_check_duration_ms_count{service="database"} 100

veza_health_check_status

Gauge du status de chaque service.

Labels:

• service: database, redis, chat_server, stream_server

Valeurs:

• 1.0: Service OK
• 0.5: Service lent (slow)
• 0.0: Service en erreur

Exemple:

veza_health_check_status{service="database"} 1.0
veza_health_check_status{service="redis"} 0.5
veza_health_check_status{service="chat_server"} 0.0

Accès aux Métriques

Endpoint: GET /api/v1/metrics

Exemple:

curl http://localhost:8080/api/v1/metrics | grep health_check

---

🐛 Intégration Sentry

Initialisation

Sentry est initialisé automatiquement dans cmd/api/main.go si SENTRY_DSN est configuré.

Middleware

Le middleware SentryRecover capture automatiquement:

• Les panics (avec stack trace)
• Les erreurs HTTP 5xx
• Les erreurs du contexte Gin

Contexte Capturé

Pour chaque erreur, Sentry capture:

• Méthode HTTP
• Path de la requête
• Query parameters
• IP du client
• Request ID (si présent)
• User ID (si authentifié)

Exemple d'Erreur dans Sentry

{
  "message": "Panic: runtime error: invalid memory address",
  "level": "error",
  "tags": {
    "component": "gin",
    "request_id": "req-12345"
  },
  "contexts": {
    "request": {
      "method": "POST",
      "path": "/api/v1/tracks",
      "query": "",
      "ip": "192.168.1.1"
    }
  },
  "user": {
    "id": "user-123",
    "username": "user-123"
  }
}

---

📝 Logging Structuré

Format

Tous les logs utilisent le format JSON structuré avec zap.

Champs Standards

Chaque requête HTTP logge:

• method: Méthode HTTP (GET, POST, etc.)
• path: Chemin de la requête
• query: Query parameters
• ip: IP du client
• user_agent: User agent
• latency: Durée de la requête
• status: Status code HTTP
• body_size: Taille de la réponse
• request_id: ID unique de la requête (si présent)
• user_id: ID de l'utilisateur (si authentifié)
• trace_id: ID de trace (si présent)
• span_id: ID de span (si présent)

Niveaux de Log

• INFO: Requêtes réussies (2xx, 3xx)
• WARN: Erreurs client (4xx)
• ERROR: Erreurs serveur (5xx)

Exemple de Log

{
  "level": "info",
  "ts": 1701878400.123,
  "msg": "Request completed",
  "method": "GET",
  "path": "/api/v1/status",
  "query": "",
  "ip": "192.168.1.1",
  "user_agent": "curl/7.68.0",
  "latency": "0.012345s",
  "status": 200,
  "body_size": 456,
  "request_id": "req-12345"
}

---

🧪 Tests

Tests Unitaires

Les tests sont dans tests/integration/api_health_test.go:

• TestAPIHealth: Test de /health
• TestAPIHealthV1: Test de /api/v1/health
• TestAPIStatus: Test de /status avec services réels
• TestAPIStatusDegraded: Test de /status avec service dégradé

Exécution des Tests

cd veza-backend-api
go test ./tests/integration -v -run TestAPIHealth
go test ./tests/integration -v -run TestAPIStatus

Tests d'Intégration HTTP

Pour tester avec un serveur réel:

# Démarrer le serveur
make run

# Dans un autre terminal
curl http://localhost:8080/api/v1/health
curl http://localhost:8080/api/v1/status

---

📈 Dashboard Grafana Recommandé

Panels Suggérés

1. Health Check Status

   • Query: veza_health_check_status
   • Type: Gauge
   • Alerte: Si valeur < 1.0

2. Health Check Latency

   • Query: rate(veza_health_check_duration_ms_sum[5m]) / rate(veza_health_check_duration_ms_count[5m])
   • Type: Graph
   • Alerte: Si latence > 100ms

3. Service Availability

   • Query: avg_over_time(veza_health_check_status[5m])
   • Type: Stat
   • Alerte: Si disponibilité < 0.95

4. Error Rate

   • Query: rate(veza_errors_total[5m])
   • Type: Graph
   • Alerte: Si taux d'erreur > 1%

Exemple de Dashboard JSON

{
  "dashboard": {
    "title": "Veza Backend Health",
    "panels": [
      {
        "title": "Health Check Status",
        "targets": [
          {
            "expr": "veza_health_check_status"
          }
        ]
      },
      {
        "title": "Health Check Latency",
        "targets": [
          {
            "expr": "rate(veza_health_check_duration_ms_sum[5m]) / rate(veza_health_check_duration_ms_count[5m])"
          }
        ]
      }
    ]
  }
}

---

🚀 Procédure de Test Locale

1. Démarrer les Services

# Démarrer PostgreSQL
docker-compose up -d postgres

# Démarrer Redis
docker-compose up -d redis

# Démarrer le backend
cd veza-backend-api
go run cmd/api/main.go

2. Tester /health

curl http://localhost:8080/api/v1/health
# Réponse: {"status":"ok"}

3. Tester /status

curl http://localhost:8080/api/v1/status | jq

4. Vérifier les Métriques

curl http://localhost:8080/api/v1/metrics | grep health_check

5. Tester avec Service Dégradé

# Arrêter Redis
docker-compose stop redis

# Vérifier le status
curl http://localhost:8080/api/v1/status | jq
# Le status devrait être "degraded" et redis en "error"

---

🔍 Dépannage

Problème: /status retourne toujours "degraded"

Causes possibles:

1. Un service est inaccessible (DB, Redis, Chat Server, Stream Server)
2. Latence élevée (> seuil)

Solution:

1. Vérifier les logs: docker-compose logs backend
2. Vérifier la connectivité: curl http://localhost:8081/health (chat server)
3. Vérifier les métriques: curl http://localhost:8080/api/v1/metrics | grep health_check

Problème: Sentry ne capture pas les erreurs

Causes possibles:

1. SENTRY_DSN non configuré
2. Sample rate trop bas

Solution:

1. Vérifier SENTRY_DSN dans les variables d'environnement
2. Augmenter SENTRY_SAMPLE_RATE_ERRORS à 1.0 pour les tests

Problème: Métriques Prometheus non visibles

Causes possibles:

1. Endpoint /metrics non accessible
2. Métriques non enregistrées

Solution:

1. Vérifier l'endpoint: curl http://localhost:8080/api/v1/metrics
2. Vérifier les logs pour les erreurs d'enregistrement

---

📚 Références

• Prometheus Metrics
• Sentry Go SDK
• Zap Logger
• Gin Framework

---

✅ Checklist de Déploiement

• Variables d'environnement configurées (SENTRY_DSN, CHAT_SERVER_URL, etc.)
• Endpoint /health accessible depuis le load balancer
• Endpoint /status accessible pour le monitoring
• Métriques Prometheus scrapées par Prometheus
• Dashboard Grafana configuré
• Alertes configurées (service down, latence élevée)
• Tests d'intégration passent
• Documentation à jour

---

Auteur: Veza Backend Team
Dernière mise à jour: 2025-12-05