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), медленные коды.
Контроль регрессов: сравнение p95/p99/ошибок до/после релиза (канареечное).

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-алертинг. Емкость планируйте по законам очередей и влиянию на бизнес-метрики; антипаттерны — средние вместо перцентилей, высокая кардинальность и неучтенные внешние зависимости.