Чому критично логувати і трасувати 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, дедуп.

Kacca/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 .

Знімок статусів саг за часом.

Підпис/хеш запиту/вебхука (для 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/xaoc-навчання: дубль-доставка, падіння регіону, затримка гаманця.
Доступ до логів і трейсів - 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-спостережуваність перетворюють інциденти в керовані події, а суперечки - у відтворювані кейси. На такому фундаменті гроші рухаються один раз, звітність відтворюється в будь-який момент, а команда залишається швидкою і спокійною - навіть в піку турнірів і під час релізів.