Амалиёт Metrics API

1) Мақсад ва соҳаи масъулият

• пайваста SLI/SLO (воридшавӣ, амонат, меъёри бозхонд);
• KRI (нишондиҳандаҳои барвақти хатар: PSP/KYC/навбатҳо/нусхаҳо);
• нишондиҳандаҳои тиҷорат (муваффақияти иҷозатномаҳои GEO/PSP/бонк, ҳиссаи гаравҳои муваффақ, давомнокии роҳи асосии p95/p99);
• хониши бехатар, арзон ва пешгӯишаванда барои панели панелҳо, огоҳкунӣ, саҳифаҳои вазъ, гузоришдиҳӣ.

2) Принсипҳои меъморӣ

Хондан-вазнин, навиштан-кам: API танҳо агрегатҳоро аз TSDB/кэш мехонад.
SLO-аввал: ҷавобҳо бо мурури замон пешгӯӣ карда мешаванд; хатогиҳо ва таназзул - шаффоф ишора карда мешаванд.
Арзиши огоҳӣ: коҳиш додан, квотаҳо, хусусиятҳои канарӣ дар SDK.
Тарроҳии махфият: PII дар метамаълумот/тамғакоғазҳо нест; токенҳо, гео-дарвоза, So-D.
Бисёр иҷорагир: ҷудокунӣ аз рӯи бренд/минтақа/муҳити зист.

3) Модели маълумот (сатҳи)

Силсилаи метрикӣ = 'metric _ id' + 'тамғакоғазҳо {}' + 'timestamp' + 'value' (+ ихтиёрӣ 'намуна {trace _ id =...}').

3. 1 Категорияҳо

SLI/SLO: 'auth _ success _ rate', 'bet _ setle _ p99 _ ms', 'бозпас гирифтани _ tat _ p95 _ ms', 'api _ 5xx _ rate'.
KRI: 'quenue _ consumer _ lag', 'db _ replication _ lag', 'psp _ soft _ redup _ rate _ rate'.
Biznes: 'амонатҳо _ муваффақият _ pct', 'bets _ success _ pct', 'kyc _ pass _ rate'.
Инфра: 'cpu _ util', 'cache _ hit _ таносуб', 'cdn _ waf _ block _ rate'.

3. 2 тамғакоғазҳо (ба таври қатъӣ маҳдуд)

'region', 'иҷорагир', 'муҳит', 'хидмат', 'psp', 'bank _ group', 'geo', 'дастгоҳ', 'версия', 'компонент'.
Манъ карда шудааст: 'корбар', 'сессия', рақами корт/ҳуҷҷати хом.

4) Версия ва мутобиқат

Роҳи асосӣ: '/v1/metrics/... '; дигаргуниҳои номувофиқ - танҳо дар 'VX' -и нав.
Илова кардани тамғакоғазҳо/силсилаҳо - ба қафо мувофиқ.
Тағйироти семантикӣ тавассути майдони 'schema _ version' дар посух ва давраи имтиёзнок аст.
Феҳристи схема ҳамчун '/v1/schemas 'нашр карда мешавад.

5) Нуқтаҳои ниҳоӣ (REST, ки дар g

1. 'GET/v1/metrics/query'

• 'metric' (multi), 'аз', 'ба', 'қадам' (резолюция), 'agg' ('avg'sum'min'max'p50|p95|p99'),
• 'filter [label] = value' (multi), 'group _ by = label1, label2',
• 'downsample=1m|5m|1h', 'намунаҳо = ҳақиқӣ' false ',' limit '(rydov),' саҳифа '.
• Ҷавоб: массиви силсилаи '{metric, тамғакоғазҳо {}, нуқтаҳо: [[ts, value]], намунаҳо?}'.

2. 'POST/v1/metrics/оммавӣ-query'

Бадан: То 50 дархост дар як партия. Захира кардани дархостҳо барои панелҳои мураккаб.

3. 'GET/v1/metrics/фавран'

Қиматҳои ҷорӣ дар 'ts' (ё 'now') бо филтрҳои муайяншуда.

4. 'GET/v1/metrics/каталог'

Рӯйхати ченакҳои мавҷуда, тавсифҳо, тамғакоғазҳо, маҷмӯаҳои иҷозатдодашуда, пайвастагиҳои SLO.

5. 'GET/v1/metrics/health'

Ҳолати худи API: таъхири p95, устувории кэш, ҳиссаи хитҳои кэш.

6. 'GET/v1/metrics/slo'

Назари омодагии SLO: истеъмоли буҷаи хатогӣ (зуд/суст), ҳолати мақсаднок.

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 → ҳал кардан" аз рӯи минтақа, бо намунаҳо (намунаҳои пайгирӣ):

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

6. 3 Ҳолати фаврии пасандози SLO ИА:

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

6. 4 Маҷмӯи 3 дархост (POST/пурсиши оммавӣ) - барои як график бо қабатҳои.

7) Агрегатҳо ва фоизҳо

Фоизҳои p50/p95/p99 дар сатҳи TSDB/агрегатор ҳисоб карда мешаванд; бо 'downsample' - бо таркиби дуруст (t-digest/HDR).
'group _ by' танҳо дар тамғакоғазҳои сафедшуда иҷозат дода шудааст, то кардинализмро пароканда накунанд.
'step' тасдиқ карда шудааст: ҳадди аққал 10s барои вақти воқеӣ, 1м барои панелҳои ҷамъиятӣ.

8) Пули нақд, пастсифат ва тару тоза

Кэши бисёрсатҳавӣ: дар хотира (то 30-60 с), тақсимшуда (то 5 дақ.), CDN барои назари оммавии SLO.
Downsampling: автоматӣ бо тирезаҳои калон ('> 24h') → 5m/1h нуқтаҳо.
Тару тоза-заголовки: 'X-Data-Freshness: 12s', 'X-Downsample: 1m', 'X-Partial: true' false '.

9) Иҷорагир ва ҷудокунӣ

Ҳар як дархост бояд 'иҷорагир' дошта бошад (дар аломат/тамғакоғазҳо).
ABAC/RBAC: нақш/сиёсат дастрасиро аз ҷониби иҷорагир, минтақа, муҳити зист, metric_id' маҳдуд мекунад.
Нишон додан/баргардонидан: 'X-Query-Cost-Estimate' сарлавҳаҳо ва ҳисобкунакҳои истифода.

10) Аутентификатсия ва амният

OAuth2 MTLS/нишонаҳои хидматрасонии миқёс.
Ҳамин тавр: дастрасӣ ба ченакҳо бо хатарҳои имконпазири танзим (молия, RG) - нақшҳои инфиродӣ.
Маҳдудиятҳои меъёрӣ: аз рӯи калиди муштарӣ ва 'metric _ id'.
Санитарияи PII: сервер набудани филтрҳо/тамғакоғазҳои манъшударо тасдиқ мекунад.

11) Истиқомат ва мувофиқат

Маълумот аз анборҳои минтақавӣ (EU/LATAM/APAC) оид ба сиёсати истиқомат хонда мешавад.
Дархостҳои байниминтақавӣ - танҳо барои агрегатҳо бидуни PII ва бо 'compliance _ scope'.

12) Намунаҳо ва таносуб

Бо 'намунаҳо = ҳақиқат', посух дар нуқтаҳои фоизӣ истинодро ба ҷуфти намояндаи 'trace _ id' (бидуни PII) барои RCA зуд бармегардонад.
Таносуб: 'correlation _ id' дар метамаълумоти вокуниш мавҷуд аст.

13) SLA API ва иштибоҳҳо

Ҷавоб SLA: p95 ≤ 300 мс (кэш), ≤ 1. 5 с (роҳи хунук), мавҷудият ≥ 99. 9%.

• '400' - дархости беэътибор (аз ҳад зиёд 'group _ by', бад 'қадам'),
• '403' - ҳуқуқҳои нокифоя/иҷорагир,
• '409' - муноқишаи ноҳиявӣ,
• '429' - маҳдудияти квота/меъёри,
• '502/504' - таназзули нигаҳдорӣ (дар сарлавҳаҳо - тавсияҳо барои коҳиш/қадам),
• '206' ҷавоби қисман аст (баъзе шардҳо дастрас нестанд).
• Сарлавҳаҳои ташхисӣ: 'X-Query-Plan', 'X-Query-Cache', 'X-Query-Shards', 'X-Rate-Limit-Remain'.

14) Квотаҳо, маҳдудиятҳои нархҳо ва бозгашт

Пешфарз: 10 rps ба як муштарӣ, 50 серия барои як посух, 3 соат тиреза, 'қадам ≥ 10c'.
Нишонаҳо: барои панели панелҳо ба экрани калон, тирезаҳои ҳамоҳангшуда.
Backpressure: сервер метавонад 'Retry-After' -ро баргардонад ва маслиҳат медиҳад, ки 'қадам '/enable' downsample 'зиёд карда шавад.

15) SDK ва таҷрибаи пешқадам

SDK: Typescript/Go/Python. Пешфарз: кэши хашмгин, бозгашти экспоненсиалӣ, 'If-None-Match'.

• дархостҳои гурӯҳӣ аз ҷониби '/пурсиши оммавӣ ';
• истифодаи 'group _ by' сарфакорона;
• барои баррасиҳои таърихӣ - 'downsample = 1h';
• танаффусро ≤ 2 сония ва нишонаҳои "бекоркунӣ" илова кунед.

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 samogo API: p95_latency, error_rate, cache_hit_ratio, partial_response_rate.
Истифодаи KPI: rps, ҳаҷми миёнаи посух, ченакҳои арзиши олӣ.
Огоҳиҳо: суръати сӯзондан дар хатогиҳо, хӯшае '429', партофтани кэш-зарба <ҳадаф.
Гузоришҳо: сохташуда, бе PII; 'иҷорагир', 'metric _ id', 'query _ cost _ class'.

17) Сиёсати FIN

Синфҳои дархостӣ: A (панели вақти воқеӣ), B (амалиётӣ), C (таҳлил). Квотаҳои гуногун/TTL.
Арзиш: $/GB мехонад, $/дархост, $/график. Ҳисоботи ҳармоҳа дар бораи ченакҳо ва тамғакоғазҳои "вазнин".
Оптимизатсия: якҷояшавии сервер, агрегатҳои пешакӣ барои SLO-view маъмул, маслиҳатҳои худкор ба муштарӣ (пешниҳодшудаи 'қадам/поён').

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

Саҳифаи вазъ: Андешаҳои омодашудаи SLO-ро мехонад.
Огоҳӣ: қоидаҳо ба '/slo 'ва' фаврӣ 'такя мекунанд.
Ҳодиса-бот: пораҳои тези графикҳо/иловаро тавассути пешнамоишҳои кӯтоҳ.
Ҷараёни корӣ/Дарвозаҳои озодкунӣ: блоки озод дар SLO-ҳои сурх.

19) Харитаи роҳсозӣ (6-10 ҳафта)

Нед. 1-2: каталоги ченакҳо, сафедпӯстон, схемаҳои '/каталог ', прототипи '/дархост' бо кэш ва пастравӣ.
Нед. 3-4: '/пурсиши оммавӣ ', '/slo', намунаҳо, RBAC/ABAC, квотаҳо/меъёрҳо.
Нед. 5-6: geo-sharding, CDN барои тамошои ҷамъиятӣ, сарлавҳаҳои FIN, панели SLI API.
Нед. 7-8: SDK (TS/Go/Py), тавсияҳо/линтерҳои дархостӣ, санҷишҳои канарӣ.
Нед. 9-10: таълимоти бетартибӣ (нокомии shard/кэш), оптимизатсияи арзиш, сиёсати беқурбшавӣ.

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

Каталоги метрӣ: id, воҳидҳо, тавсифҳо, 'agg', тамғакоғазҳои дуруст.
Сиёсати дастрасӣ: нақшҳо, минтақаҳо, маҳдудиятҳо, So-D.
Дастури услуби дархост - намунаҳои дархостҳои дуруст/нодуруст.
Харитаи SLO: риояи SLI ↔ ҳадафҳои ҷамъиятӣ.
Ҳисоботи хароҷот: дархостҳо/барчаспҳои гаронбаҳо, нақшаи оптимизатсия.

21) Метрикаҳои KPI/KRI API

p95/99 таъхир, сатҳи хатогӣ, посухҳои қисман.
Таносуби зарбаи кэш ва пасандозҳои CPU/IO.
Андозаи миёнаи посух ва $/дархост.
Таносуби панелҳои панелӣ, ки ба '/пурсиш 'гузаштанд.
Ҳодисаҳо бо сабаби дархостҳои баланди кардиналӣ.

22) Антипаттернҳо

'Group _ by' -и ройгон бо даҳҳо аломатҳо → таркиши кардинализм.
Фоизҳо ба муштарӣ § таҳриф карда мешаванд.
Дархостҳо барои 30-90 рӯз бидуни коҳиш § гарон ва суст.
Омезиши иҷорагирон/минтақаҳо дар як посух бидуни иҷозат.
Панелҳои ҷамъиятӣ бе кэш/CDN.
Тағир додани семантикаи ченакҳо бидуни 'v' ва давраи имтиёзнок.

Ҷамъ

Нишондиҳандаҳои амалиётӣ API як қабати хониши устувор, бехатар ва камхарҷ аз болои телеметрия мебошанд: схемаҳои стандартикунонидашуда ва фоизҳо, кэш ва пастшавӣ, тамғакоғазҳо ва дастрасии қатъӣ, намуди SLO ва намунаҳо барои RCA, SLA шаффоф ва арзиш. Ин қабат ба шумо имкон медиҳад, ки панелҳои боэътимод, огоҳиҳо, иртиботи вазъ ва дарвозаҳои озодро бидуни хатари махфият, буҷа ва фаъолият эҷод кунед.