API метрикалык иш

1) Дайындоо жана жоопкерчилик зонасы

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

2) Архитектуралык принциптер

Read-heavy, write-few: API гана TSDB/кэш топтоо окуп жатат.
SLO-биринчи: жооптор убакыт боюнча алдын ала айтууга болот; каталар жана деградациялар - ачык-айкын сигнал берилет.
Cost-aware: downsampling, квота, SDK канареялык чүчүкулак.
Privacy-by-design: эч кандай PII мета маалымат/этикеткалар; токендер, гео-Gates, 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' талаасы жана грейс-мезгил аркылуу.
Схемалар каталогу '/v1/schemas 'деп жарыяланат.

5) EndPoint (REST, gRPC/GraphQL окшош)

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`

Body: 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-view: бюджеттин чыгашасы каталар (fast/slow), максаттардын статусу.

6) өтүнүч мисалдар

6. 1 PSP боюнча авторизациялардын ийгилиги TR, 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 (Trace-мисалдар):

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. 4 батч 3 суроолор (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, аймак, environment, metric_id'.
Show/charge-back: 'X-Query-Cost-Estimate' аталыштары жана колдонмо эсептегичтери.

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

OAuth2 mTLS/scope чеги менен тейлөө токендер.
SoD: мүмкүн болгон жөнгө салуучу тобокелдиктери бар метриктерге жетүү (финансы, RG) - өзүнчө ролдор.
Rate limits: кардардын ачкычы жана 'metric _ id' боюнча.
PII-санитайзер: сервер тыюу салынган чыпкалар/этикеткалардын жоктугун тастыктайт.

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

Маалыматтар аймактык storaja (EU/LATAM/APAC) жашаган саясаты боюнча окулат.
Cross-аймактык суроолор - PII жок агрегаттар үчүн жана 'compliance _ scope' бар болсо гана.

12) Нускалары/Exemplars жана корреляция

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

13) SLA API жана каталар

SLA жооп: p95 ≤ 300 ms (кэш), ≤ 1. 5 с (муздак жол), жеткиликтүүлүгү ≥ 99. 9%.

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

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

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

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-метрика.
Alerty: burn-rate каталар боюнча, '429', күзүндө cache-hit <максаттуу.
Логи: структураланган, PII жок; 'tenant', 'metric _ id', 'query _ cost _ class'.

17) FinOps саясаты

Суроо класстары: A (realtime dashboard), B (операциялык), C (аналитика). Ар кандай квоталар/TTL.
Баасы: $/GB окуу, $/суроо-талап, $/тилкеси. "Оор" метриктер жана лейблдер боюнча айлык отчет.
Optimization: Server merge, популярдуу SLO-view үчүн pre-агрегаттар, кардар auto-насаат (suggested 'step/downsample').

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

Статус-бет: даяр SLO-view окуйт.
Alerting: эрежелер '/slo 'жана' instant 'таянат.
Окуя-бот: кыска Presets аркылуу тез Snippet диаграммалар/кесип.
Workflow/Release-gates: кызыл SLO менен бошотуу блогу.

19) Жол картасы киргизүү (6-10 жума)

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

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

Metric Catalog: id, бирдиктер, сүрөттөмөлөр, жеткиликтүү 'agg', алгылыктуу этикеткалар.
Access Policy: ролдору, аймактар, лимиттер, SoD.
Query Style Guide: туура/туура эмес суроо мисалдар.
SLO карта: шайкештиги SLI, коомдук максаттар.
Cost Report: жогорку кымбат суроо-талаптар/белгилер, оптималдаштыруу планы.

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

p95/99 latency, error rate, partial responses.
Cache hit ratio жана CPU/IO үнөмдөө.
Орточо жооп жана $/суроо.
'/bulk-query 'ге өткөн дашборддордун үлүшү.
Жогорку кардиналдык суроо-талаптардан улам окуялар.

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

Free 'group _ by' боюнча ондогон белгилер → кардиналдык жарылуу.
кардар → бурмалоо боюнча "бүктөлгөн".
Суроо-талап 30-90 күн downsample → кымбат жана жай.
Тенанттарды/региондорду авторизациясыз бир жоопто аралаштыруу.
Кэшсиз коомдук панелдер/CDN.
'vX' жана grace-мезгили жок метриктердин семантикасын өзгөртүү.

Жыйынтык

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