Operațiunea Metrics API

1) Scopul și domeniul de responsabilitate

• SLI/SLO consecvent (login, depozit, rată, retragere);
• IRC (indicatori de risc precoce: PSP/KYC/cozi/replicări);
• valorile de afaceri (succesul autorizațiilor GEO/PSP/bancare, ponderea pariurilor de succes, duratele traseului cheie p95/p99);
• lecturi sigure, ieftine și previzibile pentru tablouri de bord, alertă, pagini de stare, raportare.

2) Principii arhitecturale

Citiți-grele, scrie-puține: API citește numai agregate de la TSDB/cache.
SLO-first: răspunsurile sunt previzibile în timp; erori și degradare - sunt semnalizate transparent.
Cost-conștient: sub-eșantionare, cote, caracteristici canare în SDK.
Privacy-by-design: fără PII în metadate/etichete; jetoane, geo-poartă, SoD.
Multi-chiriaș: izolare după marcă/regiune/mediu.

3) Modelul de date (suprafață)

Seria metrică = 'metric _ id' +' labels {} '+' timestamp '+' value '(+ opțional' exemplar {trace _ id =...} ').

3. 1 Categorii

SLI/SLO: 'auth _ success _ rate', 'bet _ settle _ p99 _ ms',' retrage _ 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 Etichete (strict limitate)

„region”, „chiriaş”, „mediu”, „serviciu”, „psp”, „bank _ group”, „geo”, „dispozitiv”, „versiune”, „componentă”.
Interzis: 'userId',' sessionId', numere de card/document brut.

4) Versioning și compatibilitate

Cale de bază: '/v1/metrics/... '; modificări incompatibile - numai în noul „vX”.
Adăugarea de etichete/serii - compatibil înapoi.
Schimbarea semanticii se face prin câmpul 'schema _ version' în răspunsul și perioada de grație.
Directorul schemei este publicat ca „/v1/scheme ”.

5) Criterii finale (REST, similare în gRPC/GraphQL)

1. 'GET/v1/metrics/query'

• „metric” (multi), „de la”, „la”, „pas” (резолюция), „agg” („avg'sum'min'max'p50|p95|p99”)
• 'filter [label] = valoare' (multi), 'group _ by = label1, label2',
• 'downsample=1m|5m|1h', 'exemplars = true' false ',' limit '(рядов),' page '.
• Răspuns: array of series '{metric, labels {}, points: [ts, value]], exemplars?}'.

2. „POST/v1/metrics/vrac-query”

Corp: Până la 50 de cereri într-un singur lot. Salvează cererile pentru tablouri de bord complexe.

3. 'GET/v1/metrics/instant'

Valorile curente la "ts' (sau" acum ") cu filtrele specificate.

4. 'GET/v1/metrics/catalog'

Lista de valori disponibile, descrieri, etichete, agregări permise, legături SLO.

5. 'GET/v1/metrics/health'

Starea API în sine: latență p95, reziliență cache, cota de hit-uri cache.

6. 'GET/v1/metrics/slo'

Vizualizări SLO gata: consumul bugetului de eroare (rapid/lent), stările țintă.

6) Cereri de probă

6. 1 Succesul autorizațiilor PSP în TR, grila 1-min, 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” pe regiuni, cu exemplare (exemple de urme):

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

6. 3 Statutul SLO de depozit instantaneu al UE:

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

6. 4 Lot de 3 interogări (POST/vrac-interogare) - pentru un graf cu straturi.

7) Agregări și percentile

Percentilele p50/p95/p99 se calculează la nivelul TSDB/agregator; cu „downsample” - cu compoziția corectă (t-digest/HDR).
'group _ by' este permis numai pe etichete albe, astfel încât să nu arunce în aer cardinalitatea.
„step” este validat: minim 10 pentru timp real, 1m pentru tablouri de bord publice.

8) Numerar, sub-eșantionare și prospețime

Memorie cache pe mai multe niveluri: în memorie (până la 30-60 s), distribuită (până la 5 min), CDN pentru vizualizări SLO publice.
Sub-eşantionare: automată cu ferestre mari ('> 24h') → 5m/1h puncte.
Freshness- заголовки: 'X-Data-Prospetime: 12s', 'X-Downsample: 1m', 'X-Partial: true' false '.

9) Multi-chiriaș și izolare

Fiecare cerere trebuie să conțină „chiriaș” (în token/etichete).
ABAC/RBAC: rolul/politica restricționează accesul prin „tenant”, regiune, mediu, metric_id'.
Afișează/încarcă-înapoi: anteturile „X-Query-Cost-Estimate” și contoarele de utilizare.

10) Autentificare și securitate

OAuth2 mTLS/jetoane de servicii de aplicare.
SoD: accesul la valori cu posibile riscuri de reglementare (finanțe, RG) - roluri individuale.
Limitele ratei: prin cheia clientului și prin 'metric _ id'.
Salubritate PII: serverul validează absența filtrelor/etichetelor interzise.

11) Geo-rezidență și conformitate

Datele sunt citite din depozitele regionale (EU/LATAM/APAC) privind politica de rezidență.
Interogări transregionale - numai pentru agregate fără PII și cu „compliance _ scope”.

12) Instanțe și corelație

Cu 'exemplars = true', răspunsul la punctele percentile returnează referințe la o pereche reprezentativă de 'trace _ id' (fără PII) pentru RCA rapid.
Corelație: "corelation _ id' este disponibil în metadatele răspunsului.

13) SLA API și bug-uri

SLA răspuns: p95 ≤ 300 ms (cache), ≤ 1. 5 s (cale rece), disponibilitate ≥ 99. 9%.

• '400' - cerere invalidă (prea mult 'group _ by', rău 'step'),
• „403” - drepturi insuficiente/chiriaș,
• „409” - conflict de circuit,
• „429” - limita cotei/ratei,
• „502/504” - degradarea depozitării (în anteturi - recomandări pentru downsample/pas),
• '206' este un răspuns parţial (unele cioburi nu sunt disponibile).
• Anteturi de diagnostic: "X-Query-Plan", "X-Query-Cache", "X-Query-Shards'," X-RateLimit-Remain ".

14) Cote, limite de rată și backpressure

Implicit: 10 rps per client, 50 de episoade per răspuns, fereastră de 3 ore, "pas ≥ 10c'.
Jetoane Burst: pentru tablouri de bord pe ecranul mare, ferestre coordonate.
Backpressure: serverul poate returna „Retry-After”, sfătuind să crească „pas” activați „downsample”.

15) SDK și cele mai bune practici

SDK: Typescript/Go/Python. Implicit: memorie cache agresivă, backoff exponențial, „If-None-Match”.

• interogări de grup prin „/vrac-interogare ”;
• utilizați „group _ by” în mod rar;
• pentru recenzii istorice - 'downsample = 1h';
• adăugați timeout-uri ≤ 2 secunde și jetoane de „anulare”.

15. 1 Mini Exemplu (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) Observabilitatea metricii API

SLI API: , , .
KPI de utilizare: rps, volumul mediu de răspuns, valorile costurilor de top.
Alerte: burn-rate pe erori, spike '429', drop cache-hit <țintă.
Busteni: structurati, fara PII; 'tenant', 'metric _ id',' query _ cost _ class'.

17) Politicile FinOps

Solicitați clase: A (tablouri de bord în timp real), B (operațional), C (analytics). Cote diferite/TTL.
Cost: $/GB citește, $/cerere, $/grafic. Raport lunar privind valorile și etichetele „grele”.
Optimizări: îmbinarea serverului, pre-agregate pentru SLO-view popular, auto-sfaturi pentru client (sugerat „pas/downsample”).

18) Integrări

Status page: Citește vizualizări SLO gata făcute.
Alertare: regulile se bazează pe „/slo ”și„ instant ”.
Incident-bot: fragmente rapide de grafice/felii prin presetări scurte.
Flux de lucru/Release-gates: bloc de lansare la SLO-uri roșii.

19) Foaie de parcurs de implementare (6-10 săptămâni)

Ned. 1-2: catalog metrice, etichete whitelists, '/catalog 'scheme, '/interogare' prototip cu cache, și downsample.
Ned. 3-4: „/vrac-interogare ”, „/slo”, exemplare, RBAC/ABAC, cote/limite de rată.
Ned. 5-6: geo-sharding, CDN pentru vizualizare publică, titluri FinOps, tablou de bord API SLI.
Ned. 7-8: SDK (TS/Go/Py), recomandări/interogare linter, teste canare.
Ned. 9-10: învățături de haos (eșec ciob/cache), optimizarea valorii, politica de depreciere.

20) Artefacte

Catalog metric: id, unități, descrieri, disponibile „agg”, etichete valide.
Politica de acces: roluri, domenii, limite, SoD.
Query Style Guide - exemple de interogări corecte/incorecte.
Harta SLO: Respectarea SLI ↔ scopurilor publice.
Raport cost: interogări/etichete scumpe de top, plan de optimizare.

21) KPI/KRI API Metrics

p95/99 latență, rata de eroare, răspunsuri parțiale.
Cache hit ratio și economii CPU/IO.
Mărimea medie a răspunsului și $/cerere.
Proporția de tablouri de bord care au trecut la „/vrac-interogare ”.
Incidente datorate cererilor mari de cardinalitate.

22) Antipattern

Gratis „grup _ de” de zeci de mărci → o explozie de cardinalitate.
Percentilele „pliate” pe client → distorsiuni.
Cererile pentru 30-90 de zile fără downsample → scumpe și lente.
Amestecarea chiriașilor/regiunilor într-un singur răspuns fără autorizație.
Panouri publice fără memorie cache/CDN.
Schimbarea semanticii metricii fără „vX” și perioada de grație.

Total

Metrica operațiunilor API este un strat de citire stabil, sigur și rentabil peste telemetrie: scheme și percentile standardizate, memorie cache și sub-eșantionare, etichete și accesorii stricte, vizualizare SLO și exemplare pentru RCA, SLA transparente și costuri. Acest strat vă permite să construiți tablouri de bord fiabile, alerte, comunicații de stare și porți de eliberare fără a risca intimitatea, bugetul și performanța.