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