Операциялардың API өлшемдері

1) Мақсаты және жауапкершілік аймағы

• консистенттік SLI/SLO (логин, депозит, мөлшерлеме, шығару);
• KRI (тәуекелдің бастапқы индикаторлары: PSP/KYC/кезек/репликация);
• бизнес-метрика (GEO/PSP/банктер бойынша авторизациялаудың табысы, табысты ставкалардың үлесі, негізгі жолдардың ұзақтығы p95/p99);
• дашбордтар, алертинг, статус-беттер, есептілік үшін қауіпсіз, арзан және болжамды оқулар.

2) Сәулет қағидаттары

Read-heavy, write-few: API тек TSDB/кэштен агрегацияларды оқиды.
SLO-first: жауаптар уақыт бойынша болжамды; қателер мен азып-тозулар - ашық белгі беріледі.
Cost-aware: downsampling, квоталар, SDK-дағы канарейка фичтері.
Privacy-by-design: метадеректерде/лейблдерде PII жоқ; токендер, гео-гейт, SoD.
Multi-tenant: бренд/өңір/қоршаған орта бойынша оқшаулау.

3) Деректер моделі (үстіңгі)

Метриктер сериясы = 'metric _ id' + 'labels {}' + 'timestamp' + 'value' (+ қосымша 'exemplar {trace _ id =...}').

3. 1 Санаттар

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 Лейблдер (қатаң шектелген)

`region`, `tenant`, `environment`, `service`, `psp`, `bank_group`, `geo`, `device`, `version`, `component`.
Тыйым салынған: 'userId', 'sessionId', шикі карта/құжат нөмірлері.

4) Нұсқалау және үйлесімділік

Негізгі жол: '/v1/metrics/... '; сыйыспайтын өзгерістер - тек жаңа 'vX'.
backward-compatible.
Семантиканы өзгерту - жауаптағы 'schema _ version' өрісі және grace-кезеңі арқылы.
Схемалар каталогы '/v1/schemas 'деп жарияланады.

5) Эндпоинттер (gRPC/GraphQL ұқсас 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`.
• Жауап: қатарлар жиыны '{metric, labels {}, points: [[ts, value]], exemplars?}'.

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

Дене: бір батпен 50 сұрауға дейін. Күрделі дашбордтар үшін сұрауларды үнемдейді.

3. `GET /v1/metrics/instant`

Берілген сүзгілермен 'ts' (немесе 'қазір') сәтіндегі ағымдағы мәндер.

4. `GET /v1/metrics/catalog`

Қол жетімді метриктер тізбесі, сипаттамалар, лейблдер, рұқсат етілген агрегациялар, SLO-байланыстар.

5. `GET /v1/metrics/health`

API-ның өзі: latency p95, кэштің істен шығуға төзімділігі, кэш-хит үлесі.

6. `GET /v1/metrics/slo`

Дайын SLO: бюджет шығыны қателер (fast/slow), мақсаттар мәртебесі.

6) Сұрау үлгілері

6. 1 TR PSP бойынша авторизациялаудың табысы, 1-мин грид, 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» өңірлер бойынша, exemplars (трейс-мысалдар):

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

6. 3 EU бойынша SLO депозиттерінің жедел мәртебесі:

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

6. 3 сұраудан 4 батч (POST/bulk-query) - қабаттары бар бір баған үшін.

7) Агрегациялар және перцентильдер

p50/p95/p99 перцентильдері TSDB/агрегатор деңгейінде есептеледі; 'downsample' кезінде - дұрыс композициямен (t-digest/HDR).
'group _ by' тек whitelisted-лейблдер арқылы рұқсат етілген.
'step' валидацияланады: realtime үшін ең аз 10с, көпшілік дашбордтар үшін 1м.

8) Кэш, downsampling және жаңалық

Көп деңгейлі кэш: in-memory (30-60 с дейін), таратылған (5 минутқа дейін), көпшілік SLO-вю үшін CDN.
Downsampling: үлкен терезелерде автоматты ('> 24h') → 5m/1h нүктесі.
Freshness-заголовки: `X-Data-Freshness: 12s`, `X-Downsample: 1m`, `X-Partial: true|false`.

9) Мульти-тенант және оқшаулау

Әрбір сұрауда 'tenant' (белгіде/лейблдерде) болуы тиіс.
ABAC/RBAC: рөлі/саясаты 'tenant, region, environment, metric_id' бойынша қолжетімділікті шектейді.
Show/charge-back: 'X-Query-Cost-Estimate' және usage-есептеуіштер тақырыптары.

10) Аутентификация және қауіпсіздік

OAuth2 mTLS/scope бойынша шектелген сервистік токендер.
SoD: ықтимал реттеуші тәуекелдері бар метриктерге қолжетімділік (қаржы, RG) - жеке рөлдер.
Rate limits: клиент кілті бойынша және 'metric _ id' бойынша.
PII-санитайз: сервер тыйым салынған сүзгілердің/лейблдердің жоқтығын валидациялайды.

11) Гео-резиденция және комплаенс

Деректер резиденттік саясаты бойынша өңірлік сторадждерден (EU/LATAM/APAC) оқылады.
Кросс-өңірлік сұраулар - тек PII жоқ агрегаттар үшін және 'compliance _ scope' бар болса.

12) Даналар/Exemplars және корреляция

'exemplars = true' кезінде перцентильдер нүктелерінде жылдам RCA үшін репрезентативті 'trace _ id' (PII) жұбына сілтемелер қайтарылады.
Корреляция: 'correlation _ id' жауап метадеректерінде қол жетімді.

13) SLA API және қателер

Жауап SLA: p95 ≤ 300 мс (кэш), ≤ 1. 5 с (суық жол), қол жетімділік ≥ 99. 9%.

• '400' - әлсіз сұрау (тым көп 'group _ by', жаман 'step'),
• '403' - құқықтар/теңгерім жеткіліксіз,
• '409' - схемалар қақтығысы,
• '429' - квота/рейт-лимит,
• '502/504' - сторадждің тозуы (тақырыптарда - downsample/step бойынша ұсынымдар),
• '206' - ішінара жауап (шардтардың бір бөлігі қол жетімді емес).
• Диагностика тақырыптары: 'X-Query-Plan', 'X-Query-Cache', 'X-Query-Shards', 'X-RateLimit-Remaining'.

14) Квоталар, рейс-лимиттер және backpressure

Әдепкі: клиентке 10 rps, 50 жауап сериясы, терезе 3 сағат, 'step ≥ 10c'.
Burst-токендер: үлкен экранға дашбордтар үшін, келісілген терезелер.
Backpressure: сервер 'step '/' downsample' қосу туралы кеңес бере отырып, 'Retry-After' қайтара алады.

15) SDK және үздік тәжірибелер

SDK: Typescript/Go/Python. Әдепкі: агрессивті кэш, экспоненциалды backoff, 'If-None-Match'.

• сұрауларды '/bulk-query 'арқылы топтаңыз;
• 'group _ by' үнемді пайдаланыңыз;
• тарихи шолулар үшін - 'downsample = 1h';
• 2 с ≤ тайм-ауттарды және 'cancellation' -токендерді қосыңыз.

15. 1 Шағын мысал (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 метриктерінің бақылануы

SLI самого API: p95_latency, error_rate, cache_hit_ratio, partial_response_rate.
KPI пайдалану: rps, орташа жауап көлемі, құны бойынша top-метриктер.
Алерттар: burn-rate қателер бойынша, '429' өрісі, cache-hit <мақсатты құлау.
Логтар: PII-сыз құрылымдалған; 'tenant', 'metric _ id', 'query _ cost _ class'.

17) FinOps-саясаты

Сұрау кластары: A (realtime дашбордтар), B (операциялық), C (талдау). Әртүрлі квоталар/TTL.
Құны: $/GB оқу, $/сұрау, $/бағандар. «Ауыр» метриктер мен лейблдер бойынша ай сайынғы есеп.
Оңтайландыру: сервер merge, танымал SLO-view үшін алдын ала агрегаттар, клиентке авто кеңестер (suggested 'step/downsample').

18) Интеграция

Статус-бет: дайын SLO-вью оқиды.
Алертинг: ережелер '/slo 'және' instant '-ке сүйенеді.
Инцидент-бот: қысқа пресеттер арқылы графиктердің/кесінділердің жылдам сниппеттері.
Workflow/Release-gates: қызыл SLO кезіндегі релиздер блогы.

19) Енгізу жол картасы (6-10 апта)

Нед. 1-2: метриктер каталогы, whitelists лейблдер, схемалар '/catalog ', прототип '/query' кэшімен және downsample.
Нед. 3-4: '/bulk-query ', '/slo', exemplars, RBAC/ABAC, квоталар/рейт-лимиттер.
Нед. 5-6: гео-шардинг, көпшілікке арналған CDN, FinOps-тақырыптар, дашборд SLI API.
Нед. 7-8: SDK (TS/Go/Py), ұсыныстар/сұраулар линтері, канареялық тесттер.
Нед. 9-10: хаос-оқу-жаттығулар (шард/кэштен бас тарту), құнды оңтайландыру, депрекейт саясаты.

20) Артефактілер

Metric Catalog: id, бірліктер, сипаттамалар, қол жетімді 'agg', жарамды лейблдер.
Access Policy: рөлдер, аумақтар, лимиттер, SoD.
Query Style Guide: дұрыс/дұрыс емес сұраулардың мысалдары.
SLO Map: SLI жария мақсаттарға сәйкестігі.
Cost Report: ең қымбат сұраныстар/белгілер, оңтайландыру жоспары.

21) KPI/KRI API метрик

p95/99 latency, error rate, partial responses.
Cache hit ratio және CPU/IO үнемдеу.
Жауаптың орташа мөлшері және $/сұрау.

'/bulk-query '-ге көшкен дашбордтардың үлесі

Жоғары түбегейлі сұраныстарға байланысты оқыс оқиғалар.

22) Антипаттерндер

Еркін 'group _ by' ондаған таңба бойынша → түбегейлі жарылыс.
Клиентке «бүктелген» бұрмалаулар.
30-90 күндік сұраулар downsample → қымбат және баяу.
Авторландырусыз бір жауапта тенанттарды/өңірлерді араластыру.
Кэшсіз ашық тақталар/CDN.
'vX' және grace-кезеңсіз метриктердің семантикасын өзгерту.

Жиынтығы

API метрикалық операциялар - бұл телеметрия үстіндегі тұрақты, қауіпсіз және үнемді оқу қабаты: стандартты схемалар мен перценттер, кэш және downsampling, қатаң лейблдер мен қолжетімділік, RCA үшін SLO және exemplars, мөлдір SLA және құны. Мұндай қабат сенімді дашбордтар, алертинг, статус-коммуникация және релиздер гейттерін жекешелікке, бюджетке және өнімділікке қауіп төндірмей салуға мүмкіндік береді.