API аналітика і метрики продуктивності

1) Навіщо це потрібно

• довести виконання SLO і SLA,
• керувати пропускною спроможністю та економікою запитів,
• швидко локалізувати деградації (p99-хвости, сплески 5xx),
• приоритизувати оптимізації за впливом на бізнес.

Мета: єдина модель спостережуваності, де кожен запит відстежується від периметра до БД із загальними ідентифікаторами та узгодженими SLI.

2) Таксономія метрик

Технічні: RPS, латентність (p50/p95/p99), error rate (4xx/5xx), saturation (CPU, memory, file-desc), queue time.
Продуктові: успішні операції/хв, конверсія кроку (200/total), частка rate-limited (429), ретраї, призначені для користувача сегменти.
Вартість: cost/request (CPU-ms + egress + БД-запити), вартість фічі/ендпоінта, $/тенант, $/1k викликів.

3) «Золоті сигнали»: RED и USE

• Rate - запити/сек (за ендпоінтом/тенантом/планом).
• Errors - 4xx/5xx/429 частки і абсолютні.
• Duration - p50/p95/p99 end-to-end і по стадіях (ingress → app → DB → сторонні).

• Utilization - завантаження CPU/IO/каналу.
• Saturation - черги (run-queue, backlog, DB wait).
• Errors - помилки драйверів/таймаути.

4) Базові визначення та формули

Availability SLI: `1 − (5xx + gateway_timeout) / all_requests`.
Success SLI: '2xx/( all − 429_shadow)'( виключаючи «тіньові» блокування).
Apdex: `(|T≤T| + 0. 5·|T≤4T| )/all', де'T'- цільовий «хороший» поріг.
Tail amplification: 'p99 _ total − max (p99_stage_i)'- внесок черг/композиції.
Error budget (місяць) при 99. 9%: 'бюджет = 0. 1% час _ періоду'.

Рекомендовані перцентильні бини гістограм latency: `[5ms, 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s, 2. 5s, 5s]`.

5) SLI/SLO і алертинг по burn-rate

• Доступність: ≥ 99. 9 %/30 днів.
• p95 латентності'GET/wallet/balance'< 150 мс;'POST/payments'< 400 мс.
• Помилки'5xx'< 0. 2%.'429'( тверді) <1% від загального трафіку.

• 2% бюджету за 1 годину або 5% за 6 годин → page інженеру.
• 10% за добу → пріоритизація RCA.

6) Набір метрик (що збирати обов'язково)

• `http_requests_total{route,method,status,tenant,plan}`
• 'http _ request _ duration _ seconds _ bucket {route,...}'( гістограма)
• `retries_total{reason}`, `rate_limited_total{key,policy}`
• Розміри тіла: `request_bytes`, `response_bytes`

• `db_client_requests_total{op,table}`, `db_latency_seconds_bucket{op}`
• 'cache _ ops _ total {op}', hit-rate кеша зовнішні виклики: 'outbound _ calls _ total {provider, op}', latency/помилки/таймаути черги/пули: довжини/затримки, активні воркери ресурсні USE: CPU, RSS, FD, GC-паузи

Бізнес-лейбли: `tenant_id`, `region`, `kyc_level`, `plan`, `feature_flag`.

7) Трасування та кореляція (OpenTelemetry)

W3C Trace-Context («traceparent», «tracestate») на всіх хопах.
Span-и за стадіями: ingress → authZ → app handler → DB/Redis → PSP/зовнішні.
Attributes/лейбли: `http. route`, `enduser. id`, `tenant. id`, `idempotency. key`, `risk. score`.
Exemplars: зв'язуйте точки на графіках latency/error з конкретними trace-id.

• head-based 1-10% для «звичайних» шляхів,
• tail-based для хвостів (беремо повільні/помилкові),
• adaptive для піків та інцидентів.
• Baggage: перенесення'tenant '/' risk'для розрізів без розмітки кожної події.

8) Логи: структура та приватність

Структурований JSON; обов'язкові поля: `ts`, `trace_id`, `span_id`, `route`, `status`, `latency_ms`, `tenant`, `user_id_hash`.
Політика PII: маскуйте PAN/PII; забороняйте секрети/токени.
Семплінг логів: високий для 4xx/5xx/429 і «довгих» запитів.

9) Карта дашбордів (мінімальний набір)

1. Exec-Summary: RPS, Availability, Error-rate, p95/p99 latency, 429 частка, burn-rate бюджету.
2. Per-Route: топ-ендоінти по RPS/помилкам/хвостам; порівняння версій (канареєчка).
3. Per-Tenant/Plan: лідери по навантаженню/вартості/помилкам.
4. Dependency Health: DB, cache, PSP/зовнішні - latency, помилки, saturation.
5. Capacity: CPU/RAM/FD, черги, connection pool, GC, ліміти контейнерів.
6. Security/Abuse: 401/403, 429/політики, гео/ASN зрізи, сплески ретраїв.

10) Алерти (порогові та трендові)

'error _ rate {route}'> 2% (5 хвилин) і RPS> N → пагер.
'p99 _ latency {critical}'> цільового порогу (10 хвилин).
'burn _ rate'по бюджету (див. § 5).
DB'timeouts '/' deadlocks'або зростання'queue _ time'> X мс.
Зовнішні провайдери: 'outbound _ 5xx _ rate {provider}'> 1% + SLO-залежні.

11) Ємнісне планування і продуктивність

Закон Літтла: 'L = λ· W'( середня довжина черги = трафік × середній час).
Цільове p95 розкладаємо: `ingress + app + DB + external + queue`.
Concurrency budget: фіксуємо максимум одночасних write-операцій.
Budget-метрика: «мс CPU на запит»; тримаємо запас 30-50% до піку.
Взаємодія з rate-limit: вимірюйте частку запитів у «стелі» квоти і вплив на латентність.

12) Навантажувальні та синтетичні перевірки

Види: базове навантаження, бурсти × 10, «ступені», довготривалі плато, стрес/chaos (вбивство нод, затримки мережі), синтетика за критичними клієнтськими сценаріями.
Профілювання: CPU/alloc/lock-contention, N + 1 (SQL/HTTP), повільні коди.
Контроль регресів: порівняння р95/р99/помилок до/після релізу (канареечное).

13) Вартість (Cost-Observability)

Метрики витрат: `cpu_ms`, `egress_bytes`, `db_calls`, `$ per 1k requests`.
Алокація на ендпоінт/тенант/фічу: теги білінгу з оркестратора + метрики навантаження → звіт по юніт-економіці API.
Алгоритм оптимізації: вибираємо TOP-ендпоінти за твором'traffic × cost × (p95 − мета)'.

14) Пер-тенант аналітика і «справедливість»

Всі ключові метрики - з лейблом'tenant _ id/plan'.
Частка «важких» клієнтів у хвостах p99; окремі ліміти/квоти та бюджети ретраїв.
Справедливий шейринг: при перевантаженні зменшуємо частку «гучних» орендарів.

15) Специфіка iGaming/фінансів

Розрізи по'kyc _ level','risk _ tier','payment _ method'.
SLI для «грошових» шляхів ('POST/deposits','POST/withdrawals'): нижче цільові p95, окремі бюджети помилок.
Метрики Time-to-Wallet (TTW), частка автоблокувань антифродом, конверсія виплати.
Аудит: незмінні журнали для фінансових дій і рішень антифроду.

16) Інструментація: практики реалізації

• `api_http_requests_total` (counter)
• `api_http_request_duration_seconds` (histogram)
• `api_outbound_requests_total`, `api_db_query_duration_seconds`
• `api_rate_limited_total`, `api_retry_total{reason}`

Лейбли: `route`, `method`, `status_class`, `tenant`, `region`, `version`, `canary`, `provider`, `db_table`.
Кардинальність: уникайте вільних значень (user_id), використовуйте «бакети »/хеш.
Exemplars: підключіть до гістограм p95/p99 → клік по trace.

17) Антипатерни

Середні замість перцентилів; відсутність розбиття на статус-класи.
Неузгоджені'route '/' path'( динамічні ID «вшиті» в лейбли).
Лейбли з високою кардинальністю (raw user_id, IP).
Відсутність роздільного обліку зовнішніх провайдерів (PSP/3rd-party).
Алерти по «шуму» (єдиноокно і один поріг).
p99 без урахування queue time (маскує реальну деградацію).

18) Контрольний список prod-готовності

• Визначені SLI/SLO і error-budget, узгоджені з бізнесом.
• Єдині гістограми latency і статус-класи; p95/p99 на дашбордах.
• Повне трасування (OTel), кореляція логів/метрик/трейсів.
• Алерти burn-rate (двовіконні), пороги по p99 і error-rate.
• Пер-тенант/пер-план розрізи і звіти за вартістю.
• Дашборди: Exec, Per-Route, Dependencies, Capacity, Abuse.
• Навантажувальні сценарії (бурст/плато/стрес), профілювання.
• Політики ретраїв з джиттером; облік впливу ретраїв на RPS.
• Документація SLA/SLO для партнерів і публічних клієнтів.
• Ретеншн/маскування логів, захист PII.

19) TL; DR

Будуйте спостережуваність навколо SLI/SLO і error-budget, вимірюйте RED/USE, збирайте гістограми latency з p95/p99 і «queue time», поширюйте єдиний trace-id від периметра до БД, використовуйте tail/adaptive-sampling, тримайте пер-тенант/вартісні розрізи і двовіконний burn-rate-алертинг. Ємність плануйте за законами черг і впливу на бізнес-метрики; антипатерни - середні замість перцентилів, висока кардинальність і невраховані зовнішні залежності.