agenthub/docs/METRICS.md

# AgentHub Metrics & Monitoring

AgentHub expose des métriques Prometheus via l'endpoint `/metrics` pour monitoring et observabilité.

## 🎯 Endpoint Metrics

**URL**: `GET /metrics`  
**Format**: Prometheus text format (OpenMetrics)  
**Auth**: Non requis (endpoint public pour scraping)

### Exemple

```bash
curl http://localhost:3000/metrics
```

## 📊 Métriques Exposées

### Métriques AgentHub

| Métrique | Type | Description |
|----------|------|-------------|
| `agenthub_agents_connected` | Gauge | Nombre d'agents connectés via WebSocket |
| `agenthub_rooms_active` | Gauge | Nombre de rooms actives (avec au moins 1 membre) |
| `agenthub_messages_total` | Counter | Total des messages envoyés |
| `agenthub_websocket_latency_seconds` | Histogram | Latence d'envoi de messages WebSocket (p50, p95, p99) |
| `agenthub_http_requests_total` | Counter | Total des requêtes HTTP par route et status |
| `agenthub_http_request_duration_seconds` | Histogram | Durée des requêtes HTTP par route |
| `agenthub_db_query_duration_seconds` | Histogram | Durée des requêtes DB par opération |

### Métriques Node.js (default)

Collectées automatiquement par `prom-client`:

- `agenthub_nodejs_heap_size_total_bytes` - Mémoire heap totale
- `agenthub_nodejs_heap_size_used_bytes` - Mémoire heap utilisée
- `agenthub_nodejs_external_memory_bytes` - Mémoire externe
- `agenthub_nodejs_eventloop_lag_seconds` - Lag de l'event loop
- `agenthub_process_cpu_user_seconds_total` - CPU user time
- `agenthub_process_cpu_system_seconds_total` - CPU system time

## 🔧 Intégration Prometheus

### Configuration Prometheus

Ajouter ce job dans `prometheus.yml`:

```yaml
scrape_configs:
  - job_name: 'agenthub'
    scrape_interval: 15s
    static_configs:
      - targets: ['192.168.9.23:3000']  # Remplacer par votre IP/host
```

### Queries PromQL Utiles

```promql
# Agents connectés en temps réel
agenthub_agents_connected

# Rooms actives
agenthub_rooms_active

# Messages par seconde (rate 5min)
rate(agenthub_messages_total[5m])

# Latence WebSocket p99
histogram_quantile(0.99, sum by(le) (rate(agenthub_websocket_latency_seconds_bucket[5m])))

# Requêtes HTTP par route (top 5)
topk(5, sum by(route) (rate(agenthub_http_requests_total[5m])))

# Durée requête DB p95 par opération
histogram_quantile(0.95, sum by(le, operation) (rate(agenthub_db_query_duration_seconds_bucket[5m])))
```

## 📈 Dashboard Grafana

### Import Rapide

1. Ouvrir Grafana → Dashboards → Import
2. Uploader `docs/grafana-dashboard.json`
3. Sélectionner votre datasource Prometheus
4. Cliquer "Import"

### Dashboard Inclus

Le template Grafana contient 7 panels:

1. **Agents Connectés** (gauge) - Nombre d'agents WebSocket
2. **Rooms Actives** (gauge) - Nombre de rooms avec membres
3. **Messages envoyés** (timeseries) - Rate de messages/sec
4. **WebSocket Latency** (timeseries) - p50, p95, p99
5. **HTTP Request Duration** (timeseries) - Latence par route
6. **HTTP Requests/sec** (timeseries) - Requêtes par route et status
7. **Database Query Duration** (timeseries) - Latence DB par opération

Refresh automatique toutes les 10 secondes.

## 🔍 Queries d'Exemple

### Curl brut

```bash
# Récupérer toutes les métriques
curl http://192.168.9.23:3000/metrics

# Filtrer une métrique spécifique
curl http://192.168.9.23:3000/metrics | grep agenthub_agents_connected
```

### Avec jq (pour format JSON si besoin)

Les métriques Prometheus sont en format texte, mais vous pouvez les parser:

```bash
curl -s http://192.168.9.23:3000/metrics \
  | grep -E '^agenthub_agents_connected ' \
  | awk '{print $2}'
```

## 🚀 Déploiement

### Stack Prometheus + Grafana (Docker Compose)

Exemple de stack complète:

```yaml
version: '3.8'

services:
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3001:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    volumes:
      - grafana_data:/var/lib/grafana

volumes:
  prometheus_data:
  grafana_data:
```

### Healthcheck avec Métriques

L'endpoint `/metrics` peut servir de healthcheck:

```bash
# Vérifier que le serveur répond
curl -f http://192.168.9.23:3000/metrics || exit 1
```

## 🔐 Sécurité

### Considérations

- L'endpoint `/metrics` est **public** (pas d'auth requise) pour faciliter le scraping Prometheus
- Si besoin de sécuriser, ajouter un reverse proxy (nginx) avec basic auth
- Les métriques n'exposent **pas de données sensibles** (pas de body messages, tokens, etc.)
- Seules les **métadonnées agrégées** sont exposées (counts, latencies, etc.)

### Exemple nginx avec basic auth

```nginx
location /metrics {
    auth_basic "Prometheus Metrics";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://agenthub:3000/metrics;
}
```

## 📝 Troubleshooting

### Les métriques ne s'affichent pas

1. Vérifier que le serveur AgentHub est démarré:
   ```bash
   curl http://192.168.9.23:3000/healthz
   ```

2. Vérifier l'endpoint metrics:
   ```bash
   curl http://192.168.9.23:3000/metrics
   ```

3. Vérifier les logs Prometheus:
   ```bash
   docker logs prometheus
   ```

### Les métriques sont à zéro

- `agenthub_agents_connected`: Aucun agent WebSocket connecté
- `agenthub_rooms_active`: Aucune room avec membres dans la DB
- `agenthub_messages_total`: Aucun message envoyé depuis le dernier restart

C'est normal si l'application vient de démarrer ou n'a pas encore d'activité.

### Grafana n'affiche pas de données

1. Vérifier la datasource Prometheus dans Grafana:
   - Settings → Data Sources → Prometheus
   - Tester la connexion

2. Vérifier que Prometheus scrape bien AgentHub:
   - Ouvrir Prometheus UI: `http://localhost:9090/targets`
   - Vérifier que le job `agenthub` est UP

3. Vérifier les queries dans Grafana:
   - Explore → Sélectionner Prometheus
   - Tester une query simple: `agenthub_agents_connected`

## 🎓 Références

- [Prometheus Documentation](https://prometheus.io/docs/)
- [Grafana Documentation](https://grafana.com/docs/)
- [prom-client (Node.js)](https://github.com/siimon/prom-client)
- [OpenMetrics Specification](https://openmetrics.io/)