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

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

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

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

```json
{
  "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.