Распределённая трассировка backend-приложений

Требования этого документа применяются к backend-приложениям, API, worker-процессам, consumer-процессам и data pipelines. Уровни обязательности определены в корневом README.md.

Распределённая трассировка является рекомендуемой возможностью. Требования OBS-TRACE-002–OBS-TRACE-009 применяются только если проект выбрал сбор трасс или формирует другой OpenTelemetry-сигнал, прямо использующий их общую схему.

OBS-TRACE-001. OpenTelemetry и маршрут доставки

Уровень: SHOULD

Применяется к: решению о сборе распределённых трасс приложения

Приложению следует создавать трассы через OpenTelemetry API/SDK и передавать их по OTLP в OpenTelemetry Collector с последующей доставкой в OpenObserve. При выборе этого канала не следует связывать прикладной код с API OpenObserve.

Обоснование

Стандартный API и промежуточный Collector отделяют инструментирование от конкретного хранилища.

Проверка

• review зависимостей и конфигурации exporter;
• интеграционный тест маршрута приложение → OTLP → Collector → OpenObserve;
• проверка отсутствия прямого exporter в OpenObserve из прикладного кода.

Исключения

Проект MAY не собирать распределённые трассы без ADR.

OBS-TRACE-002. Версия Semantic Conventions

Уровень: MUST

Применяется к: каждому проекту

Проект должен явно фиксировать точную версию OpenTelemetry Semantic Conventions, по которой формируются атрибуты каждого сигнала OpenTelemetry. Общие поля из OBS-TRACE-003 должны иметь одинаковые имя и семантику независимо от версии instrumentation package.

Если разные instrumentation packages технически используют разные версии, проект должен зафиксировать это различие и преобразование общих полей на границе Collector. Обновление версии должно быть управляемым изменением с проверкой переименованных, удалённых и изменивших семантику атрибутов, запросов, dashboards и alerts.

Обоснование

Неконтролируемое изменение схемы нарушает поиск, агрегацию и сопоставимость телеметрии.

Проверка

• проверка project manifest или файла зависимостей;
• проверка версии библиотек инструментирования;
• review миграции схемы при обновлении.

Исключения

Различие версий между сигналами не требует ADR, если преобразование общих полей проверяется.

OBS-TRACE-003. Идентификация ресурса

Уровень: MUST

Применяется к: всем span приложения

Resource должен содержать service.name, service.version и deployment.environment.name. Значения должны поступать из управляемой конфигурации поставки и быть одинаковыми в трассах, логах и событиях ошибок.

Имя сервиса должно быть стабильным между экземплярами и не должно содержать hostname, pod ID или другой идентификатор экземпляра.

Обоснование

Стабильные resource-атрибуты позволяют сопоставлять сигналы и сравнивать версии сервиса.

Проверка

• запрос по resource-атрибутам в OpenObserve;
• сопоставление значений с развёрнутым артефактом;
• автоматический тест конфигурации телеметрии.

Исключения

Не допускаются.

OBS-TRACE-004. Распространение контекста

Уровень: MUST

Применяется к: поддерживаемым синхронным и асинхронным межпроцессным вызовам

Контекст трассировки должен распространяться по W3C Trace Context. W3C Baggage допускается только для заранее утверждённых атрибутов, не содержащих секретные, персональные или высококардинальные данные.

Входящий корректный контекст должен продолжаться; при его отсутствии должен создаваться новый trace. Некорректные заголовки контекста должны игнорироваться с созданием нового trace и не должны приводить к отказу бизнес-операции.

Обоснование

Единый формат обеспечивает сквозную трассу между технологиями и сервисами.

Проверка

• contract-тест HTTP/RPC и используемого брокера сообщений;
• сквозной тест между сервисами разных стеков;
• security-тест некорректного и чрезмерного baggage.

Исключения

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

OBS-TRACE-005. Обязательные границы span

Уровень: MUST

Применяется к: входящим операциям и значимым зависимостям

Span должен создаваться для:

• входящего HTTP/RPC-запроса;
• получения и обработки сообщения;
• выполнения фоновой job;
• исходящего HTTP/RPC-вызова;
• обращения к базе данных, cache и брокеру сообщений.

Внутренняя операция MAY иметь отдельный span, если без него нельзя локализовать существенную задержку или ошибку. Высокочастотная внутренняя операция не должна создавать span без такой диагностической цели.

Span должен завершаться при фактическом завершении соответствующей операции и сохранять корректную родительскую связь.

Обоснование

Единые границы делают критический путь и место отказа видимыми.

Проверка

• интеграционные тесты для каждого типа операции;
• анализ дерева trace в OpenObserve;
• тест контекста при асинхронном и конкурентном выполнении.

Исключения

Недоступная в используемом протоколе или SDK автоматическая граница может проверяться эквивалентным ручным span без привязки бизнес-кода к exporter.

OBS-TRACE-006. Имя и атрибуты span

Уровень: MUST

Применяется к: каждому span

Имя span должно описывать тип операции и иметь ограниченную кардинальность. Оно должно строиться по стабильному шаблону операции и не должно содержать значения из запроса, ресурса или результата выполнения. Конкретный URL, идентификатор сущности, текст SQL и имя пользователя в имени запрещены.

Стандартные атрибуты должны следовать зафиксированной версии Semantic Conventions. Пользовательские атрибуты должны иметь корпоративно согласованный namespace, стабильную семантику и ограниченную кардинальность.

Обоснование

Неконтролируемая кардинальность ухудшает поиск, стоимость хранения и полезность агрегатов.

Проверка

• автоматическая проверка имён и обязательных атрибутов;
• анализ кардинальности в OpenObserve;
• code review ручного инструментирования.

Исключения

Не допускаются для идентификаторов и чувствительных данных в имени span.

OBS-TRACE-007. Статус и регистрация ошибок

Уровень: MUST

Применяется к: неуспешным операциям

Статус span должен отражать технический результат операции в соответствии с OpenTelemetry Semantic Conventions. Исключение должно регистрироваться как span event с нормализованными атрибутами ошибки.

Ожидаемый бизнес-результат и корректный клиентский отказ не должны автоматически помечать span как техническую ошибку. Один экземпляр исключения должен регистрироваться как event не более чем в одном span — операции, в которой он возник или был перехвачен для регистрации. Родительские span MAY отражать техническую ошибку статусом, но не должны повторять тот же event исключения.

Обоснование

Корректная семантика статуса необходима для расчёта error rate и поиска первопричины.

Проверка

• тест успешных, бизнес-, клиентских и серверных исходов;
• анализ статуса и events в OpenObserve;
• проверка отсутствия дублирования одной ошибки.

Исключения

Не допускаются.

OBS-TRACE-008. Sampling и сохранение ошибок

Уровень: MUST

Применяется к: настройке sampling трасс

Sampling должен управляться централизованно и иметь документированную долю для каждой среды или класса операций. Решение должно учитывать родительский sampling-флаг и сохранять репрезентативность данных.

Если политика требует сохранять трассы по результату выполнения, включая ошибку или высокую задержку, решение должно приниматься с помощью tail sampling в Collector. Head sampling в SDK не должен до этого отбрасывать трассы, необходимые такой политике. Sampling не должен использовать чувствительные данные как критерий.

Обоснование

Sampling ограничивает стоимость, но не должен удалять наиболее ценные для расследования трассы.

Проверка

• review конфигурации SDK и Collector;
• статистическая проверка фактической доли;
• тест сохранения ошибочной и медленной трассы.

Исключения

Полное сохранение трасс допустимо при подтверждённой способности платформы обрабатывать максимальный поток.

OBS-TRACE-009. Ограничение влияния телеметрии

Уровень: MUST

Применяется к: SDK и OTLP exporter

Экспорт трасс должен быть асинхронным, пакетным и ограниченным по памяти, размеру очереди и времени ожидания. Недоступность Collector или OpenObserve не должна приводить к отказу бизнес-операции или неограниченному росту ресурсов.

Перед штатным завершением процесс должен предоставить SDK ограниченное время для сброса буфера. Ошибки exporter должны наблюдаться без рекурсивной генерации телеметрии.

Обоснование

Наблюдаемость не должна становиться синхронной критической зависимостью приложения.

Проверка

• тест недоступности и замедления Collector;
• нагрузочный тест;
• тест штатного завершения процесса.

Исключения

Не допускаются.