Distributed Tracing

(Розділ: Технології та Інфраструктура)

Коротке резюме

Розподілені трасування дають відповідь на питання де і чому втрачається час по шляху запиту через шлюз, API, черги, БД, зовнішніх провайдерів (PSP/ігрові студії). OpenTelemetry (OTel) - відкритий стандарт SDK/агентів/протоколу, що об'єднує трейси, метрики і логи. В iGaming це базовий інструмент, щоб тримати p95/p99, швидко локалізувати проблеми платежів і виявляти «вузькі місця» перед піковими турнірами.

1) Концепції OTel

Trace - повний шлях операції (депозит, ставка, висновок).
Span - ділянка роботи (HTTP-хендлер, SQL-запит, виклик черги/провайдера).
Attributes - ключ-значення з деталями ('net. peer. name`, `db. system`, `psp. route`).
Events - моментальні події (ретрай, таймаут, кеш-промах).
Links - зв'язок з іншими трасами (важливо для async/queue).
Resource - метадані процесу: `service. name`, `service. version`, `deployment. environment`, `cloud. region`.

2) Пропагандація контексту

traceparent: 00-<trace_id>-<span_id>-01 tracestate:...

Додатково - baggage для безпечних ключів (наприклад,'tenant','route'), не кладіть туди PII.

Де проколювати контекст: API-шлюз → внутрішні RPC → продюсер в чергу → консьюмер → зовнішні HTTP (PSP/провайдери).

3) Семантичні конвенції (обов'язковий мінімум)

HTTP/RPC: `http. method`, `http. route`, `http. status_code`.
DB/кеш: `db. system` (`mysql`/`postgresql`/`redis`), `db. statement'( замасковано),'db. operation`.
Черги: `messaging. system` (`kafka`/`rabbitmq`), `messaging. destination`, `messaging. operation` (`send`/`process`).
Платежі: `psp. route`, `psp. provider`, `payment. id'( псевдонімізувати),'amount','currency'.
iGaming домен: `game. provider`, `game. session_id` (hash), `player. id_hash`.

Єдина таксономія → порівнянність дашбордів і швидкий пошук причин.

4) Семплінг: Як не потонути в даних

Head-based (на вході запиту)

Простий, дешевий; підходить для загального потоку.
Мінус - можна втратити «цікаві» повільні/помилкові траси.

Tail-based (в Collector)

Рішення приймається після завершення спанів: зберігаємо лише помилки/повільні/важливі сегменти (VIP/платежі).
Ідеально для прод-навантаження: сильно знижує вартість при високій інформативності.

• Head: 5-10% для «фонового» покриття.
• Tail: 100% помилок + p95 + повільні + платіжні траси/канарські релізи.

5) Топології OpenTelemetry Collector

Agent-сайдкар (на кожному вузлі/поді): локальна приймання, мінімальний буфер, експорт в агрегатор.
Gateway (кластерний): tail-sampling, маршрутизація, збагачення, експорт в Tempo/Jaeger/Zipkin/OTLP.

Приклад: tail-sampling (фрагмент YAML)

yaml processors:
tailsampling:
decision_wait: 5s policies:
- name: errors type: status_code status_code:
status_codes: [ ERROR ]
- name: slow_p95 type: latency latency:
threshold_ms: 250
- name: payments type: string_attribute string_attribute:
key: service. name values: [ "payments-api", "payments-worker" ]

6) Кореляція з метриками і логами

У кожен запис логів додавайте'trace _ id '/' span _ id'.
Метрики латентності зберігайте як гістограми і включайте exemplars - посилання на репрезентативний'trace _ id'для «стрибка» з p95-бокету в конкретний слід.
Анотації релізів (Git SHA, версія чарту) - як events/лейбли.

7) Інструменталізація (мови та авто-агенти)

Go (ручна + авто)

go tp:= sdktrace. NewTracerProvider(
sdktrace. WithBatcher(exporter),
sdktrace. WithResource(resource. NewWithAttributes(
semconv. SchemaURL,
semconv. ServiceName("payments-api"),
)),
)
otel. SetTracerProvider(tp)

ctx, span:= tracer. Start(ctx, "Deposit")
defer span. End()
span. SetAttributes(
attribute. String("psp. route","pspX"),
attribute. String("currency","EUR"),
)

Java

Авто-агент'-javaagent:opentelemetry-javaagent. jar', конфіг через env ('OTEL _ SERVICE _ NAME','OTEL _ EXPORTER _ OTLP _ ENDPOINT').
Вручну - анотації/інструмент цибулевих місць (JDBC-пули, кеш).

Node. js / Python

Авто-інструмент з SDK + плагіни (Express/FastAPI/celery).
Для черг - обгортки продюсера/консьюмера, щоб проставити'messaging.'і links.

8) Черги і async: Правильні спани

Продюсер ('send'): span на відправку в топік/чергу.
Консьюмер ('process'): новий span обробки повідомлення з link на span продюсера (зберегти причинно-наслідковий зв'язок без загального'trace _ id').
Атрибути: `messaging. kafka. partition`, `messaging. rabbitmq. routing_key`, `messaging. message_id`.
При ретраях - event'retry', лічильник спроб.

9) БД/кеш і N + 1

Увімкніть трейсинг драйверів БД, групуйте однотипні запити в батчі.
Для Redis/кешу - атрибути'cache. hit`/`cache. miss`.
Виносьте «важкі» запити в окремі спани - видно, де p99.

10) Зовнішні провайдери: PSP/ігрові студії

Обертайте HTTP-клієнти: `psp. provider`, `psp. route`, `timeout_ms`, `attempt`.
Логуйте коди/типи помилок, але не PII (номер карти, токени).
Порівнюйте студії/маршрути по'duration','error-rate'.

11) Фронтенд і RUM

OTel Web SDK: `page_view`, `resource_load`, `xhr`.
Проколюйте'traceparent'в бекенд, щоб стежити шлях користувача skвозь UI → API → БД.
Сегментація по гео/провайдерам мережі - опціональні лейбли.

12) Безпека та PII

Маскуйте поля ('db. statement'з редагуванням), хешируйте'player _ id'.
Зони даних: `pii=true`, `region=EU/TR/LATAM`.
Контроль доступу до трейсів платежів (роль-базований).
WORM/Retention: терміни зберігання для чутливих слідів, видалення по політиці.

13) Продуктивність і вартість

Tail-sampling з політики: «помилки + повільні + платежі + канарські релізи».
Downsampling гістограм метрик, агресивна дедуплікація логів.
Обмеження кардинальності: не вписувати'user _ id'як лейбл метрики.
Буфери/батчі в Collector, компресія OTLP.

14) Дашборди та аналіз

Service map: залежності сервісів, забарвлення за помилками/латентності.
Release compare: стабільна vs канарська ревізія (p95, error-rate, payments conv).
Top slow traces: за маршрутом '/deposit', розріз по PSP/регіону.
Queue lag: траси з глибокою затримкою споживання.

15) Приклади конфігурацій Collector

Pipelines (метрики/трейси/логи, фрагмент)

yaml receivers:
otlp: { protocols: { http: {}, grpc: {} } }

processors:
batch:
memory_limiter:
limit_mib: 1024 spike_limit_mib: 256 attributes/payments:
actions:
- key: "psp. provider"
action: insert value: "pspX"

exporters:
otlp/traces: { endpoint: tempo:4317, tls: { insecure: true } }
otlp/metrics:{ endpoint: prometheus-otlp:4317, tls: { insecure: true } }
otlp/logs:  { endpoint: loki-otlp:4317, tls: { insecure: true } }

service:
pipelines:
traces:
receivers: [ otlp ]
processors: [ memory_limiter, batch, tailsampling ]
exporters: [ otlp/traces ]
metrics:
receivers: [ otlp ]
processors: [ batch ]
exporters: [ otlp/metrics ]
logs:
receivers: [ otlp ]
processors: [ batch ]
exporters: [ otlp/logs ]

16) Runbooks (типові сценарії)

A) Зростання p99 в'payments-api '

1. Відкрити «Top slow traces» → провалитися в спани БД/PSP.
2. Якщо PSP-проблема - перевести маршрут, включити ретраї/таймаути.
3. Перевірити чергу'withdrawals'( lag), збільшити консьюмери.

B) Помилки 5xx після релізу

1. Фільтр по'service. version`.
2. Порівняти стабільну/канаркову; знайти спайки в'psp. route`.
3. Заморозити промоушен, відкотити (див. «Стратегії релізів «/» Ролбеки »).

C) Підозра на N + 1

1. Трейси з великим числом коротких DB-спанів.
2. Включити агрегацію/джойни, додати кеш-шар.

17) Чек-лист впровадження

1. Увімкніть OTel SDK і єдині Resource-атрибути ('service. name`, `env`, `region`).
2. Пропаганда W3C Trace Context через всі шари і черги.
3. Мінімальний набір семантичних атрибутів (HTTP/DB/queue/PSP).
4. Tail-sampling: помилки, p95 +, платежі, канар.
5. Логи з'trace _ id '/' span _ id', метрики з exemplars.
6. Дашборди: service map, release compare, payments flow.
7. PII-політики: маскування, зони, ролі, ретеншн.
8. Тести/навантаження: перевірка кореляції і completeness трейсингу перед піками.
9. Автогенерація runbook-посилань в алертах.
10. Звіт по вартості телеметрії і кардинальності.

18) Антипатерни

Трасування «тільки на вході» без БД/черг → немає користі.
Відсутність пропагандації в async → «рвуться» ланцюжки причинно-наслідкових зв'язків.
Семплінг випадковий 1% без tail-логіки → не ловимо повільні/помилкові.
Логи без'trace _ id'→ немає наскрізної кореляції.
Сирі PII в атрибутах/логах → ризики комплаєнсу.
Кардинальність «у стелю» (user/session як лейбли метрик) → вибух вартості.

Підсумки

OpenTelemetry перетворює спостережуваність з набору розрізнених інструментів в наскрізну мову продуктивності. При правильній пропагандації контексту, акуратній семантиці, tail-sampling і зв'язці «метрики ↔ траси ↔ логи» команда iGaming тримає p95/p99 під контролем, швидко ізолює вузькі місця (БД, черги, PSP) і впевнено випускає релізи навіть в піки трафіку.