---
title: Распределённая трассировка
description: "Tracing: traces и spans, context propagation, service map, RED и Apdex, sampling, OpenTelemetry и eBPF."
---

## Что показывает трассировка

**Distributed tracing** записывает путь одного запроса через операции, сервисы и зависимости. Она помогает ответить, где именно возникла задержка или ошибка, когда запрос нельзя воспроизвести локально.

- **Trace** — сквозной путь запроса от начала до завершения.
- **Span** — одна операция внутри trace: HTTP request, вызов сервиса, SQL query или фоновая задача.
- **Root span** — начальная операция, дочерние spans раскрывают последующие шаги.
- **Attributes и events** — метаданные и события внутри span: сервис, маршрут, статус, длительность и другие безопасные детали.

Waterfall-визуализация показывает иерархию и время операций. По ней видно, какой участок критического пути занял время и какие вызовы шли параллельно.

## Context propagation

Для единой трассы контекст должен передаваться между процессами. Клиент, API gateway, backend и worker получают trace/span identifiers и связывают свои операции с тем же путём. Обычно используют W3C Trace Context.

Если propagation обрывается на очереди, внешнем API или ручном HTTP-клиенте, появляются отдельные фрагменты вместо одной трассы. Поэтому проверяют не только наличие SDK, но и сквозной сценарий.

## Service map и метрики

Трассы позволяют строить **service map**: какие сервисы вызывают друг друга, где возникают ошибки и задержки. Для request-driven сервисов используют **RED**:

- **Rate** — частота запросов;
- **Errors** — доля или число ошибок;
- **Duration** — распределение длительности.

**Apdex** дополнительно оценивает долю ответов, уложившихся в заданные пороги удовлетворительной и допустимой задержки. Он не заменяет распределение и пользовательские SLI.

## Sampling

Сохранение всех трасс может быть дорогим, а удаление всего подряд — потерять редкие ошибки.

- **Head sampling** решает в начале запроса, сохранять ли trace; дешевле, но может пропустить необычное завершение.
- **Tail sampling** принимает решение после получения данных и может сохранить ошибки или медленные запросы; требует больше ресурсов и буферизации.

Полезно сохранять представительный обычный трафик и повышать покрытие ошибок, длинных запросов и критичных сценариев. Правила оценивают по диагностической ценности и стоимости.

## OpenTelemetry и eBPF

[OpenTelemetry](https://wpcraft.ru/kb/infrastructure/tools/open-telemetry.md) предоставляет API/SDK, авто- и ручную инструментацию, OTLP и Collector. Он позволяет экспортировать трассы в разные backends.

**eBPF** может собирать сетевые и системные события без изменения кода приложения и помогает построить service map или автоматически инструментировать часть вызовов. Но zero-code подход не всегда раскрывает бизнес-операции, внутреннюю логику и пользовательские атрибуты; ручная инструментация остаётся полезной.

## Минимальная проверка

1. Выбрать один сквозной сценарий с двумя и более вызовами.
2. Проверить trace ID и propagation на всех участках.
3. Убедиться, что у spans есть service, operation, status и duration.
4. Найти медленный запрос и сопоставить его с логами.
5. Настроить sampling, redaction и retention.
6. Связать релиз с изменением задержки и ошибок.

## Связанные инструменты

- [Jaeger](https://wpcraft.ru/kb/infrastructure/tools/jaeger.md) — хранение и исследование распределённых трасс.
- [OpenTelemetry](https://wpcraft.ru/kb/infrastructure/tools/open-telemetry.md) — инструментация и конвейер.
- [Better Stack](https://wpcraft.ru/kb/infrastructure/tools/better-stack.md) — tracing, service map и корреляция сигналов.
- [Grafana](https://wpcraft.ru/kb/infrastructure/tools/grafana.md) — совместное исследование traces, logs и metrics.

## Связанные материалы

- [Log management](https://wpcraft.ru/kb/infrastructure/observability/log-management.md) — события внутри и вокруг spans.
- [Infrastructure monitoring](https://wpcraft.ru/kb/infrastructure/observability/infrastructure-monitoring.md) — агрегированные показатели сервисов.
- [AI-наблюдаемость](https://wpcraft.ru/kb/ai/agents/observability.md) — трассировка агентных запусков и LLM-вызовов.

## Материалы и источники

- [OpenTelemetry: Observability primer](https://opentelemetry.io/docs/concepts/observability-primer/) — traces, spans и путь запроса.
- [OpenTelemetry: Traces](https://opentelemetry.io/docs/concepts/signals/traces/) — контекст, spans и атрибуты.
- [W3C: Trace Context](https://www.w3.org/TR/trace-context/) — переносимый контекст распределённой трассировки.
- [Better Stack: Tracing](https://betterstack.com/tracing) — пример eBPF, service map и OpenTelemetry-native tracing.