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) и уверенно выпускает релизы даже в пики трафика.