Телеметрия и сбор событий

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.