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-чарте:
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.alert | engine.IngestAlert | nxs.source, nxs.alert_group_id |
worker.cycle | engine.RunWorkerCycle | nxs.stage.<этап>_ms по каждому этапу, счётчики групп и уведомлений |
delivery.<канал> | engine.deliverNotificationViaAdapter | nxs.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в логе — без этого коллектор, отвергающий каждый батч, выглядит ровно как сервис, не производящий спанов.
Проверка
# поднять коллектор, который просто печатает всё, что получил
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 в ответе:
curl -si -X POST localhost:8080/integrations/v1/webhook/<key> \
-d '{"title":"probe","severity":"warning"}' | grep -i x-trace-id