API métriques des opérations

1) Désignation et zone de responsabilité

• consistance SLI/SLO (login, dépôt, taux, retrait) ;
• KRI (indicateurs de risque précoces : PSP/KYC/file d'attente/réplication) ;
• métriques commerciales (succès des autorisations GEO/PSP/banques, proportion de taux de réussite, p95/p99 durées des voies clés) ;
• lecture sûre, bon marché et prévisible pour les dashboards, alerting, status pages, reporting.

2) Principes architecturaux

Read-heavy, write-few : l'API ne lit que les agrégations du TSDB/cache.
SLO-first : les réponses sont prévisibles dans le temps ; erreurs et dégradations - signalées de manière transparente.
Cost-aware : downsampling, quotas, fiches canaries en SDK.
Privacy-by-design : pas de PII dans les métadonnées/labels ; Tokens, géo-gate, SoD.
Multi-tenant : Isolation par marque/région/environnement.

3) Modèle de données (surface)

Série de métriques = 'metric _ id' + 'labels {}' + 'timestamp' +' value '(+ optionnellement' examplar {trace _ id =...} ').

3. 1 Catégories

SLI/SLO: `auth_success_rate`, `bet_settle_p99_ms`, `withdraw_tat_p95_ms`, `api_5xx_rate`.
KRI: `queue_consumer_lag`, `db_replication_lag`, `psp_soft_decline_rate`.
Бизнес: `deposits_success_pct`, `bets_success_pct`, `kyc_pass_rate`.
Инфра: `cpu_util`, `cache_hit_ratio`, `cdn_waf_block_rate`.

3. 2 Labels (strictement limités)

`region`, `tenant`, `environment`, `service`, `psp`, `bank_group`, `geo`, `device`, `version`, `component`.
Interdit : 'userId', 'sessionId', numéros bruts de cartes/documents.

4) Versioning et compatibilité

Chemin de base : '/v1/metrics/... '; les modifications incompatibles sont uniquement dans le nouveau 'vX'.
Ajout de labels/séries - backward-compatible.
Changement de sémantique - via le champ 'schema _ version' dans la réponse et la période grace.
Le catalogue des schémas est publié sous la forme '/v1/schemas '.

5) Endpoints (REST, similaire dans gRPC/GraphQL)

1. `GET /v1/metrics/query`

• `metric` (multi), `from`, `to`, `step` (резолюция), `agg` (`avg|sum|min|max|p50|p95|p99`),
• `filter[label]=value` (multi), `group_by=label1,label2`,
• `downsample=1m|5m|1h`, `exemplars=true|false`, `limit` (рядов), `page`.
• Réponse : tableau de séries '{metric, labels {}, points : [[ts, value]], examplars ?} ".

2. `POST /v1/metrics/bulk-query`

Corps : jusqu'à 50 demandes par batch. Permet d'économiser des demandes pour les dashboards complexes.

3. `GET /v1/metrics/instant`

Les valeurs actuelles au moment 't' (ou « maintenant ») avec les filtres spécifiés.

4. `GET /v1/metrics/catalog`

Liste des métriques, descriptions, étiquettes, agrégations admissibles, références SLO disponibles.

5. `GET /v1/metrics/health`

L'état de l'API elle-même : latency p95, la tolérance aux pannes du cache, la proportion de cache hits.

6. `GET /v1/metrics/slo`

Ready SLO-view : budget d'erreurs (fast/slow), état des objectifs.

6) Exemples de demandes

6. 1 Succès des autorisations PSP dans TR, 1 min grid, p95 :

GET /v1/metrics/query? metric=auth_success_rate&from=2025-11-01T13:00:00Z&to=2025-11-01T16:00:00Z&step=1m&agg=p95&filter[geo]=TR&group_by=psp&downsample=1m

6. 2 p99 « bet→settle » par région, avec des exemples (par exemple) :

GET /v1/metrics/query? metric=bet_settle_p99_ms&from=...&to=...&step=5m&group_by=region&exemplars=true

6. 3 État instantané des dépôts SLO dans l'UE :

GET /v1/metrics/slo? domain=payments&region=EU&tenant=brandA

6. 4 Butch de 3 requêtes (POST/bulk-query) - pour un graphe avec des couches.

7) Agrégations et percentiles

Les percentiles p50/p95/p99 sont calculés au niveau du TSDB/agrégateur ; dans « downsample » - avec une composition correcte (t-digest/HDR).
'Group _ by 'est autorisé uniquement par les labels whitelisted afin de ne pas faire exploser la cardinalité.
« step » est validé : minimum 10c pour le realtime, 1m pour le dashboard public.

8) Cache, downsampling et fraîcheur

Cache hiérarchisé : in-memory (jusqu'à 30-60 s), distribué (jusqu'à 5 min), CDN pour SLO-view public.
Downsampling : automate aux grandes fenêtres ('> 24h') → 5m/1h.
Freshness-заголовки: `X-Data-Freshness: 12s`, `X-Downsample: 1m`, `X-Partial: true|false`.

9) Multi-tenant et isolant

Chaque requête doit contenir 'tenant' (en token/labels).
ABAC/RBAC : rôle/politique limite l'accès par "tenant, region, environment, metric_id'.
Show/charge-back : titres « X-Query-Cost-Estimate » et compteurs d'utilisation.

10) Authentification et sécurité

OAuth2 mTLS/jetons de service avec restriction par scope.
SoD : accès à des métriques avec des risques réglementaires possibles (finances, RG) - rôles distincts.
Limites de taux : par la clé du client et par "metric _ id'.
Assainissement PII : le serveur valide l'absence de filtres/labels interdits.

11) Géo-résidence et conformité

Les données sont lues dans le cadre de la politique de résidence régionale (EU/LATAM/APAC).
Demandes croisées régionales - uniquement pour les agrégats sans PII et si « conformité _ scope » est disponible.

12) Instances/Exemplars et corrélation

Lorsque 'examplars = true'en réponse aux points percentiles, les références à la paire 'trace _ id'représentative (sans PII) pour RCA rapide sont renvoyées.
Corrélation : 'correlation _ id'est disponible dans les métadonnées de réponse.

13) API SLA et erreurs

Réponse SLA : p95 ≤ 300 ms (cache), ≤ 1. 5 s (voie froide), accessibilité ≥ 99. 9%.

• « 400 » est une requête non validée (trop de « group _ by », mauvais « step »),
• « 403 » - droits insuffisants/tenants,
• « 409 » - conflit de schémas,
• « 429 » - quota/rate limite,
• « 502/504 » - dégradation du storage (dans les rubriques - recommandations sur le downsample/step),
• « 206 » est une réponse partielle (une partie des chardes n'est pas disponible).
• Les titres de diagnostic sont : 'X-Query-Plan', 'X-Query-Cache', 'X-Query-Shards', 'X-RateLimit-Remaining'.

14) Quotas, limites de vol et backpressure

Par défaut : 10 rps par client, 50 séries par réponse, fenêtre de 3 heures, 'step ≥ 10c'.
Jetons Burst : pour les dashboards sur grand écran, fenêtres convenues.
Backpressure : le serveur peut renvoyer 'Retry-After' en conseillant d'agrandir 'step '/activer' downsample '.

15) SDK et meilleures pratiques

SDK: Typescript/Go/Python. Par défaut : cache agressif, backoff exponentiel, 'If-None-Match'.

• regrouper les requêtes via '/bulk-query ';
• utilisez 'group _ by' de manière économique ;
• pour les revues historiques, « downsample = 1h » ;
• ajouter les temporisations ≤ 2 s et 'cancellation' -token.

15. 1 Mini-exemple (TS)

ts const res = await client. query({
metric: ["auth_success_rate"],
from: "-3h", to: "now", step: "1m",
agg: "p95",
filter: { geo: "TR", tenant: "brandA" },
group_by: ["psp"],
downsample: "1m",
exemplars: true,
timeoutMs: 1800
});

16) Observabilité des indicateurs API

SLI самого API: p95_latency, error_rate, cache_hit_ratio, partial_response_rate.
Utilisation KPI : rps, volume moyen de réponse, top-métriques en valeur.
Alert : burn-rate par erreur, sursaut '429', chute cache-hit <cible.
Logs : structurés, sans PII ; 'tenant', 'metric _ id',' query _ cost _ class '.

17) Politiques FinOps

Classes de requête : A (realtime dashboards), B (opérationnel), C (analytique). Quotas différents/TTL.
Coût : $/GB lecture, $/demande, $/graphique. Rapport mensuel sur les métriques et labels « lourds ».
Optimisations : merge serveur, pré-agrégats pour SLO-view populaires, auto-conseils au client (suggested 'step/downsample').

18) Intégration

Status Page : lit les SLO-view prêts.
Alerting : les règles reposent sur '/slo 'et' instant '.
Incident-bot : prélèvements rapides de graphiques/tranches à travers des presets courts.
Workflow/Release-gates : bloc de release sous SLO rouge.

19) Feuille de route pour la mise en œuvre (6-10 semaines)

Ned. 1-2 : catalogue des métriques, des étiquettes whitelists, des schémas '/catalogue ', du prototype '/query' avec cache et downsample.
Ned. 3-4 : '/bulk-query ', '/slo', exemplars, RBAC/ABAC, quotas/rate limites.
Ned. 5-6 : géo-charding, CDN pour Public View, FinOps-heads, dushboard de l'API SLI.
Ned. 7-8 : SDK (TS/Go/Py), recommandations/lignes directrices, tests canariaux.
Ned. 9-10 : exercice de chaos (échec des chardons/cache), optimisation des coûts, politique de déprécation.

20) Artefacts

Catalogue métrique : id, unités, descriptions, 'agg' disponibles, labels valides.
Politique d'accès : rôles, zones, limites, SoD.
Guide Query Style : exemples de requêtes correctes/incorrectes.
SLO Map : conformité de SLI ↔ objectifs publics.
Cost Report : Top des demandes/étiquettes coûteuses, plan d'optimisation.

21) KPI/KRI API métriques

p95/99 latency, error rate, partial responses.
Cache hit ratio et économies de CPU/IO.
Taille moyenne de la réponse et $/demande.
Proportion de dashboards qui sont passés à '/bulk-query '.
Incidents dus à des demandes de cardinalité élevée.

22) Anti-modèles

Un « groupe _ by » libre de dizaines de marques → une explosion de cardinalité.
Percentiles, « pliés » sur le client → distorsions.
Les demandes de 30-90 jours sans downsample sont → coûteuses et lentes.
Mélange de tenants/régions dans une seule réponse sans autorisation.
Panneaux publics sans cache/CDN.
Modification de la sémantique des métriques sans 'vX' et grace-période.

Résultat

L'API est une couche de lecture stable, sûre et économique au-dessus de la télémétrie : circuits et percentiments standardisés, cache et downsampling, labels et accès stricts, SLO-view et exemplars pour RCA, SLA transparent et coût. Cette couche permet de construire des dashboards fiables, des alertes, des communications de statut et des gates de sortie sans risque pour la vie privée, le budget et la productivité.