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) Ендпоінти (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`

Тіло: до 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 Успіх авторизацій по 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 (трейс-приклади):

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

6. 3 Миттєвий статус SLO депозитів по EU:

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'валідується: мінімум 10с для realtime, 1м для публічних дашбордів.

8) Кеш, downsampling і свіжість

Багаторівневий кеш: in-memory (до 30-60 с), розподілений (до 5 хв), CDN для публічних SLO-в'ю.
Downsampling: автоматом при великих вікнах ('> 24h') → 5м/1ч точки.
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'у відгуку у точок перцентилів повертаються посилання на пару репрезентативних'trace _ id'( без PII) для швидкого RCA.
Кореляція: '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: сервер може повертати «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-метрики за вартістю.
Алерти: burn-rate за помилками, сплеск'429', падіння cache-hit <цільового.
Логи: структуровані, без PII;'tenant','metric _ id','query _ cost _ class'.

17) FinOps-політики

Класи запитів: A (realtime дашборди), B (операційні), C (аналітика). Різні квоти/TTL.
Вартість: $/GB читання, $/запит, $/граф. Щомісячний звіт по «важким» метрикам і лейблам.
Оптимізації: серверний merge, передагрегати для популярних SLO-в'ю, авто-поради клієнту (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, строгі лейбли і доступи, SLO-в'ю і exemplars для RCA, прозорі SLA і вартість. Такий шар дозволяє будувати надійні дашборди, алертинг, статус-комунікації і гейти релізів без ризику для приватності, бюджету і продуктивності.