Trace-exporter

Установка экспортера трейсов

Контекст

Trace Exporter - это инструмент автоматического сбора распределённых трассировок сервисов и приложений, использующий технологию eBPF для перехвата и анализа системных вызовов непосредственно на уровне ядра операционной системы, инструмент собирает подробные трассировки запросов без какого-либо вмешательства в логику приложения. Ключевым преимуществом Trace Exporter является неинвазивный способ развёртывания: установка не требует внесения изменений в кодовую базу целевого сервиса и встраивания сторонних библиотек, а также перезапуска работающих процессов.

Сбор трассировок начинается сразу после запуска инструмента. Это делает Trace Exporter универсальным решением для инструментирования приложений.

Установка и конфигурация trace-exporter

Для развёртывания trace-exporter используются два компонента: исполняемый бинарный файл и файл конфигурации в формате YAML. Для запуска trace-exporter требуются root права.

Системные требования для функционирования trace-exporter

Ядро unix от 5.8 Для проверки версия ядра unix используйте команду:

uname -r

BTF (BPF Type Format):

Должен быть включён в ядре — файл /sys/kernel/btf/vmlinux должен существовать
Либо наличие capabilities: CAP_BPF, CAP_PERFMON, CAP_SYS_PTRACE, CAP_NET_ADMIN Команды для проверки: Проверка наличия BTF: ls /sys/kernel/btf/vmlinux

Проверка поддержки eBPF в ядре: grep CONFIG_BPF /boot/config-$(uname -r)

 CONFIG_BPF=y
 CONFIG_BPF_SYSCALL=y
 CONFIG_BPF_JIT=y
 CONFIG_BPF_JIT_ALWAYS_ON=y

Проверка текущих capabilities: capsh --print

  Current: cap_sys_ptrace,cap_net_admin,cap_bpf,cap_perfmon=eip
  # В строке Current: должны присутствовать все четыре: cap_bpf, cap_perfmon, cap_sys_ptrace, cap_net_admin

Конфигурационный файл

Пример конфигурационного файла для trace-exporter:

log_level: warn
discovery:
  services:
    -  exe_path: ".*"

ebpf:
  context_propagation: "all"
  track_request_headers: true
  enable_http: true
  enable_tcp: true
  enable_grpc: true
  enable_sql: true
  enable_redis: true
  enable_kafka: true
  enable_outgoing_http: true
  wakeup_len: 128
  batch_length: 100
  batch_timeout: 2s
  high_request_volume: false
otel:
  propagators: tracecontext
enforce_sys_caps: true
traces:
  max_queue_size: 1500
otel_traces_export:
  endpoint: "http://127.0.0.1:9702/api/v1/write/traces"
  # instrumentations: ["http","grpc","sql"]
  max_export_batch_size: 512
  export_timeout: 5s
  interval: 5s

В приведённой выше конфигурации trace-exporter осуществляет сбор трейсов с максимально возможного числа объектов на целевой системе.

Для ограничения работы экспортера трейсов необходимо использовать раздел discovery: также можно присвоить кастомное имя конкретному сервису.

Пример ограничения настроек по сервисам и его наименования:

discovery:
  services:
    -  exe_path: "usr/sbin/nginx"
       name: "ngixn-web-server"
    -  exe_path: "/usr/bin/python3.11" 
       name: "python-service"

exe_path можно определить по PID процесса при помощи данной команды:

readlink -f /proc/<PID>/exe
# или
ls -la /proc/<PID>/exe

Настройки ограничений работы экспортера для различных протоколов:

 # Собирать HTTP-заголовки запросов в трейсы
 track_request_headers: false
 # Перехватывать gRPC-вызовы
 enable_grpc: true
 # Перехватывать SQL-запросы
 enable_sql: true
 # Перехватывать Redis-команды
 enable_redis: false
 # Перехватывать Kafka produce/consume операции
 enable_kafka: false
 # Перехватывать исходящие HTTP-запросы приложения
 enable_outgoing_http: false
 # Перехватывать входящие HTTP-запросы приложения
 enable_http: false
 # Трассировки на уровне TCP
 enable_tcp: false
 # Сколько событий накапливается в буфере ядра перед пробуждением userspace

Данные параметры необходимо комбинировать с настройкой разделов otel_traces_export: instrumentations Пример:

  otel_traces_export:
    endpoint: "http://127.0.0.1:9702/api/v1/write/traces"
    instrumentations: ["http","grpc","sql","tcp"]

Настройка параметра отправки трейсов:

wakeup_len: - Сколько сообщений должно накопиться в eBPF ring buffer ядра, прежде чем отправить сигнал пробуждения в userspace. Более высокое значение снижает нагрузку на CPU при высоком трафике, но увеличивает задержку обработки при низком трафике
batch_length: - Сколько событий (трейсов/метрик) накапливается на начальном этапе eBPF-пайплайна перед передачей на следующий этап обработки.
batch_timeout: - Таймаут для отправки batch даже если не набралось batch_length
high_request_volume: - доступны значения True или false. необходимо установить в значение True при RPS выше 100
max_queue_size: - Размер внутренней in-memory очереди трейсов перед отправкой. При переполнении новые трейсы дропаются.
max_export_batch_size: - Максимальное количество спанов в одном HTTP-запросе к экспортёру (должен быть <= max_queue_size).
export_timeout: - Таймаут одной попытки отправки батча в экспортёр. При превышении — батч считается неудачным.
interval: - Интервал между попытками экспорта накопленных спанов.

Конфигурация `trace-exporter.service`

Для удобства запуска экспортера трейсов екомендуется зарегистрировать его в качестве systemd-сервиса.

Создайте файл trace-exporter.service в директории /etc/systemd/system/ Пример файла сервиса:

[Unit]
Description=trace-exporter
Wants=basic.target
After=basic.target network.target
[Service]
WorkingDirectory=/path/to/
ExecStartPre=-/bin/chmod +x /path/to/trace-exporter
ExecStart=/path/to/trace-exporter -config your_config.yaml
ExecReload=/bin/kill -HUP
KillMode=process
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.targe

После чего trace-exporter может быть запущен при помощи команды:

service trace-exporter start

После внесения изменений в trace-exporter.service . необхоимо выполнить команду:

systemctl daemon-reload

Пошаговая установка

Загрузить на хост бинарный файл trace-exporter. После чего сделать его исполняемым.

chmod+x trace-exporter

Загрузить конфигурационный файл. Внести изменения в конфигуарции при необходимости
Сконфигурировать trace-exporter.service