Skip to content

Distributed tracing (OpenTelemetry) ​

Зачем, если есть метрики и логи ​

Сервис уже отдаёт четыре десятка Prometheus-метрик и структурированные логи. Метрики отвечают на вопрос «сколько доставок медленные», логи — «что произошло в этом процессе». Ни то, ни другое не отвечает на вопрос, который дежурный задаёт после инцидента: почему вот это конкретное уведомление ушло через четыре минуты?

Ответ — причинная цепочка: ingest → группировка → шаг эскалации → вызов провайдера. Метрики её агрегируют и теряют, логи фиксируют звенья, но не связи между ними. Цепочка — это и есть трейс.

Особенность именно этого сервиса: цепочка пересекает границы процессов и времени. Webhook принимает API-под, а эскалацию и доставку выполняет worker-под через минуты, в другом цикле. X-Request-ID их связать не может — это разные запросы. Trace id может.

Включение ​

Трассировка выключена, пока не задан endpoint. Без него Init не ставит ни экспортёра, ни провайдера: спаны становятся no-op'ами глобального провайдера, и цена — один вызов интерфейса на путях, которые и так делали работу. Запускать коллектор, чтобы запустить nxs-anomaly, не нужно.

ПеременнаяОписание
OTEL_EXPORTER_OTLP_ENDPOINTбазовый URL OTLP/HTTP-коллектора, например http://otel-collector:4318; SDK сам добавляет /v1/traces
OTEL_EXPORTER_OTLP_TRACES_ENDPOINTто же, но только для трейсов; имеет приоритет
OTEL_SERVICE_NAMEзначение service.name; по умолчанию nxs-anomaly
OTEL_TRACES_SAMPLER_ARGдоля сэмплирования 0..1; пусто = сэмплировать всё
OTEL_EXPORTER_OTLP_HEADERSзаголовки к коллектору (например, токен), стандартная переменная SDK

В Helm-чарте:

yaml
tracing:
  enabled: true
  endpoint: http://otel-collector.observability:4318
  serviceName: nxs-anomaly-prod   # необязательно
  sampleRatio: ""                 # пусто = всё

Конфиг попадает в общий ConfigMap, то есть и в API, и в worker. Это принципиально: трейс, который отдаёт только половина деплоймента, хуже, чем никакого — он выглядит полным. tracing.enabled: true без endpoint — ошибка рендера, а не деплой, который молча экспортирует в никуда.

Почему по умолчанию сэмплируется всё ​

Обычно always-on — безрассудный дефолт. Здесь нет. Объём запросов этого сервиса — это скорость, с которой ломается чужая инфраструктура, а не пользовательский трафик: спанов десятки в секунду. И ценны как раз редкие медленные трейсы, которые ratio-сэмплер выбрасывает в первую очередь. Ставьте долю, только если объём реально того требует.

Решение вышестоящего сервиса уважается: сэмплер ParentBased.

Что инструментировано ​

СпанГдеКлючевые атрибуты
<METHOD> <категория>HTTP-middleware, корневой спан запросаurl.path, http.response.status_code, client.address
ingest.alertengine.IngestAlertnxs.source, nxs.alert_group_id
worker.cycleengine.RunWorkerCyclenxs.stage.<этап>_ms по каждому этапу, счётчики групп и уведомлений
delivery.<канал>engine.deliverNotificationViaAdapternxs.notification_id, nxs.channel, nxs.alert_group_id, nxs.retry_count, nxs.outcome, nxs.provider_status; link на трейс ingest'а

Как трейс переживает запись в базу ​

Жизнь алерта — не одна цепочка вызовов. Webhook принимает API-под и отвечает; через минуты worker-под забирает группу из таблицы и доставляет. Между ними нет вызова — только строка, поэтому никакая передача context.Context их не свяжет.

Решение то же, что применяют для очередей: на входе span context сериализуется в строку (trace_parent в JSONB группы алертов, поле Extra — без миграции, потому что по нему никто не ищет и не индексирует), а на выходе присоединяется к спану доставки как link. Поле пишется, только когда трассировка включена, так что каноническая форма группы у остальных не меняется.

Путь целиком: ingest.alert → trace_parent на группе → trace_parent в payload уведомления → tracing.StartLinked в deliverNotificationViaAdapter. Группа, созданная до включения трассировки, просто не имеет поля — доставка получает обычный спан без ссылки, без ветвлений на стороне вызова.

Осознанные пропуски:

  • /live, /health, /ready, /metrics не трассируются. Их вечно опрашивают kubelet и Prometheus; спан на каждую проверку живости — чистый шум, который вытеснит трейсы, ради которых всё затевалось.
  • Имя спана — категория маршрута, а не путь. В пути лежат идентификаторы сущностей; иначе у каждой группы алертов был бы свой уникальный span name и группировка в бэкенде трейсов перестала бы работать. Полный путь остаётся атрибутом url.path.
  • У этапов worker-цикла нет дочерних спанов — только длительности атрибутами. Цикл всегда выполняет одну и ту же фиксированную последовательность этапов, так что дюжина дочерних спанов на каждый тик сказала бы ровно то же, что и длительности, но умножила бы объём спанов простаивающего деплоймента на частоту тиков.
  • Провалившаяся доставка помечается Error статусом, но не RecordError. Это ожидаемое состояние мира, а не баг.

Связь трейса с остальным ​

Trace id — это ключ соединения, и он положен туда, где переживёт сам трейс:

  • X-Trace-ID в ответе. Тот, кто жалуется «мой вебхук тормозил», может назвать id, а не время, когда ему показалось.
  • Логи. Access-лог (http_request) и delivery_attempt содержат trace_id.
  • Аудит. Колонка trace_id (миграция 0025) рядом с request_id из 0022, и фильтр GET /api/v1/audit?trace_id=....

Последнее — не дублирование. Спаны выпадают из коллектора через дни или недели, а запись аудита живёт столько, сколько велит retention. Найти строку через полтора месяца и увидеть в ней trace id — это то, как вопрос «кто это подтвердил и что система делала в тот момент» остаётся отвечаемым уже после того, как спаны исчезли.

Трейсы — копия операционных данных вне PostgreSQL. Пользовательский erase не может удалить их из внешнего collector/backend; задайте retention и доступы там отдельно. Атрибуты не должны содержать payload алерта, токены и адреса доставки. Полная карта границ — DATA_INVENTORY.md.

Ограничения ​

  • Спан доставки связан с ingest ссылкой (link), а не родительством. Это осознанный выбор, а не недоделка. Родительство означало бы, что четырёхминутный спан лежит внутри HTTP-запроса, завершившегося за двадцать миллисекунд, и что доставка покидает трейс своего worker-цикла. Ссылка сохраняет оба вида: доставка принадлежит циклу, а «что её вызвало» — в одном переходе. В UI трейсов это раздел Links, а не вложенность.
  • SSRF-guard на экспортёр не распространяется. NXS_ANOMALY_BLOCK_PRIVATE_WEBHOOKS защищает адреса доставки, а коллектор — это ваш собственный адрес, обычно приватный внутрикластерный. Так и задумано.
  • Ошибка построения экспортёра не фатальна. Логируется tracing_exporter_failed, сервис стартует. Сервис, который не поднимается из-за отсутствующего коллектора трейсов, превратил проблему наблюдаемости в аварию.
  • Проблемы самого SDK видны как otel_error в логе — без этого коллектор, отвергающий каждый батч, выглядит ровно как сервис, не производящий спанов.

Проверка ​

bash
# поднять коллектор, который просто печатает всё, что получил
docker run --rm -p 4318:4318 otel/opentelemetry-collector:latest

export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
./nxs-anomaly serve

В логе на старте появится tracing_enabled. Дальше — отправить алерт и посмотреть на X-Trace-ID в ответе:

bash
curl -si -X POST localhost:8080/integrations/v1/webhook/<key> \
  -d '{"title":"probe","severity":"warning"}' | grep -i x-trace-id

nxs-anomaly · Documentation