Телеметрія та збір подій

1) Призначення та принципи

• Єдиний і передбачуваний потік подій для аналітики, антифроду, RG, комплаєнсу і ML.
• Наскрізне трасування (user/session/request/trace) і відтворюваність.
• Мінімізація PII і відповідність вимогам приватності.

Принципи: schema-first, privacy-by-design, idempotency-by-default, observability-by-default, cost-aware.

2) Таксономія подій

Платіжні: `payment. deposit`, `payment. withdrawal`, `payment. chargeback`.
Ігрові: `game. session_start/stop`, `game. bet`, `game. payout`, `bonus. applied`.
Користувацькі: `auth. login`, `profile. update`, `kyc. status_changed`, `rg. limit_set`.
Операційні: `api. request`, `error. exception`, `release. deploy`, `feature. flag_changed`.
Комплаєнс: `aml. alert_opened`, `sanctions. screened`, `dsar. requested`.

Кожен тип має власника (domain owner), схему і SLO свіжості.

3) Схеми та контракти

• `event_time` (UTC), `event_type`, `schema_version`, `event_id` (UUID/ULID),
• `trace_id`/`span_id`, `request_id`, `user. pseudo_id`, `session_id`,

json
{
"event_id": "01HFY1S93R8X",
"event_time": "2025-11-01T18:45:12. 387Z",
"event_type": "game. bet",
"schema_version": "1. 4. 0",
"user": {"pseudo_id": "p-7a2e", "age_band": "25-34", "country": "EE"},
"session": {"id": "s-2233", "device_id": "d-9af0"},
"game": {"id": "G-BookOfX", "provider": "StudioA", "stake": {"value": 2. 00, "currency": "EUR"}},
"ctx": {"ip": "198. 51. 100. 10", "trace_id": "f4c2...", "request_id": "req-7f91"},
"labels": {"market": "EE", "affiliate": "A-77"}
}

Еволюція схем: семантичні версії; backward-compatible - додаємо nullable поля; breaking - тільки в новій версії ('/v2') з періодом подвійного запису.

4) Інструментація: де і як

4. 1 Клієнт (Web/Mobile/Desktop)

SDK телеметрії з локальним буфером, batch-відправка, експоненціальні ретраї.
Авто-події: візити, кліки, видимість блоків, web-vitals (TTFB, LCP, CLS), помилки JS.
Ідентифікатори: 'device _ id'( стійкий, але приватний),'session _ id'( оновлюється),'user. pseudo_id`.
Захист від «шумів»: дедуп по'event _ id', троттлінг, client-side sampling.

4. 2 Сервер/бекенд

Обгортки логгерів/трейсера (OpenTelemetry) → еміт доменних подій.
Обов'язкове прокидання'trace _ id'з edge/gateway в усі downstream сервіси.
Outbox-патерн для транзакційної публікації доменних подій.

4. 3 Провайдери/треті сторони

Конектори (PSP/KYC/студії) з нормалізацією до хост-схем; Версійні адаптери.
Підпис/перевірка цілісності payload, журналізм периметра (ingest audit).

5) OpenTelemetry (OTel)

Трейси: кожен запит отримує'trace _ id'; зв'язуємо логи/події через'trace _ id '/' span _ id'.
Логи: використовуємо OTel Logs/перетворювачі; мітки середовища'service. name`, `deployment. env`.
Метрики: RPS/latency/error-rate по сервісах, бізнес-метрики (GGR, конверсія).
Collector: єдина точка прийому/буфер/експорт в Kafka/HTTP/графіч. стек.

6) Ідентифікатори та кореляція

'event _ id'- унікальність та ідемпотентність.
`user. pseudo_id' - стабільна псевдонімізація (маппінг окремо і обмежено).
'session _ id','request _ id','trace _ id','device _ id'- обов'язкові для наскрізного аналізу.
Узгодженість ID на рівні API-шлюзу і SDK.

7) Семплювання і контроль обсягу

Правила: per-event-type, per-market, динамічне (адаптивне) по навантаженню.
Точно-зняті події: платіжні/комплаєнс/інциденти - не семплюються.
Аналітичні події: допускається 10-50% з коригуючими вагами у вітринах.
Server-side downsampling: допустимо для high-frequency метрик.

8) Приватність і комплаєнс

Мінімізуйте PII: токенізуйте PAN/IBAN/email; IP → гео-коди/ASN при ingest.
Регіоналізація: відправляйте в регіональні ingest-ендпоінти (EEA/UK/BR).
DSAR/RTBF: підтримка вибіркового приховування проекцій; журнал правових операцій.
Політики зберігання: терміни за типом (аналітика коротше, регуляторні довше); Legal Hold.

9) Транспорт і буферизація

Клієнт → Edge: HTTPS (HTTP/2/3),'POST/telemetry/batch'( до 100 подій).
Edge → Шина: Kafka/Redpanda з партіонуванням по'user. pseudo_id`/`tenant_id`.
Формати: JSON (ingest), Avro/Protobuf (в шині), Parquet (в lake).
Надійність: ретраї з jitter, DLQ, poison-pill ізоляція.

json
{
"sdk": {"name":"igsdk-js","version":"2. 7. 1"},
"sent_at": "2025-11-01T18:45:12. 500Z",
"events": [ {... }, {... } ]
}

10) Надійність та ідемпотентність

Client-generated'event _ id'+ серверний дедуп по'( event_id, source)'.
Outbox на сервісах, Exactly-Once-семантика в потоках (keyed state + dedupe).
Порядок у межах ключа: партіонування по'user/session'.
Контроль часу: NTP/PTP, допустимий дрейф (наприклад, ≤ 200 мс),'received _ at'на сервері.

11) Якість телеметрії (TQ) і SLO

Completeness: ≥ 99. 5% подій критичних типів за T.
Freshness: p95 затримка доставки до Silver ≤ 15 хв.
Correctness: валідні схеми ≥ 99. 9%, drop-rate < 0. 1%.
Trace coverage: частка запитів з'trace _ id'≥ 98%.
Cost/GB: цільовий бюджет на ingest/зберігання по доменах.

12) Спостережуваність і дашборди

• Лаг ingest (p50/p95) за джерелами і регіонами.
• Completeness за типами подій і ринків.
• Помилки валідації схем/oversized-payloads.
• Карта версій SDK і відсоток застарілих клієнтів.
• Кореляція web-vitals ↔ конверсія/відмови.

13) Клієнтські SDK: вимоги

Легкий footprint, offline-буфер, відкладена ініціалізація.
Налаштування: sampling, max batch size, max queue age, privacy-моды (no-PII).
Захист: підпис пакета/anti-tamper, обфускація ключів.
Оновлення: feature-прапори для відключення гучних подій.

14) Edge-шар і захист

Rate limit, WAF, schema validation, компресія (gzip/br).
Token bucket на клієнта; анти-replay ('request _ id', TTL).
Зняття IP і UA → нормалізація/збагачення поза «сирого» payload.

15) Інтеграція з конвеєром даних

Bronze: незворотно-додаткові сирі payload (для форензики).
Silver: нормалізовані таблиці з дедупом/збагаченням.
Gold: вітрини для BI/AML/RG/продукту.
Лінедж між подіями та звітами; версії трансформацій.

16) Аналітика якості клієнта

Коефіцієнт «тихих клієнтів» (немає подій за N годин).
Аномалії «шторму» (mass duplicate/burst).
Частка «застарілих SDK» за версіями і платформами.

17) Процеси і RACI

R: Data Platform (ingest/шина/валідатори), App Teams (інструментація SDK).
A: Head of Data/Architecture.
C: Compliance/DPO (PII/retention), SRE (SLO/інциденти).
I: BI/Маркетинг/Ризик/Продукт.

18) Дорожня карта впровадження

1. Таксономія подій v1 + JSON-схеми для 6-8 типів.

2. SDK (Web/Android/iOS) с batch и sampling; Edge `/telemetry/batch`.

3. Kafka + Bronze шар; базові валідатори і дедуп.

4. Дашборд ingest lag/completeness, алерти на drop/валідатор.

• OTel Collector, трейс-кореляція; Silver-нормалізація і DQ-правила.
• Регіональні ендпоінти (EEA/UK), privacy-моди, DSAR/RTBF процедури.
• Карта версій SDK, авто-rollout оновлень по кільцях.

• Exactly-Once в потоках, Feature Store підключення, антифрод-онлайн фіди.
• Rule-as-Code для схем і валідаторів, симуляції змін (impact analysis).
• Оптимізація вартості: adaptive sampling, Z-order/кластеризація в lake.

19) Чек-лист якості перед релізом

• Заповнені обов'язкові поля схеми і коректні типи.
• Присутні'trace _ id '/' request _ id '/' session _ id'.
• SDK підтримує batch, retry, sampling.
• Edge валідує схему і обмежує розмір payload.
• Включені приватність-фільтри і токенізація чутливих полів.
• Налаштовані SLO/алерти і дашборди.
• Документація для доменів (приклад події, owner, SLA).

20) Часті помилки і як їх уникнути

Сирі події без схем: введіть registry і CI-валідацію.
Немає ідемпотентності: вимагайте'event _ id'і зберігайте вікна дедупа.
Змішування PII та аналітики: відокремлюйте маппінги, маскуйте поля.
Відсутність трейсингу: прокладайте'trace _ id'крізь gateway → сервіси → події.
Некеровані обсяги: застосовуйте sampling/trrottling і budget-квоти.
Глобальний endpoint без регіонів: використовуйте регіоналізацію і data residency.

21) Глосарій (коротко)

OpenTelemetry (OTel) - відкритий стандарт для трейсів/метрик/логів.
Outbox - транзакційна публікація доменних подій.
DLQ - черга «битих» повідомлень.
Sampling - відбір частини подій для зниження обсягу.
Data Residency - зберігання даних в потрібній юрисдикції.

22) Підсумок

Добре спроектована телеметрія - це домовленості, а не просто «відправка логів»: строгі схеми, узгоджені ідентифікатори, приватність за замовчуванням, надійний транспорт, спостережуваність і економна вартість. Дотримуючись цієї статті, ви отримаєте стійкий потік подій, готовий до аналітики, комплаєнсу і машинного навчання з передбачуваними SLO.