veza/MONITORING_SETUP.md

Monitoring Setup - Veza Platform

Date: 2025-01-27
Statut: ✅ Configuré et opérationnel

---

📊 Vue d'Ensemble

Le monitoring de Veza Platform est configuré avec :

• Prometheus pour les métriques backend
• Sentry pour le suivi des erreurs (backend + frontend)
• Grafana (optionnel) pour la visualisation

---

🔧 Backend - Prometheus

Configuration

Les métriques Prometheus sont automatiquement collectées via le middleware middleware.Metrics() dans veza-backend-api/internal/middleware/metrics.go.

Métriques Disponibles

1. HTTP Requests Total

   • Nom: veza_gin_http_requests_total
   • Labels: method, path, status
   • Type: Counter

2. HTTP Request Duration

   • Nom: veza_gin_http_request_duration_seconds
   • Labels: method, path, status
   • Type: Histogram

3. Error Metrics

   • Collectées via internal/metrics/error_metrics.go
   • Exposées via /api/v1/metrics/aggregated

Endpoints

• Prometheus Metrics: GET /metrics ou GET /api/v1/metrics
• Aggregated Metrics: GET /api/v1/metrics/aggregated
• System Metrics: GET /api/v1/system/metrics

Exemple de Requête

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

Configuration Prometheus (scrape config)

Ajoutez cette configuration à votre prometheus.yml:

scrape_configs:
  - job_name: 'veza-backend'
    scrape_interval: 15s
    metrics_path: '/api/v1/metrics'
    static_configs:
      - targets: ['localhost:8080']
        labels:
          environment: 'staging'
          service: 'veza-backend-api'

---

🐛 Backend - Sentry

Configuration

Sentry est initialisé dans veza-backend-api/cmd/api/main.go si SENTRY_DSN est configuré.

Variables d'Environnement

SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
SENTRY_ENVIRONMENT=staging  # ou production, development
SENTRY_SAMPLE_RATE_TRANSACTIONS=0.1  # 10% des transactions
SENTRY_SAMPLE_RATE_ERRORS=1.0        # 100% des erreurs

Intégration

• Erreurs capturées automatiquement via middleware.SentryRecover()
• Stack traces incluses
• Contexte enrichi avec request_id, user_id, etc.

---

🎨 Frontend - Sentry

Configuration

Sentry est configuré dans apps/web/src/lib/sentry.ts et doit être initialisé dans apps/web/src/main.tsx.

Variables d'Environnement

VITE_SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id

Fonctionnalités

• ✅ Capture automatique des erreurs React
• ✅ Performance Monitoring (10% en prod, 100% en dev)
• ✅ Session Replay (10% des sessions, 100% avec erreur)
• ✅ Enrichissement avec contexte (request_id, user_id)
• ✅ Filtrage des erreurs (réseau, CORS, extensions)

Initialisation

Assurez-vous que initSentry() est appelé dans main.tsx:

import { initSentry } from '@/lib/sentry';

// Initialiser Sentry avant le rendu de l'app
initSentry();

Utilisation

import { captureException, captureMessage } from '@/lib/sentry';

try {
  // Code qui peut échouer
} catch (error) {
  captureException(error, { context: 'additional info' });
}

// Capturer un message personnalisé
captureMessage('Something important happened', 'info');

---

📈 Grafana Dashboards

Dashboard Recommandé

Créez un dashboard Grafana avec les panneaux suivants:

1. Request Rate

   rate(veza_gin_http_requests_total[5m])
   

2. Error Rate

   rate(veza_gin_http_requests_total{status=~"5.."}[5m])
   

3. Response Time (p95)

   histogram_quantile(0.95, rate(veza_gin_http_request_duration_seconds_bucket[5m]))
   

4. Request Duration par Endpoint

   histogram_quantile(0.50, rate(veza_gin_http_request_duration_seconds_bucket[5m])) by (path)
   

Exemple de Dashboard JSON

Voir grafana/dashboards/veza-backend.json (à créer)

---

🚨 Alertes

Alertes Prometheus Recommandées

1. High Error Rate

   - alert: HighErrorRate
     expr: rate(veza_gin_http_requests_total{status=~"5.."}[5m]) > 0.1
     for: 5m
     annotations:
       summary: "High error rate detected"
   

2. Slow Response Time

   - alert: SlowResponseTime
     expr: histogram_quantile(0.95, rate(veza_gin_http_request_duration_seconds_bucket[5m])) > 2
     for: 5m
     annotations:
       summary: "Response time is slow"
   

3. Service Down

   - alert: ServiceDown
     expr: up{job="veza-backend"} == 0
     for: 1m
     annotations:
       summary: "Veza backend is down"
   

Alertes Sentry

Configurez dans le dashboard Sentry:

• Erreurs critiques (> 100 erreurs/min)
• Nouveaux types d'erreurs
• Erreurs par utilisateur (> 10 erreurs/user)

---

📝 Checklist de Déploiement

Staging

• Prometheus metrics exposées sur /api/v1/metrics
• Sentry backend configuré avec SENTRY_DSN
• Sentry frontend configuré avec VITE_SENTRY_DSN
• Grafana dashboard créé
• Alertes Prometheus configurées
• Alertes Sentry configurées

Production

• Prometheus scrape config ajouté
• Sentry DSN configuré (environnement: production)
• Sample rates ajustés (10% transactions, 100% erreurs)
• Grafana dashboard déployé
• Alertes configurées et testées
• Notifications configurées (email, Slack, PagerDuty)

---

🔍 Vérification

Vérifier Prometheus

# Vérifier que les métriques sont exposées
curl http://localhost:8080/api/v1/metrics | grep veza_gin

# Vérifier les métriques agrégées
curl http://localhost:8080/api/v1/metrics/aggregated

Vérifier Sentry

1. Générer une erreur de test dans le backend ou frontend
2. Vérifier dans le dashboard Sentry que l'erreur apparaît
3. Vérifier que le contexte (request_id, user_id) est présent

---

📚 Ressources

• Prometheus Documentation
• Sentry Documentation
• Grafana Documentation

---

🆘 Dépannage

Métriques Prometheus non visibles

1. Vérifier que le middleware Metrics() est activé dans le router
2. Vérifier que l'endpoint /metrics est accessible
3. Vérifier les logs pour erreurs de collecte

Sentry ne capture pas les erreurs

1. Vérifier que SENTRY_DSN / VITE_SENTRY_DSN est configuré
2. Vérifier que Sentry est initialisé (initSentry() appelé)
3. Vérifier les filtres d'erreurs (ignoreErrors, denyUrls)
4. Vérifier la console du navigateur pour erreurs Sentry