Трейсы¶

control.observability.traces

Sapsan экспортирует трейсы через OTLP/HTTP с protobuf. Приёмник задаётся в конфиге Sapsan; для HTTP endpoint нужен полный путь /v1/traces.

Запуск Jaeger¶

Для диагностики на одной машине запустите Jaeger all-in-one:

docker run --rm --name jaeger \
  -p 127.0.0.1:16686:16686 \
  -p 127.0.0.1:4318:4318 \
  cr.jaegertracing.io/jaegertracing/jaeger:2.22.0

Этот вариант хранит трейсы в RAM: после остановки процесса данные теряются. По умолчанию число трейсов не ограничено, поэтому по мере накопления данных расход RAM растёт и доступная память может закончиться. В конфиге Jaeger ограничьте число хранимых трейсов параметром jaeger_storage.backends.<имя>.memory.max_traces; это ограничение числа трейсов, а не объёма памяти в байтах. RAM-хранилище Jaeger предназначено для краткой диагностики. Для длительной работы настройте постоянное хранилище.

Настройка Sapsan¶

telemetry — локальная настройка процесса: central не передаёт эту секцию стримеру. Добавьте её в существующий стартовый конфиг /etc/sapsan/sapsan.yaml (или файл, заданный через CONFIG_PATH):

telemetry:
  otlp:
    enabled: true
    endpoint: http://127.0.0.1:4318/v1/traces
    sample_ratio: "0.01"

enabled включает экспорт. sample_ratio — строка с долей отбора новых трейсов: "0.01" соответствует 1%, "1.0" — всем новым трейсам; решение родительского span учитывается. Если параметр не задан, используется "0.01". Для короткой диагностики можно временно указать "1.0".

Перечитайте локальный конфиг службы. Экспортёр применяет изменения без перезапуска процесса:

sudo systemctl reload sapsan

После выполнения операций, покрытых трейсами, откройте http://127.0.0.1:16686, выберите сервис sapsan и выполните поиск. Экспорт работает пакетами, поэтому трейсы появляются с задержкой.

Если Sapsan работает в Docker, адрес 127.0.0.1 указывает на сам контейнер. Подключите Sapsan и Jaeger к общей Docker-сети и используйте http://jaeger:4318/v1/traces, где jaeger — имя контейнера приёмника.

Совместимость с переменными окружения¶

Если секция telemetry.otlp отсутствует, Sapsan поддерживает OTEL_ENDPOINT и OTEL_TRACES_SAMPLER_ARG:

OTEL_ENDPOINT=http://127.0.0.1:4318/v1/traces \
OTEL_TRACES_SAMPLER_ARG=0.01 \
CONFIG_PATH=/etc/sapsan/sapsan.yaml /usr/sbin/sapsan

Секция telemetry.otlp имеет приоритет над этими переменными. Без секции и без OTEL_ENDPOINT экспорт выключен; JSON-логи продолжают записываться в stdout.