Skip to content

observabilité backend (temps réel)

AGUECH OMAR requested to merge feat/Plan_observabilité—version_durcie_v3 into develop

Description

Ajout d’un socle d’observabilité backend complet pour Quantum Bluff : logs structurés JSON, métriques Prometheus, endpoints health (live/ready/degraded), instrumentation métier (poker, casino, recovery, sockets), et documentation associée. Objectifs : remplacer les console.log par un logger structuré (Pino) introduire une corrélation requestId + contexte métier (gameId, handId, actionId…) exposer des métriques Prometheus (/metrics) distinguer liveness / readiness / degraded instrumenter les chemins critiques (poker runtime, idempotence casino, rate limit, recovery, sockets) préparer dashboards Grafana et alerting Cette MR pose la fondation d’exploitation pour le poker temps réel, blackjack multi, casino et recovery.

Lien vers la tâche

Closes #observability-v3

Type de changement

  • Feature — nouvelle fonctionnalité
  • Fix — correction de bug
  • Refactor — modification du code sans changement fonctionnel
  • Docs — documentation uniquement
  • Chore — maintenance (deps, config, etc.)
  • Hotfix — correction urgente en production

Modifications principales

Socle observabilité Ajout dossier : server/src/observability/ logger.ts — logger Pino JSON httpAccess.middleware.ts — requestId + log HTTP structuré metrics.ts — prom-client registry + compteurs métier routeGroup.ts — normalisation path → route_group rateLimitWithMetrics.ts — wrapper express-rate-limit instrumenté healthCheck.ts — logique live / ready / degraded Endpoints Ajout : GET /api/health/live GET /api/health/ready GET /api/health GET /metrics (auth optionnelle via METRICS_BEARER_TOKEN) Instrumentation métier Poker : poker_actions_total logs poker_action_rejected logs poker_action_accepted Casino : casino_idempotency_total casino_idempotency_rejected mismatch / duplicate logs Recovery : recovery_boot_events_total logs boot / cleanup Sockets : socket_io_events_total logs connexion / déconnexion Rate limit : rate_limit_exceeded_total logs rate_limit_exceeded DB / Prisma : prisma_slow_query prisma error event db_errors_total Redis : logs structurés connexion / fallback Middleware HTTP Remplacement : console.log HTTP → log structuré : http_request_complete avec : requestId routeGroup status durationMs Health + degraded mode Ajout : app_component_up app_degraded ready retourne : ready degraded état DB état Redis Sécurité /metrics protégé via METRICS_BEARER_TOKEN (optionnel) sanitization logs (pas de body / secrets) Docs Ajout : Docs/OBSERVABILITY.md contrat msg sévérité logs sampling live/ready/degraded Prometheus scrape KPIs P0/P1/P2 roadmap Docs/prometheus-alerts.example.yml exemples alertes 5xx degraded rate limit poker stale spike Tests métriques désactivées sous Jest build OK 366 tests OK Dépendances ajoutées pino prom-client

Comment tester

  1. Lancer le backend npm run dev
  2. Vérifier health endpoints GET /api/health/live GET /api/health/ready GET /api/health
  3. Vérifier métriques Prometheus GET /metrics
  4. Faire une requête HTTP (ex roulette) → vérifier log structuré http_request_complete
  5. Déclencher rate limit → vérifier : log rate_limit_exceeded métrique rate_limit_exceeded_total Lancer une action poker → vérifier : poker_actions_total logs poker_action_* Vérifier degraded mode (Redis down) → /api/health/ready doit retourner degraded: true

Checklist

  • Code relu et conforme aux conventions du projet
  • Tests ajoutés ou mis à jour si nécessaire
  • Documentation mise à jour (si applicable)
  • Pipeline CI vert
  • Pas de régression détectée

Impact potentiel

  • Breaking change — migration nécessaire
  • Performance — impacts à surveiller
  • Sécurité — audit recommandé

Reviewers

  • Backend (@azra, @soheil)
  • Frontend (@mohamed, @yigit)
  • Sécurité (@linda, @massi)
  • BDD (@elhadj)
  • Revue générale (@aguech)
  • Validation chef de projet (@omar)

Merge request reports