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

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:

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

Queries PromQL Utiles

# 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

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

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:

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:

# 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

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é:

   curl http://192.168.9.23:3000/healthz
   

2. Vérifier l'endpoint metrics:

   curl http://192.168.9.23:3000/metrics
   

3. Vérifier les logs Prometheus:

   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
• Grafana Documentation
• prom-client (Node.js)
• OpenMetrics Specification