Objectifs de service et métriques

Cette page fixe les objectifs de service de BlockLucky pour la période de la Grande Loterie citoyenne, décrit les métriques que le backend expose et donne les règles de dimensionnement. Les objectifs servent de référence aux seuils des tests de charge.

#Indicateurs et objectifs

Fenêtre glissante de 28 jours.

L'ancienne version de ces objectifs fixait 300 ms pour la consultation. Les seaux de l'histogramme (0.25 puis 0.5) ne permettent pas de mesurer ce seuil exactement : l'objectif est ramené au seuil mesurable le plus proche, 250 ms. Pour revenir à 300 ms, il faut ajouter 0.3 à la liste buckets de metrics.ts.

L'achat de ticket attend la confirmation de la transaction sur la chaîne (tx.wait() dans lottery.gateway.ts). Sur le nœud Hardhat local, le minage est immédiat et l'objectif de 800 ms est réaliste. Sur Sepolia, un bloc est produit environ toutes les 12 secondes : cet objectif de latence n'a pas de sens et seul l'objectif de disponibilité s'applique.

#Budget d'erreur

Un objectif de 99,9 % sur 28 jours autorise 0,1 % de requêtes en échec, soit l'équivalent d'environ 40 minutes d'indisponibilité totale (28 × 24 × 60 × 0,001 = 40,3 minutes). Quand le budget est consommé, les livraisons de fonctionnalités s'arrêtent au profit des corrections de fiabilité.

#Alertes

Une alerte se déclenche sur la vitesse de consommation du budget (burn rate), jamais sur une cause seule comme le processeur ou la mémoire. Une règle courante : alerter quand le taux d'erreur dépasse 14,4 fois le rythme nominal à la fois sur 1 heure et sur 5 minutes. À ce rythme, 2 % du budget mensuel part en une heure ; la fenêtre courte évite une alerte qui continuerait de sonner après la fin du problème.

(
  sum(rate(http_request_duration_seconds_count{route=~"/api(/v1)?/lottery/buy",status_code=~"5.."}[1h]))
  / sum(rate(http_request_duration_seconds_count{route=~"/api(/v1)?/lottery/buy"}[1h]))
) > 14.4 * 0.001
and
(
  sum(rate(http_request_duration_seconds_count{route=~"/api(/v1)?/lottery/buy",status_code=~"5.."}[5m]))
  / sum(rate(http_request_duration_seconds_count{route=~"/api(/v1)?/lottery/buy"}[5m]))
) > 14.4 * 0.001

#Métriques exposées

Les métriques sont définies dans backend/src/observability/metrics.ts avec prom-client, dans un registre qui ajoute à chaque série les étiquettes service="blocklucky-backend" et environment (valeur de NODE_ENV).

Les métriques par défaut ne sont pas collectées quand METRICS_ENABLED=false ou quand NODE_ENV=test.

#Étiquette route

L'étiquette route vaut req.baseUrl suivi du chemin déclaré dans le routeur, par exemple /api/v1/lottery/rewards/:id et non l'identifiant réel : le nombre de séries reste borné. Comme les routes sont montées deux fois, sous /api/v1 et sous /api, une même route produit deux valeurs selon le préfixe appelé par le client ; les requêtes PromQL utilisent donc l'expression /api(/v1)?/…. Une requête qui ne correspond à aucune route (404) est étiquetée unmatched.

#Événements métier

#Où lire les métriques

curl -s -H "Authorization: Bearer $METRICS_TOKEN" http://localhost:2053/metrics | grep http_request_duration_seconds_count

#Requêtes utiles

Taux de réussite de la consultation sous 250 ms, sur 5 minutes :

sum(rate(http_request_duration_seconds_bucket{route=~"/api(/v1)?/lottery/status",status_code=~"2..",le="0.25"}[5m]))
/
sum(rate(http_request_duration_seconds_count{route=~"/api(/v1)?/lottery/status"}[5m]))

95e centile de la latence par route :

histogram_quantile(0.95, sum by (le, route) (rate(http_request_duration_seconds_bucket[5m])))

Taux d'échec des emails :

sum(rate(queue_jobs_total{queue="emails-queue",status="failed"}[1h]))
/
sum(rate(queue_jobs_total{queue="emails-queue"}[1h]))

status="failed" compte chaque tentative en échec, y compris celles qui seront réessayées (cinq tentatives par job). C'est une borne haute du taux d'échec définitif.

#Sondes de santé

Définies dans system.routes.ts, hors rate limiting et hors mode maintenance :

/health/deep répond pass si tout va bien, warn si Redis est absent (l'API fonctionne en mode dégradé, voir l'ADR 0002) et fail avec un statut 503 si PostgreSQL est injoignable.

#Capacité

#PostgreSQL

Chaque processus (API ou worker) ouvre un pool de DB_POOL_MAX connexions, 10 par défaut (prisma.config.ts). Le serveur accepte max_connections=100, dont 3 réservées par défaut aux superutilisateurs. Au-delà de 8 processus, il faut réduire DB_POOL_MAX ou placer PgBouncer en mode transaction devant PostgreSQL.

Chaque connexion de l'application est ouverte avec :

#HTTP

Réglés dans server.ts :

#Redis

256 Mo avec la politique noeviction : une fois plein, Redis refuse les écritures. Les jobs terminés sont gardés 24 heures (1 000 au plus par file), les jobs en échec 14 jours (queue.options.ts). Surveiller used_memory avec redis-cli INFO memory.

#Blockchain

Le keeper interroge le contrat toutes les KEEPER_INTERVAL_MS (10 s) et l'indexeur lit les journaux toutes les INDEXER_INTERVAL_MS (3 s), par tranches de 2 000 blocs au plus. Les actions on-chain (versement de cagnotte, remboursements, badges) sont traitées une à une (concurrency: 1) pour ne pas désordonner les nonces du compte opérateur.

#Arrêt propre

Sur SIGTERM ou SIGINT, shutdown.ts :

1. marque l'arrêt : /health/ready répond 503 (et la sonde du worker aussi) ;
2. ferme dans l'ordre le serveur HTTP (connexions inactives coupées), le relais d'événements Socket.IO, Socket.IO, l'indexeur et le keeper, les workers BullMQ, les files, le client blockchain, Prisma et Redis ;
3. quitte avec le code 0, ou force l'arrêt avec le code 1 après SHUTDOWN_TIMEOUT_MS (25 s).

Une promesse rejetée non gérée déclenche aussi l'arrêt en production, et une exception non capturée dans tous les environnements.