Почему критично логировать и трассировать API-запросы

Полный текст статьи

💡 18+. Технический материал для платформ, студий (RGS/live), агрегаторов и смежных сервисов. Не призыв к игре. Под «денежными путями» подразумеваем authorize/settle/credit/withdraw.

1) Зачем вообще логи и трейсинг в iGaming

Деньги и репутация. Любая потеря/дубль сеттлмента — прямые убытки. Нужна доказуемость, что операция прошла один раз.

Регуляторика. Отчётность, споры, расследования — без журналов вы «слепы».

SLO и инциденты. Латентность растёт? Падает конверсия депозита? Трейсы покажут узкое место.

Безопасность и фрод. Аномальные паттерны, реплеи, скриптовые атаки — видны в телеметрии.

Вывод: наблюдаемость — часть дизайна денег, а не «последний штрих».

2) Что именно трассировать и логировать

2.1 Корреляция по всей цепочке

`trace_id` — один на запрос от edge → доменные сервисы → шина → консьюмеры.

`span_id` — для каждого хопа, с `parent_span_id`.

Ключи бизнеса: `tenant_id/brand_id/region`, `player_id` (псевдоним), `session_id`, `round_id`, `bet_id`, `settlement_id`, `idempotency_key`.

2.2 Что писать в логах (структура)

Таймстамп ISO-8601 с таймзоной.

Метод/путь/статус, длительность (мс), размер payload (байт).

Исход и класс ошибки (`business/4xx/5xx`), код (`RG_BLOCK`, `DUPLICATE`, `IDEMPOTENCY_MISMATCH`).

Хост/зона/версия билда, имя сервиса и среда (`prod/eu-west-1`).

Сетевые признаки: IP/ASN (агрегированные), user-agent (усечённый/нормализованный).

2.3 Где — по слоям

Edge/API gateway: аутентикация, rate limits, geo/бот-фильтры.

Домены (Wallet/Bonus/RGS): команды/события, статусы саг, латентность БД/кэша.

Шина/очереди: лаг, retry, DLQ, дедуп.

Касса/PSP: авторизации, 3-DS, мерчант/роут.

3) Форматы: только структурированные логи

Свободный текст бесполезен для поиска и алертов. Используйте JSON-строки (одна запись — одна строка).

Пример (усечённо):

json
{
"ts":"2025-10-23T16:21:05.481Z",  "env":"prod",  "service":"wallet",  "version":"1.14.3",  "level":"INFO",  "event":"bet.settle",  "trace_id":"tr_a1b2c3",  "span_id":"sp_01",  "tenant_id":"brand-7",  "region":"EU",  "bet_id":"b_001",  "round_id":"r_8c12",  "idempotency_key":"settle_r_8c12_1",  "latency_ms":124,  "status":"credited",  "win_minor":1460,  "currency":"EUR"
}

4) Трейсинг: OpenTelemetry как стандарт

Инструментация HTTP/gRPC/DB/кэша + кастомные спаны на саги (`authorize → commit → settle → credit`).

Пропагация контекста: W3C Trace Context (`traceparent`, `tracestate`), в вебхуках — заголовками.

Багаж (baggage): только безопасные ключи (brand/region/trace flags), не PII.

Сэмплинг:

по умолчанию 1–10% для общего трафика, всегда 100% для денежной ошибки/латентности > SLO, динамический апсемплинг при инциденте.

5) WORM-аудит и неизменяемость

Для критичных действий (изменение лимитов, key-rotation, джекпот-конфиги, ручные операции поддержки) — WORM-хранилище (write once read many).

Требования: неизменяемость, подписи/хэши, независимый доступ комплаенса, ретеншен по закону (например, 5–7 лет).

6) PII и безопасность логов

Не логируйте PAN, CVV, документ-ID, e-mail/телефон в открытом виде. Маскируйте/токенизируйте.

В логах используйте псевдо-идентификатор игрока (stable hash).

Секреты/токены в лог не попадают никогда (фильтры на уровне SDK/агента).

Резидентность данных: журналы и трейсы физически в регионе (EU/UK/BR…), с отдельными ролями доступа (RBAC/ABAC).

Шифрование at-rest/in-transit, доступ — по временным токенам, принцип минимальных прав.

7) Метрики и SLO, которые держат платформу

Latency p95/p99 по ключевым эндпоинтам: `bets.authorize`, `bets.settle`, `wallet.credit`, `cashier.deposit`.

Error rate по классу и коду.

Queue/consumer lag (шина), % ретраев и «штормов».

Settle lag (от исхода до кредита), deposit success rate по PSP/гео.

Webhook lag p99 по темам.

Алерты — по «SLO-бюджету» (превысили бюджет ошибок/латентности за окно → инцидент).

8) Для расследований и споров: минимальный набор

Кросс-ссылка `trace_id ↔ event_id ↔ idempotency_key ↔ settlement_id`.

Снимок статусов саг по времени.

Подпись/хэш запроса/вебхука (для non-repudiation).

Скриншот/снимок конфигурации (версия правил бонуса/джекпота) по `ts`.

9) Хранение и стоимость

Горячее (7–14 дней): поиск инцидентов и постмортемы.

Тёплое (30–90 дней): продуктовая аналитика и фрод-паттерны.

Холодное/архив (≥ 1 год): юридические/регуляторные нужды.

Применяйте фильтры и сэмплинг, храните агрегаты, включайте TTL и компрессию. Используйте индексацию по `trace_id`, `tenant_id`, `event`, `status_code`.

10) Чек-листы

Для платформы/оператора

Везде есть `trace_id`, `idempotency_key`, теги `tenant/brand/region`.
Структурированные JSON-логи; OpenTelemetry на HTTP/gRPC/DB/кэш/шину.
WORM-аудит крит-действий; ретеншен по регуляторике.
Маскирование PII/секретов; журналы и трейсы — по регионам.
SLO-дашборды: p95/p99, error-rate, queue-lag, settle-lag, webhook-lag.
Алерты по SLO-бюджету; авто-апсемплинг трейсов при деградации.
DR/хаос-учения: дубль-доставка, падение региона, задержка кошелька.
Доступ к логам и трейсам — RBAC/ABAC, «четыре глаза» для экспорта.

Для провайдера (RGS/live/JP)

Отправляю/прокидываю `trace_id` и `idempotency_key` во все вызовы и вебхуки.
Логи — структурированные; код/класс ошибки фиксируются.
Вебхуки подписаны; храню `event_id` и дедуплицирую.
Трассировка исходов/сеттлмента, измеряю `settle_lag`.
Маскирование PII; токены/ключи не попадают в логи.
Делаю сэмплинг разумным (100% — для ошибок и денежных аномалий).

11) Анти-паттерны (красные флаги)

Текстовые логи без структуры и `trace_id`.

Отсутствие `idempotency_key` в логах write-операций.

Логирование PII/секретов, запись Bearer-токенов.

Логи всех регионов в одном бакете без разграничения.

Отсутствие WORM для крит-действий; «редактируемые» аудиты.

События публикуются в обход outbox/CDC → «потерянные» операции.

Слепой 100% трейсинг без фильтров (разорение на хранении, шум).

Нет дашбордов SLO/алертов; расследования длятся часами.

12) Внедрение по шагам (реалистично)

1. Ввести единый `trace_id` и `idempotency_key` во всех контрактах (REST/gRPC/вебхуки).

2. Перевести логи на JSON; добавить обязательные поля (сервис, версия, регион, таймстамп, коды).

3. Подключить OpenTelemetry и пропагацию контекста; минимальный трейсинг на денежные пути.

4. Настроить SLO-дашборды и алерты; определить бюджеты.

5. Включить WORM-аудит критичных действий; определить ретеншен.

6. Ввести маскирование PII/секретов, разграничение доступа к журналам.

7. Добавить хаос-кейсы и учения, отрабатывать постмортемы.

8. Оптимизировать хранение: сэмплинг, TTL, архивы.

13) Итог

Логи и трассировка — это не «удобно иметь», а неснимаемая обязанность платформы и провайдера iGaming. Структурированные логи, сквозные трейсы, WORM-аудит, защита PII и SLO-наблюдаемость превращают инциденты в управляемые события, а споры — в воспроизводимые кейсы. На таком фундаменте деньги движутся один раз, отчётность воспроизводится в любой момент, а команда остаётся быстрой и спокойной — даже в пике турниров и во время релизов.