Skip to content

Распределённая трассировка (OpenTelemetry) ​

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

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

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

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

Включение ​

Трассировка выключена, пока не задан endpoint. Без него Init не устанавливает ни exporter, ни provider: spans становятся no-op на глобальном provider, а затраты сводятся к одному вызову интерфейса на уже работающих путях. Для запуска nxs-anomaly не требуется collector.

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

В Helm chart:

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

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

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

Постоянный сбор всех spans обычно неосторожен. Здесь это не так. Объём запросов этого сервиса определяется тем, как часто ломается чужая инфраструктура, а не пользовательским трафиком: spans поступают десятками в секунду. Ценнее всего именно редкие медленные traces, которые вероятностная выборка отбрасывает в первую очередь. Задавайте долю только при реальной необходимости по объёму.

Решение вышестоящего сервиса учитывается: используется sampler ParentBased.

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

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

Как trace переживает запись в БД ​

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

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

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

Сознательные исключения:

  • /live, /health, /ready и /metrics не трассируются. Kubelet и Prometheus опрашивают их постоянно; span на каждую liveness probe создавал бы шум, вытесняющий полезные traces.
  • Имя span определяется категорией маршрута, а не его путём. В путях есть идентификаторы объектов; иначе каждая группа алертов создавала бы уникальное имя span, ломая группировку в tracing backend. Полный путь сохраняется в атрибуте url.path.
  • У этапов worker cycle нет дочерних spans, только длительности в атрибутах. Цикл всегда выполняет одну фиксированную последовательность; десяток дочерних spans на tick повторял бы информацию длительностей и умножал объём spans простаивающей установки на частоту tick.
  • Неудачная доставка получает статус Error, но не RecordError. Это ожидаемое состояние внешнего мира, а не ошибка программы.

Как trace связывается с остальной системой ​

Trace ID — ключ связи; он записывается туда, где переживёт сам trace:

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

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

Traces — копия эксплуатационных данных вне PostgreSQL. Удаление данных пользователя не удалит их из внешнего collector или backend; срок хранения и доступ там задаются отдельно. В атрибуты нельзя помещать payload алертов, токены или адреса доставки. Полная карта границ приведена в DATA_INVENTORY.md.

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

  • Span доставки связан с приёмом через link, а не через parent. Это осознанный выбор. Родительская связь означала бы четырёхминутный span внутри HTTP-запроса, завершившегося за двадцать миллисекунд, и выводила бы доставку из trace её worker cycle. Link сохраняет обе интерпретации: доставка принадлежит своему циклу, а её причина находится в одном переходе. В UI трассировки это отображается в Links, а не как вложенность.
  • SSRF-защита не применяется к exporter.NXS_ANOMALY_BLOCK_PRIVATE_WEBHOOKS защищает адреса доставки; collector — ваш собственный адрес, обычно приватный внутрикластерный. Так и задумано.
  • Ошибка создания exporter не фатальна. В лог пишется tracing_exporter_failed, сервис запускается. Отказ запуска из-за отсутствия collector превращал бы проблему наблюдаемости в недоступность сервиса.
  • Внутренние проблемы SDK появляются в логе как otel_error: иначе collector, отклоняющий все batches, выглядел бы как сервис, не создающий spans.

Проверка работы ​

bash
# collector, который просто печатает полученные данные
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