Amallaryň API metrikleri

1) Jogapkärçiligiň bellenilmegi we zolagy

• konsistent SLI/SLO (login, goýum, stawka, netije);
• KRI (töwekgelçiligiň irki görkezijileri: PSP/KYC/nobatlar/replikasiýa);
• biznes-metrika (GEO/PSP/banklar boýunça ygtyýarnamalaryň üstünligi, üstünlikli nyrhlaryň paýy, esasy ýollaryň dowamlylygy p95/p99);
• dashbordlar, alerting, status-sahypalar, hasabatlar üçin howpsuz, arzan we öňünden aýdyp boljak okalyşlar.

2) Binagärlik ýörelgeleri

Read-heavy, write-few: API diňe TSDB/kesişden agregasiýalary okaýar.
SLO-first: jogaplary wagt öňünden aýdyp bolýar; ýalňyşlyklar we zaýalanmalar - aç-açan signal berilýär.
Cost-aware: downsampling, kwotalar, SDK-da kanareýa çiçekleri.
Privacy-by-design: metadata/belliklerde PII ýok; tokenler, geo-gate, SoD.
Multi-tenant: marka/sebit/daşky gurşaw boýunça izolýasiýa.

3) Maglumatlaryň modeli (ýerüsti)

Metrikler seriýasy = 'metric _ id' + 'labels {}' + 'timestamp' + 'value' (+ goşmaça 'exemplar {trace _ id =...}').

3. 1 Kategoriýalar

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 Bellikler (berk çäklendirilen)

`region`, `tenant`, `environment`, `service`, `psp`, `bank_group`, `geo`, `device`, `version`, `component`.
Gadagan: 'userId', 'sessionId', kartlaryň/resminamalaryň çig belgileri.

4) Wersiýalaşdyrmak we gabat gelmek

Esasy ýol: '/v1/metrics/... '; gabat gelmeýän üýtgeşmeler - diňe täze 'vX' -de.
Bellikleri/seriýalary goşmak - backward-compatible.
Semantikanyň üýtgemegi - jogapdaky 'schema _ version' meýdançasy we grace-period arkaly.
Shemalaryň katalogy '/v1/schemas 'hökmünde çap edilýär.

5) Endpointler (REST, gRPC/GraphQL meňzeş)

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`.
• Jogap: '{metric, labels {}, points: [[ts, value]], exemplars?}'.

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

Beden: bir batch bilen 50 soraga çenli. Çylşyrymly daşbordlar üçin haýyşlary tygşytlaýar.

3. `GET /v1/metrics/instant`

Häzirki "ts" (ýa-da "indi") süzgüçleri bilen.

4. `GET /v1/metrics/catalog`

Elýeterli metrikleriň sanawy, düşündirişler, bellikler, rugsat berilýän agregasiýalar, SLO-baglanyşyklar.

5. `GET /v1/metrics/health`

API-iň ýagdaýy: latency p95, kesiň şowsuzlyga çydamlylygy, kesiş hitleriniň paýy.

6. `GET /v1/metrics/slo`

Taýýar SLO-view: ýalňyşlyklaryň býudjet çykdajylary (fast/slow), maksatlaryň ýagdaýy.

6) Haýyşlaryň mysallary

6. 1 TR-de PSP boýunça ygtyýarnamalaryň üstünligi, 1-minutlyk 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" sebitler boýunça, bilen exemplars (trace-mysallar):

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

6. 3 EU boýunça goýumlaryň SLO-nyň derrew ýagdaýy:

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

6. 3 soragdan 4 batch (POST/bulk-query) - gatlakly bir sütün üçin.

7) Agregasiýalar we burçlar

P50/p95/p99 pertsentilleri TSDB/agregator derejesinde hasaplanylýar; 'downsample' - dogry kompozisiýa (t-digest/HDR).
'group _ by' diňe kardinallygy partlatmazlyk üçin whitelisted-bellikler arkaly rugsat berilýär.
'step' tassyklanýar: realtime üçin azyndan 10s, köpçülik dashbordlary üçin 1m.

8) Nagt pul, downsampling we täzelik

Köp derejeli keş: in-memory (30-60 s çenli), paýlanan (5 minuta çenli), köpçülik SLO-wyu üçin CDN.
Downsampling: uly penjirelerde awtomat ('> 24h') → 5m/1h nokatlar.
Freshness-заголовки: `X-Data-Freshness: 12s`, `X-Downsample: 1m`, `X-Partial: true|false`.

9) Multi-tenant we izolýasiýa

Her haýyşda 'tenant' bolmaly (bellikde/bellikde).
ABAC/RBAC: rol/syýasat 'tenant, region, environment, metric_id' boýunça elýeterliligi çäklendirýär.
Show/charge-back: başlyklar 'X-Query-Cost-Estimate' we usage-hasaplaýjylar.

10) Tassyklamak we howpsuzlyk

OAuth2 mTLS/hyzmat bellikleri

SoD: kadalaşdyryjy töwekgelçilikleri bolan metriklere girmek (maliýe, RG) - aýratyn rollar.
Rate limits: müşderiniň açary boýunça we 'metric _ id' boýunça.
PII-sanitariýa: serwer gadagan edilen süzgüçleriň/bellikleriň ýoklugyny tassyklaýar.

11) Geo-rezidensiýa we komplayens

Rezidensiýanyň syýasaty boýunça maglumatlar sebitleýin storajlardan (EU/LATAM/APAC) okalýar.
Sebitleýin soraglar - diňe PII bolmadyk agregatlar üçin we "compliance _ scope" bar bolsa.

12) Nusgalar/Exemplars we korrelýasiýa

'exemplars = true' -de percentile nokatlaryna jogap berlende, çalt RCA üçin bir jübüt wekilçilikli 'trace _ id' (PII-siz) salgylanmalar yzyna gaýtarylýar.
Baglanyşyk: 'correlation _ id' jogap meta-maglumatlarynda bar.

13) SLA API we ýalňyşlyklar

Jogap SLA: p95 ≤ 300 ms (keş), ≤ 1. 5 s (sowuk ýol), elýeterlilik ≥ 99. 9%.

• '400' - gaty köp ('group _ by', erbet 'step'),
• '403' - ýeterlik hukuklar/tenant,
• '409' - shemalaryň gapma-garşylygy,
• '429' - kwota/reýt-çäk,
• '502/504' - storajyň pese gaçmagy (sözbaşylarda - downsample/step boýunça teklipler),
• '206' - bölekleýin jogap (çardlaryň bir bölegi elýeterli däl).
• Diagnostikanyň sözbaşylary: 'X-Query-Plan', 'X-Query-Cache', 'X-Query-Shards', 'X-RateLimit-Remaining'.

14) Kwotalar, reýt-çäkler we backpressure

Müşderi üçin 10 rps, jogap üçin 50 seriýa, penjire 3 sagat, 'step ≥ 10c'.
Burst-tokenler: uly ekranda daşbordlar üçin, utgaşdyrylan penjireler.
Backpressure: Serwer 'step '/' downsample' -ni açmagy maslahat berip 'Retry-After' -ni yzyna gaýtaryp biler.

15) SDK we iň gowy tejribeler

SDK: Typescript/Go/Python. Agressiw keş, eksponensial backoff, 'If-None-Match'.

• '/bulk-query 'arkaly soraglary toparlanyň;
• 'group _ by' -den tygşytly peýdalanyň;
• taryhy synlar üçin - 'downsample = 1h';
• 2 s ≤ taým-autlary we 'cancellation' -bellikleri goşuň.

15. 1 Kiçi mysal (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) API metrikleriniň syn edilmegi

SLI самого API: p95_latency, error_rate, cache_hit_ratio, partial_response_rate.
KPI ulanylmagy: rps, jogabyň ortaça mukdary, bahasy boýunça top-metrikler.
Alertler: burn-rate ýalňyşlyklar, '429' köpelýär, cache-hit <nyşana düşýär.
Loglar: gurluşly, PII-siz; 'tenant', 'metric _ id', 'query _ cost _ class'.

17) FinOps-syýasatlar

Soraglaryň synplary: A (realtime daşbordlary), B (operasiýa), C (analitika). Dürli kwotalar/TTL.
Bahasy: $/GB okamak, $/haýyş, $/graf. "Agyr" metrikler we bellikler boýunça aýlyk hasabat.
Optimizasiýa: serwer merge, meşhur SLO-view üçin deslapky agregatlar, müşderä awto-maslahatlar (suggested 'step/downsample').

18) Integrasiýa

Status-sahypa: taýýar SLO-view okaýar.
Alerting: düzgünler '/slo 'we' instant '-a esaslanýar.
Waka-bot: gysga presetleriň üsti bilen grafikleriň/dilimleriň çalt snippetleri.
Workflow/Release-gates: gyzyl SLO-da goýberiş bloky.

19) Durmuşa geçirmegiň ýol kartasy (6-10 hepde)

Ned. 1-2: metrikler katalogy, bellikler whitelists, shemalar '/catalog ', prototip '/query' kese we downsample bilen.
Ned. 3-4: '/bulk-query ', '/slo', exemplars, RBAC/ABAC, kwotalar/reýt-çäkler.
Ned. 5-6: geo-sharding, köpçülige açyk CDN, FinOps-sözbaşylar, dashboard SLI API.
Ned. 7-8: SDK (TS/Go/Py), teklipler/soraglar linteri, kanareýa synaglary.
Ned. 9-10: bulam-bujarlyk (çardlaryň/kesiň ret edilmegi), bahany optimizirlemek, deprekeýt syýasaty.

20) Artefaktlar

Metric Catalog: id, birlikler, düşündirişler, elýeterli 'agg', rugsat berilýän bellikler.
Access Policy: rollar, ýerler, çäkler, SoD.
Query Style Guide: Dogry/nädogry soraglaryň mysallary.
SLO Map: SLI jemgyýetçilik maksatlaryna laýyk gelmek.
Cost Report: iň gymmat haýyşlar/bellikler, optimizasiýa meýilnamasy.

21) KPI/KRI API metrik

p95/99 latency, error rate, partial responses.
Cache hit ratio we CPU/IO tygşytlamak.
Jogap we $/soragyň ortaça ululygy.
'/bulk-query '-e geçen daşbordlaryň paýy.
Ýokary kardinallyk haýyşlary sebäpli hadysalar.

22) Antipatternler

Mugt 'group _ by' onlarça bellik → kardinalizmiň partlamasy.
Müşderä "bukulan" ýüzler → ýoýulmalar.
30-90 günüň arzalary downsample → gymmat we haýal.
Tenantlary/sebitleri ygtyýarnamasyz bir jogapda garyşdyrmak.
Keshsiz köpçülik panelleri/CDN.
'vX' we grace-döwürsiz metrikleriň semantikasynyň üýtgemegi.

Jemi

Operasiýalaryň API metrikleri, telemetriýanyň üstünde okamagyň durnukly, ygtybarly we tygşytly gatlagy: standartlaşdyrylan shemalar we burçlar, nagt we downsampling, berk bellikler we elýeterlilikler, RCA üçin SLO-wiew we exemplars, aç-açan SLA we çykdajylar. Şeýle gatlak gizlinlik, býudjet we öndürijilik üçin töwekgelçiliksiz ygtybarly daşbordlar, alerting, status-aragatnaşyk we geýt relizleri gurmaga mümkinçilik berýär.