Logs
Logs
Dernière mise à jour : 2026-05-10
Logger central
Tous les logs serveur passent par src/lib/logger.ts. Conventions :
- Aucun
console.*danssrc/(saufsrc/config.tsqui boot avant le logger) - Préfixer le scope :
logger.info('[meta-sync] ...'),logger.error('[ssh] ...') - Niveaux :
debug/info/warn/error(filtrable viaLOG_LEVEL) - Format prod : JSON ligne (parseable via
jq) - Format dev : pretty print (lisible sans outil)
Locations
- Stdout / stderr Docker :
docker logs boardgame-referee - Fichier persistant :
/app/data/logs/server.log(volume Unraiddata/)
Rotation
Géré par entrypoint.sh au boot :
- Si
server.log > 50 Mo→ archive enserver-YYYYMMDD-HHMMSS.log - Purge automatique des archives
> 30 jours
Pas de rotation runtime (only at boot). Si tu fais beaucoup de DEBUG en prod, pense à restart le container ou logrotate manuellement.
Filtrer
# Live tail
docker exec boardgame-referee tail -f /app/data/logs/server.log
# Live tail avec scope filter (jq pour le JSON)
docker exec boardgame-referee tail -f /app/data/logs/server.log | jq 'select(.scope == "rag")'
# Grep classique
docker exec boardgame-referee grep "claude-quota" /app/data/logs/server.log | tail -50
# Toutes les erreurs des 24 dernières heures
docker exec boardgame-referee grep -E '"level":"error"' /app/data/logs/server.log | tail -100
Niveaux par défaut
| Environnement | LOG_LEVEL |
|---|---|
| Dev | debug |
| Prod | info |
Pour passer en debug en prod (temporaire) :
# Modifier .env Unraid : LOG_LEVEL=debug
# Restart container :
docker compose -f /mnt/user/appdata/boardgame-referee/docker-compose.yml restart app
⚠️ N'oublie pas de remettre en info après — debug est verbeux et remplit vite les 50 Mo.
Logs notables à surveiller
| Pattern | Sens |
|---|---|
[claude-quota] ClaudeQuotaError |
Pause auto enclenchée, vérifier resetAt |
[ssh] command rejected |
Wrapper oracle a bloqué une commande (debug /tmp/oracle-debug.log si nécessaire) |
[ingest] stage error |
Stage d'ingestion en échec |
[meta-sync] purge |
Purge hebdo des chunks méta périmés |
[forum-sync] |
Cron forums BGG (3h du matin par défaut) |
[hyde] timeout |
HyDE Haiku a dépassé 25s, fallback question brute |
[contextual-cache] flushed |
Cache JSON sauvé sur disque (avant quota error ou checkpoint) |
[rag] retrieve |
Diagnostics retrieval (timings, scores) en debug |
Pas de log aggregation externe
Pas de Loki / Grafana / ELK / Sentry actuellement. Tout reste dans le fichier Unraid + Docker logs.
Si un jour tu veux ajouter Sentry ou un log shipper :
- Ajouter une lib (
@sentry/node) - Wrapper le logger pour aussi pousser vers Sentry sur
level === 'error' - Configurer
SENTRY_DSNenv var - Le code reste centralisé dans
src/lib/logger.ts— les autres fichiers n'ont pas à savoir qu'on log ailleurs
Debug d'une question
Pour relire les diagnostics d'une question donnée (lecture seule) :
docker exec boardgame-referee npm run debug:question -- --id <questionId>
Affiche : question, réponse, chunks retrouvés, HyDE, timings — équivalent CLI du panneau /admin/feedback/<id>.