API metrik operatsiyalar

1) Javobgarlikni tayinlash va uning doirasi

• konsistent SLI/SLO (login, depozit, stavka, chiqarib tashlash);
• KRI (tavakkalchilikning erta indikatorlari: PSP/KYC/navbatlar/replikatsiyalar);
• biznes-metrika (GEO/PSP/banklar bo’yicha avtorizatsiyalarning muvaffaqiyati, muvaffaqiyatli stavkalar ulushi, asosiy yo’llarning davomiyligi p95/p99);
• dashbordlar, alerting, status-sahifalar, hisobotlar uchun xavfsiz, arzon va oldindan aytib bo’ladigan o’qishlar.

2) Arxitektura prinsiplari

Read-heavy, write-few: API faqat TSDB/kesh agregatsiyalarini o’qiydi.
SLO-first: javoblar vaqt bo’yicha oldindan aytib bo’ladi; xatolar va tanazzullar - shaffof signalizatsiya qilinadi.
Cost-aware: downsampling, kvotalar, SDKda kanareya chichlari.
Privacy-by-design: meta maʼlumotlar/yorliqlarda hech qanday PII mavjud emas; tokenlar, geo-geyt, SoD.
Multi-tenant: brend/hudud/atrof-muhit bo’yicha izolyatsiya.

3) Ma’lumotlar modeli (sirt)

Metriklar seriyasi =’metric _ id’+’labels {}’+’timestamp’+’value’(+ ixtiyoriy’exemplar {trace _ id =...}’).

3. 1 toifalar

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 Yorliqlar (qat’iy cheklangan)

`region`, `tenant`, `environment`, `service`, `psp`, `bank_group`, `geo`, `device`, `version`, `component`.
Taqiqlangan:’userId’,’sessionId’, xom xarita/hujjat raqamlari.

4) Versiyalash va muvofiqlik

Asosiy yo’l: ’/v1/metrics/...’; mos kelmaydigan o’zgarishlar - faqat yangi’vX’da.
Yorliqlar/seriyalar qoʻshish - backward-compatible.
Semantikani oʻzgartirish - javobdagi’schema _ version’maydoni va grace-davri orqali.
Sxemalar katalogi ’/v1/schemas’sifatida e’lon qilinadi.

5) Endpointlar (gRPC/GraphQL ga o’xshash REST)

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

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

Tanasi: bitta batch bilan 50 so’rovgacha. Murakkab dashbordlar uchun so’rovlarni tejaydi.

3. `GET /v1/metrics/instant`

Joriy «ts» (yoki «hozir») koʻrsatilgan filtrlar bilan.

4. `GET /v1/metrics/catalog`

Mavjud metriklar ro’yxati, tavsiflar, yorliqlar, ruxsat etilgan agregatsiyalar, SLO-bog’lamalar.

5. `GET /v1/metrics/health`

API holati: latency p95, keshning ishlamay qolishi, kesh xit ulushi.

6. `GET /v1/metrics/slo`

Tayyor SLO-vyu: xatolar byudjeti sarfi (fast/slow), maqsad maqomi.

6) So’rovlar namunalari

6. 1 TRda PSP bo’yicha avtorizatsiyalarning muvaffaqiyati, 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» mintaqalar bo’yicha, exemplars bilan (treys-misollar):

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

6. 3 EU bo’yicha SLO depozitlarining tezkor maqomi:

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

6. 3 so’rovdan 4 batch (POST/bulk-query) - qatlamli bitta grafa uchun.

7) Agregatsiyalar va pertsentillar

p50/p95/p99 pertsentillari TSDB/agregator darajasida hisoblab chiqariladi; ’downsample’ da - to’g "ri kompozitsiyali (t-digest/HDR).
’group _ by’ faqat kardinallikni buzmaslik uchun whitelisted-yorliqlar orqali ruxsat berilgan.
’step’ validatsiya qilinadi: realtime uchun kamida 10s, ommaviy dashbordlar uchun 1m.

8) Kesh, downsampling va yangilik

Ko’p darajali kesh: in-memory (30-60 s gacha), taqsimlangan (5 minutgacha), ommaviy SLO-vyu uchun CDN.
Downsampling: katta oynalarda avtomat (’> 24h’) → 5m/1s nuqtalar.
Freshness-заголовки: `X-Data-Freshness: 12s`, `X-Downsample: 1m`, `X-Partial: true|false`.

9) Multi-tenant va izolyatsiya

Har bir soʻrovda «tenant» (token/yorliqlarda) boʻlishi kerak.
ABAC/RBAC: rol/siyosat’tenant, region, environment, metric_id'’ga kirishni cheklaydi.
Show/charge-back:’X-Query-Cost-Estimate’sarlavhalari va usage-hisoblagichlar.

10) Autentifikatsiya va xavfsizlik

OAuth2 mTLS/scope cheklangan servis tokenlari.
SoD: tartibga solish xavfi bo’lgan metriklardan foydalanish imkoniyati (moliya, RG) - alohida rollar.
Rate limits: mijoz kaliti va’metric _ id’.
PII-sanitariya: server taqiqlangan filtrlar/yorliqlar yo’qligini tasdiqlaydi.

11) Geo-rezidensiya va komplayens

Ma’lumotlar rezidentlik siyosati bo’yicha mintaqaviy storajlardan (EU/LATAM/APAC) o’qiladi.
Kros-mintaqaviy so’rovlar - faqat PIIsiz agregatlar uchun va’compliance _ scope’mavjud bo’lganda.

12) Nusxalar/Exemplars va korrelyatsiya

Agar’exemplars = true’javob bersa, tezkor RCA uchun bir juft reprezentativ’trace _ id’ga (PIIsiz) havolalar qaytariladi.
Korrelyatsiya:’correlation _ id’javob meta-ma’lumotlarida mavjud.

13) SLA API va xatolar

Javob SLA: p95 ≤ 300 ms (kesh), ≤ 1. 5 s (sovuq yo’l), foydalanish imkoniyati ≥ 99. 9%.

• ’400’ - noto’g’ri so’rov (juda ko’p’group _ by’, yomon’step’),
• ’403’ - yetarli huquqlar/tenant,
• ’409’ - sxemalar to’qnashuvi,
• ’429’ - kvota/reyt-limit,
• ’502/504’ - storajning degradatsiyasi (sarlavhalarda - downsample/step bo’yicha tavsiyalar),
• ’206’ - qisman javob (shardlarning bir qismi mavjud emas).
• Diagnostika sarlavhalari:’X-Query-Plan’,’X-Query-Cache’,’X-Query-Shards’,’X-RateLimit-Remaining’.

14) Kvotalar, reyt-limitlar va backpressure

Andoza: mijoz uchun 10 rps, javob uchun 50 seriya, 3 soat,’step ≥ 10c’.
Burst-tokenlar: dashbordlar uchun katta ekran, kelishilgan oynalar.
Backpressure: server’Retry-After’ni’step ’/’ downsample’ni kengaytirishni maslahat berib qaytarishi mumkin.

15) SDK va eng yaxshi amaliyotlar

SDK: Typescript/Go/Python. Andoza: tajovuzkor kesh, eksponensial backoff,’If-None-Match’.

• ’/bulk-query’orqali soʻrovlarni guruhlang;
• ’group _ by’ dan tejamkorlik bilan foydalaning;
• tarixiy sharhlar uchun -’downsample = 1h’;
• 2 s ≤ taym-autlarni va’cancellation’-tokenlarni qo’shing.

15. 1 Mini-misol (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 kuzatilishi metrik

SLI самого API: p95_latency, error_rate, cache_hit_ratio, partial_response_rate.
KPI foydalanish: rps, javobning o’rtacha hajmi, qiymati bo’yicha top-metriklar.
Alertlar: burn-rate xato bo’yicha,’429’ko’tarilishi, cache-hit <maqsadli tushishi.
Loglar: strukturalangan, PIIsiz;’tenant’,’metric _ id’,’query _ cost _ class’.

17) FinOps siyosati

So’rovlar klasslari: A (realtime dashbordlar), B (operatsion), C (tahlillar). Turli kvotalar/TTL.
Qiymati: $/GB o’qish, $/so’rov, $/grafa. «Og’ir» metriklar va leybllar bo’yicha har oylik hisobot.
Optimallashtirish: server merge, mashhur SLO-vyu uchun pre-agregatlar, mijozga avto-maslahatlar (suggested’step/downsample’).

18) Integratsiya

Status-sahifa: tayyor SLO-vyu oʻqiydi.
Alerting: qoidalar ’/slo’va’instant’ga asoslanadi.
Hodisa-bot: qisqa presetalar orqali jadvallar/kesimlarning tezkor snippetlari.
Workflow/Release-gates: qizil SLOlarda relizlar bloki.

19) Joriy etish yo’l xaritasi (6-10 hafta)

Ned. 1-2: metriklar katalogi, whitelists leybllar, sxemalar ’/catalog’, prototip ’/query’bilan kesh va downsample.
Ned. 3-4: ’/bulk-query’, ’/slo’, exemplars, RBAC/ABAC, kvotalar/reyt-limitlar.
Ned. 5-6: geo-sharding, ommaviy vyu uchun CDN, FinOps-sarlavhalar, SLI API dashbord.
Ned. 7-8: SDK (TS/Go/Py), tavsiyalar/so’rovlar linteri, kanareya testlari.
Ned. 9-10: xaos-mashqlar (shardlar/keshlarni rad etish), qiymatni optimallashtirish, deprekeytlar siyosati.

20) Artefaktlar

Metric Catalog: id, birliklar, tavsiflar, mavjud’agg’, ruxsat etilgan yorliqlar.
Access Policy: rollar, sohalar, limitlar, SoD.
Query Style Guide: Toʻgʻri/notoʻgʻri soʻrovlar misollari.
SLO Map: SLI ning ommaviy maqsadlarga muvofiqligi.
Cost Report: eng qimmat so’rovlar/belgilar, optimallashtirish rejasi.

21) KPI/KRI API metrik

p95/99 latency, error rate, partial responses.
Cache hit ratio va CPU/IO tejash.
Javobning oʻrtacha hajmi va $/soʻrov.
’/bulk-query’ga o’tgan dashbordlar ulushi.
Yuqori darajadagi talablar tufayli sodir bo’lgan hodisalar.

22) Antipatternlar

O’nlab belgilar bo’yicha erkin’group _ by’→ kardinallik portlashi.
Parsentili, mijozga «buklangan» → buzilishlar.
30-90 kunlik so’rovlar downsample → qimmat va sekin.
Tanantlar/hududlarni avtorizatsiyasiz bitta javobda aralashtirish.
Keshsiz ochiq panellar/CDN.
’vX’ va grace-davrsiz metrikalarning semantikasini oʻzgartirish.

Jami

API metrik operatsiyalar - bu telemetriya ustida o’qishning barqaror, xavfsiz va tejamkor qatlami: standartlashtirilgan sxemalar va pertsentillar, kesh va downsampling, qattiq yorliqlar va kirish joylari, SLO-vyu va RCA uchun exemplars, shaffof SLA va qiymati. Bunday qatlam ishonchli dashbordlar, alerting, status-kommunikatsiyalar va shaxsiy, byudjet va unumdorlik uchun xavfsiz relizlar yaratishga imkon beradi.