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

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

### Configuration Prometheus (scrape config)

Ajoutez cette configuration à votre `prometheus.yml`:

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

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

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

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

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

### Utilisation

```typescript
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**
   ```promql
   rate(veza_gin_http_requests_total[5m])
   ```

2. **Error Rate**
   ```promql
   rate(veza_gin_http_requests_total{status=~"5.."}[5m])
   ```

3. **Response Time (p95)**
   ```promql
   histogram_quantile(0.95, rate(veza_gin_http_request_duration_seconds_bucket[5m]))
   ```

4. **Request Duration par Endpoint**
   ```promql
   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**
   ```yaml
   - 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**
   ```yaml
   - 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**
   ```yaml
   - 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

- [x] Prometheus metrics exposées sur `/api/v1/metrics`
- [x] Sentry backend configuré avec `SENTRY_DSN`
- [x] 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

```bash
# 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](https://prometheus.io/docs/)
- [Sentry Documentation](https://docs.sentry.io/)
- [Grafana Documentation](https://grafana.com/docs/)

---

## 🆘 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