API metrik əməliyyatlar

1) Təyinat və məsuliyyət sahəsi

• konsistent SLI/SLO (giriş, depozit, dərəcə, çıxarış);
• KRI (erkən risk göstəriciləri: PSP/KYC/növbələr/replikasiyalar);
• biznes metrikası (GEO/PSP/banklar üzrə avtorizasiyaların uğuru, uğurlu dərəcələrin payı, əsas yolların uzunluğunun p95/p99);
• dashboard, alerting, status-səhifə, hesabat üçün təhlükəsiz, ucuz və proqnozlaşdırıla bilən oxu.

2) Memarlıq prinsipləri

Read-heavy, write-few: API yalnız TSDB/cache-dən toplaşmaları oxuyur.
SLO-first: cavablar vaxtında proqnozlaşdırıla bilər; səhvlər və deqradasiya - şəffaf siqnal.
Cost-aware: downsampling, kvotalar, SDK kanarya fiçləri.
Privacy-by-design: metadata/etiketlərdə PII yoxdur; tokenlər, geo-qapı, SoD.
Multi-tenant: marka/region/ətraf mühitə görə izolyasiya.

3) Data modeli (səthi)

Metrik seriya = 'metric _ id' + 'labels {}' + 'timestamp' + 'value' (+ isteğe bağlı 'exemplar {trace _ id =...}').

3. 1 Kateqoriyalar

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 Etiketlər (ciddi şəkildə məhdudlaşdırılmış)

`region`, `tenant`, `environment`, `service`, `psp`, `bank_group`, `geo`, `device`, `version`, `component`.
Qadağandır: 'userId', 'sessionId', xam kart/sənəd nömrələri.

4) Version və uyğunluq

Əsas yol: '/v1/metrics/... '; uyğunsuz dəyişikliklər - yalnız yeni 'vX'.
Etiketlərin/seriyaların əlavə edilməsi - backward-compatible.
Semantikanın dəyişdirilməsi - cavabdakı 'schema _ version' sahəsi və grace-periodu vasitəsilə.
Sxemlər kataloqu '/v1/schemas 'kimi dərc olunur.

5) End nöqtələri (gRPC/GraphQL-də oxşar 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`.
• Cavab: '{metric, labels {}, points: [[ts, value]], exemplars?}'.

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

Bədən: bir batch 50 sorğu qədər. Mürəkkəb daşbordlar üçün sorğulara qənaət edir.

3. `GET /v1/metrics/instant`

'ts' (və ya 'indi') anında cari qiymətlər müəyyən edilmiş filtrlərlə.

4. `GET /v1/metrics/catalog`

Mövcud metrlərin siyahısı, təsvirlər, etiketlər, icazə verilən aqreqasiyalar, SLO bağları.

5. `GET /v1/metrics/health`

API-nin özü: latency p95, cache uğursuzluğu, cache hitlərinin payı.

6. `GET /v1/metrics/slo`

Hazır SLO-view: büdcə xərcləri səhvlər (fast/slow), məqsəd statusu.

6) Sorğu nümunələri

6. 1 TR, 1-min grid, p95 PSP avtorizasiyalarının uğuru:

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» regionlar üzrə, ilə exemplars (trace-nümunələr):

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

6. 3 AB ani SLO depozit statusu:

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

6. 3 sorğudan 4 Batch (POST/bulk-query) - qatlarla bir qrafik üçün.

7) Aqreqasiya və üzlük

P50/p95/p99 qələmləri TSDB/aqreqator səviyyəsində hesablanır; 'downsample' - düzgün kompozisiya ilə (t-digest/HDR).
'group _ by' yalnız kardinallığı partlatmamaq üçün whitelisted etiketləri ilə icazə verilir.
'step' valid: realtime üçün minimum 10s, ictimai dashboard üçün 1m.

8) Cache, downsampling və təravət

Çox səviyyəli cache: in-memory (30-60 saniyəyə qədər), paylanmış (5 dəqiqəyə qədər), ictimai SLO üçün CDN.
Downsampling: böyük pəncərələrdə avtomatik ('> 24h') → 5m/1h nöqtələr.
Freshness-заголовки: `X-Data-Freshness: 12s`, `X-Downsample: 1m`, `X-Partial: true|false`.

9) Multi-tenant və izolyasiya

Hər bir sorğuda 'tenant' (token/etiketlərdə) olmalıdır.
ABAC/RBAC: rol/siyasət 'tenant, region, environment, metric_id'.
Show/charge-back: başlıqlar 'X-Query-Cost-Estimate' və usage-sayğacları.

10) Autentifikasiya və təhlükəsizlik

OAuth2 mTLS/scope limitli xidmət tokenləri.
SoD: mümkün tənzimləyici riskləri olan metriklərə giriş (maliyyə, RG) - fərdi rollar.
Rate limits: müştərinin açarı və 'metric _ id'.
PII-sanitizes: server qadağan olunmuş filtrlərin/etiketlərin olmamasını təsdiqləyir.

11) Geo-yaşayış və komplayens

Məlumat regional storajlardan (EU/LATAM/APAC) yaşayış siyasəti üzrə oxunur.
Cross-regional sorğular - yalnız PII olmayan aqreqatlar üçün və «compliance _ scope» varsa.

12) Nüsxələr/Exemplars və korrelyasiya

'exemplars = true' cavabında persentillərin nöqtələrində tez bir RCA üçün bir neçə reprezentativ 'trace _ id' (PII olmadan) linkləri geri qaytarılır.
Korrelyasiya: 'correlation _ id' cavab metadata mövcuddur.

13) SLA API və səhvlər

SLA cavab: p95 ≤ 300 ms (cache), ≤ 1. 5 s (soyuq yol), mövcudluğu ≥ 99. 9%.

• '400' - qeyri-adi sorğu (çox 'group _ by', pis 'step'),
• '403' - yetərli hüquqlar/tenant,
• '409' - sxemlərin toqquşması,
• '429' - kvota/reyt-limit,
• '502/504' - Storajın deqradasiyası (başlıqlarda - downsample/step üzrə tövsiyələr),
• '206' - qismən cavab (bəzi şardlar mövcud deyil).
• Diaqnostika başlıqları: 'X-Query-Plan', 'X-Query-Cache', 'X-Query-Shards', 'X-RateLimit-Remaining'.

14) Kvotalar, uçuş limitləri və backpressure

Default: müştəri başına 10 rps, cavab üçün 50 seriyası, pəncərə 3 saat, 'step ≥ 10c'.
Burst-tokenlər: böyük ekranda dashboard üçün, razılaşdırılmış pəncərələr.
Backpressure: Server 'Retry-After' qaytara bilər, 'step' artırmağı/' downsample 'daxil etməyi məsləhət görür.

15) SDK və ən yaxşı təcrübələr

SDK: Typescript/Go/Python. Default: aqressiv cache, eksponent backoff, 'If-None-Match'.

• '/bulk-query 'vasitəsilə sorğuları qruplaşdırın;
• istifadə edin 'group _ by' qənaətlə;
• tarixi icmallar üçün - 'downsample = 1h';
• time-auts ≤ 2 s və 'cancellation' -jetonlar əlavə edin.

15. 1 Mini nümunə (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 metrik müşahidə

SLI самого API: p95_latency, error_rate, cache_hit_ratio, partial_response_rate.
KPI istifadə: rps, orta cavab həcmi, dəyəri top-metrik.
Alertlər: burn-rate səhvlər, sıçrayış '429', düşmə cache-hit <hədəf.
Qeydlər: strukturlaşdırılmış, PII-siz; 'tenant', 'metric _ id', 'query _ cost _ class'.

17) FinOps siyasəti

Sorğu sinifləri: A (realtime dashboard), B (əməliyyat), C (analitik). Müxtəlif kvotalar/TTL.
Dəyəri: $/GB oxu, $/sorğu, $/qraf. «Ağır» metriklər və etiketlər üzrə aylıq hesabat.
Optimizasiyalar: server merge, məşhur SLO-view üçün pre-aqreqatlar, avtomatik müştəri məsləhətləri (suggested 'step/downsample').

18) İnteqrasiya

Status-səhifə: hazır SLO-view oxuyur.
Alerting: qaydalar '/slo 'və' instant 'əsaslanır.
Hadisə-bot: qısa presetlər vasitəsilə qrafiklərin/kəsiklərin sürətli snippetləri.
Workflow/Release-gates: qırmızı SLO-da buraxılış bloku.

19) Tətbiqi yol xəritəsi (6-10 həftə)

Ned. 1-2: metrik kataloq, etiket whitelists, sxemlər '/catalog ', prototip '/query' cache və downsample ilə.
Ned. 3-4: '/bulk-query ', '/slo', exemplars, RBAC/ABAC, kvotalar/reyt limitləri.
Ned. 5-6: geo-sharding, ictimai view üçün CDN, FinOps-başlıqlar, SLI API dashboard.
Ned. 7-8: SDK (TS/Go/Py), tövsiyələr/sorğu linter, kanarya testləri.
Ned. 9-10: xaos təlimləri (şard/cache imtina), dəyər optimallaşdırılması, deprekeyt siyasəti.

20) Artefaktlar

Metric Catalog: id, vahidlər, mövcud olan təsvirlər 'agg', icazə verilən etiketlər.
Access Policy: rollar, sahələr, limitlər, SoD.
Query Style Guide: Düzgün/səhv sorğuların nümunələri.
SLO Map: SLI ictimai məqsədlərə uyğunluq.
Cost Report: Ən bahalı sorğular/etiketlər, optimallaşdırma planı.

21) KPI/KRI API metrik

p95/99 latency, error rate, partial responses.
Cache hit ratio və CPU/IO qənaət.
Orta cavab ölçüsü və $/sorğu.
'/bulk-query '-ə keçən daşbordların payı.
Yüksək kardinallıq tələblərinə görə insidentlər.

22) Antipattern

Pulsuz 'group _ by' on işarələri → kardinallıq partlayışı.
Müştərinin üzərində «qatlanmış» → təhriflər.
downsample olmadan 30-90 gün üçün sorğular → bahalı və yavaş.
Tenant/regionların avtorizasiyasız bir cavabda qarışdırılması.
Cache/CDN olmadan açıq panellər.
'vX' və grace-period olmadan metriklərin semantikasının dəyişdirilməsi.

Yekun

API metrik əməliyyatlar sabit, təhlükəsiz və qənaətcil telemetriya üzərində oxu təbəqəsidir: standartlaşdırılmış sxemlər və üzlüklər, cache və downsampling, ciddi etiketlər və accessories, RCA üçün SLO və exemplars, şəffaf SLA və dəyəri. Bu təbəqə etibarlı daşbordlar, alertinq, status-kommunikasiyalar və gizlilik, büdcə və performans üçün risk olmadan gate relizlər qurmağa imkan verir.