Распределённая трассировка запросов
Назначение
Интеграция библиотеки OpenTelemetry реализует распределённую трассировку запросов — сквозную наблюдаемость (observability) системы. Ранее использовался внутренний механизм передачи TraceID между сервисами, который приводил к разрывам цепочек при технических ошибках и не давал достаточной глубины контекста для анализа проблем.
Трассировка отслеживает путь запроса через все сервисы системы (Gateway, Composer, Core и др.). Фундаментальная единица трассы — Span, содержащий метаданные, время выполнения, статусы ответов и кастомную информацию.
Трассировка генерируется и пробрасывается между сервисами на уровне заголовков в любом случае, однако фактическое сохранение и экспорт этих данных зависят от настроек экспортёра и сэмплера.
Настройки экспорта (Exporter Type)
Определяет, куда сохраняются данные о трассах:
| Режим | Назначение и особенности |
|---|---|
| None | Данные никуда не сохраняются. Подходит для чрезвычайно нагруженных продакшен-систем: генерация и проброс TraceID продолжаются, но оверхэд на диск и сеть отсутствует. |
| Jaeger | Прямая отправка в систему Jaeger для визуализации. Требует поднятия отдельного сервиса Jaeger и открытия портов; не входит в базовую поставку. Используется на dev-стендах или для глубокого анализа. |
| File | Целевой режим для продакшена. Каждый сервис пишет информацию о трассах в свой отдельный JSON-файл. Файлы передаются в поддержку, конвертируются в формат Jaeger и загружаются в Jaeger UI для анализа. |
При выборе File для ограничения размера файлов трассировки предусмотрена ротация файлов.
Настройки сэмплирования (Sampler Mode)
Определяет, какая часть трасс фактически сохраняется:
| Режим | Описание |
|---|---|
| Always | Сохраняется 100% трасс. Удобно для локальной отладки и точечной диагностики. |
| Never | Не сохраняется ни одна трасса (0%). Трейсы генерируются и пробрасываются, но не пишутся на диск/в сеть. |
| Parent-Based | Сохраняется заданная доля трасс (параметр Fraction, от 0.0 до 1.0). Если родительский запрос попадает в выборку, сохраняется вся связанная с ним цепочка (все дочерние спэны). Используется для постоянного мониторинга высоконагруженных систем без избыточной нагрузки. |
Сценарий диагностики проблем
Поскольку по умолчанию трассировка выключена, типовой сценарий диагностики выглядит так:
- У клиента возникает проблема (например, медленная работа S3 API).
- Администратор включает экспорт в
Fileи сэмплер вAlways(100%) через конфигурацию. - Воспроизводится проблемная операция (например, загрузка объекта).
- Трассировка выключается.
- JSON-файлы передаются в поддержку.
- Поддержка конвертирует файлы и загружает их в Jaeger UI для поиска узкого места (например, медленного ответа базы данных).
КластерПри использовании
File-экспорта в кластере файлы трассировки нужно собирать со всех узлов — Admin UI не знает, на какой именно узел попал конкретный запрос.
Безопасность и содержимое
В файлы трассировки и Jaeger UI попадают метаданные запросов, время выполнения, статусы ответов, URL-пути (включая имена бакетов, если они передаются в пути) и кастомные Span-данные.
Что не сохраняетсяСекретные данные, логины, пароли, заголовки (Headers) и куки (Cookies) в трассы не попадают. Библиотека по умолчанию не кладёт в трассы чувствительные данные, однако разработчик может вручную добавить кастомный Span с дополнительной информацией или текстом ошибки.
Производительность и дисковое пространство
При выключенном экспорте (None) нагрузка на систему отсутствует — выполняется только проброс заголовков. При включённом экспорте запись происходит синхронно, а оверхэд регулируется параметром Fraction в режиме Parent-Based.
Объём одного трейса зависит от количества спэнов в цепочке и в среднем составляет порядка нескольких килобайт. Управление местом на диске обеспечивается ротацией файлов.