Monitoring

Monitoring

Dernière mise à jour : 2026-05-10

État actuel : minimal

L'app expose un seul endpoint health, qui sert au healthcheck Docker. Pas de Prometheus / Grafana / OpenTelemetry / Sentry actuellement.

GET /api/health

{
  "status": "ok",
  "timestamp": "2026-05-10T12:34:56.789Z"
}

Public (pas d'auth). Utilisé par le healthcheck Docker (docker-compose.yml) :

healthcheck:
  test: ["CMD", "wget", "-qO-", "http://localhost:3000/api/health"]
  interval: 30s
  timeout: 5s
  retries: 3
  start_period: 10s

Si 3 échecs consécutifs → container marqué unhealthy. Pas de restart auto en place — c'est manuel.

GET /api/admin/health (admin only)

Plus riche, utilisé par la page /admin :

{
  "qdrant": { "ok": true, "collections": 14, "stats": {...} },
  "tei": { "ok": true, "model": "BAAI/bge-m3" },
  "reranker": { "ok": true },
  "claude_ssh": { "ok": true, "latency_ms": 5234 },
  "smtp": { "ok": true, "configured": true },
  "stats": {
    "totalGames": 23,
    "totalQuestions": 542,
    "totalUsers": 3
  }
}

Si tu vois Qdrant/TEI/Reranker ok: false, le RAG est cassé. Investigation :

• docker logs <service> côté Unraid
• Tester le service directement : curl http://192.168.10.100:8099/health (TEI)

Ajouter un monitoring externe

Suggestions (non implémentées) :

Uptime Kuma

• Le plus simple. Container Unraid à part.
• Monitor : HTTP GET https://rules.thymon.fr/api/health toutes les 60s
• Notifications : ntfy / email / Telegram
• Permet de monitorer aussi NPM, Qdrant, TEI, etc. depuis un seul endroit.

Prometheus + Grafana

• Plus poussé. Hono peut exposer des métriques /metrics (lib @hono/prometheus-metrics ou équivalent).
• Métriques utiles : latence RAG p50/p99, count erreurs Claude, queue ingestion, etc.
• Container Prometheus + Grafana sur Unraid.

Sentry

• Erreurs côté backend + frontend
• DSN à mettre dans SENTRY_DSN env var
• Wrapper src/lib/logger.ts pour pousser sur level === 'error'

Alerting

Aucun alerting actuellement. Si l'app meurt à 3h du matin, tu le vois quand tu poses ta première question le lendemain.

Pour ajouter du basique :

• Uptime Kuma + notif ntfy / Telegram
• ou cron qui ping /api/health toutes les 5 min et envoie un mail si fail (script externe)

Métriques applicatives à logger

Si tu veux instrumenter sans monitoring formel :

• Logger info les timings RAG ([rag] question_id=X total=4521ms hyde=2103ms retrieve=854ms rerank=121ms llm=1443ms)
• Logger info les ingestion durées et tailles ([ingest] game=X chunks=234 ocr_pages=12 duration_s=380)
• Logger warn les fallbacks (HyDE timeout, retrieval vide, reranker down…)

Ensuite tu peux faire grep + jq sur /app/data/logs/server.log pour des stats ad hoc.