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