Перейти к содержанию

Телеметрия frontend-приложений

Требования этого документа применяются к browser-side Real User Monitoring (RUM), распределённым трассам и сопутствующей телеметрии frontend-приложений профилей CSR, SSR, SSG и edge по frontend/rendering-profiles.md. Телеметрия SSR- и edge-runtime регулируется backend-требованиями наблюдаемости. Сбор ошибок регулируется документом frontend/error-collection.md. Уровни обязательности определены в корневом README.md.

Browser-side RUM и распределённые трассы являются рекомендуемыми возможностями. Требования FE-OBS-003–FE-OBS-008 применяются только к выбранным проектом каналам frontend-телеметрии.

FE-OBS-001. Канал RUM и Web Vitals

Уровень: SHOULD

Применяется к: решению о сборе RUM и Web Vitals

Приложению следует инструментировать Core Web Vitals и выбранные проектом критичные пользовательские операции через OpenTelemetry Browser SDK. Для операций следует использовать стабильные низкокардинальные имена и выбирать их для проверки SLI либо диагностики конкретного сценария; собирать каждое DOM-событие не следует. Маршрут или экран следует представлять полем view.name со значением шаблона маршрута, а не фактического URL. Для передачи следует использовать маршрут FE-OBS-002 и отделять RUM от канала ошибок FE-ERR-001.

Обоснование

RUM отражает реальный пользовательский результат и производительность, которые недоступны серверной телеметрии.

Проверка

  • review инструментирования OpenTelemetry Browser SDK;
  • тест появления Web Vitals и разрешённых действий в OpenObserve;
  • проверка разделения RUM и событий ошибок.

Исключения

Проект MAY не собирать RUM без ADR. Отсутствующий в SDK Web Vital MAY измеряться эквивалентным проверяемым инструментом.

FE-OBS-002. Канал распределённых трасс

Уровень: SHOULD

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

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

Обоснование

Промежуточный Collector отделяет инструментирование от хранилища и унифицирует маршрут с серверными трассами по OBS-TRACE-001.

Проверка

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

Исключения

Проект MAY не собирать browser traces без ADR.

FE-OBS-003. Идентификация ресурса и выпуска

Уровень: MUST

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

RUM и трассы должны использовать значения service.name, service.version и deployment.environment.name, совпадающие с метаданными артефакта по DEV-BUILD-003 и с атрибутами событий ошибок по FE-ERR-005.

Имя сервиса должно быть стабильным между выпусками и не должно содержать commit SHA, hash сборки или иной идентификатор выпуска.

Обоснование

Общие идентификаторы позволяют сопоставлять ошибки, RUM и трассы одного выпуска и определять регрессию.

Проверка

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

Исключения

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

FE-OBS-005. Корреляция сессии

Уровень: MAY

Применяется к: данным о сессии

Проект MAY использовать поле session.id, согласованное между RUM, трассами и событиями ошибок, если это необходимо для диагностики заявленного сценария. Значение должно быть псевдонимным, иметь определённую границу ротации и не должно совпадать с идентификатором учётной записи или устройства.

session.id должен считаться персональными данными, если он позволяет выделить или связать действия пользователя. Его сбор, срок хранения и доступ должны соответствовать классификации данных и FE-OBS-007.

Обоснование

Согласованный идентификатор связывает пользовательский опыт и ошибки в одну сессию без использования идентификатора учётной записи.

Проверка

  • проверка согласованности session.id между сигналами;
  • review источника и границы ротации;
  • проверка отличия от идентификатора учётной записи и устройства.

Исключения

Не применяются. Отсутствие идентификаторов не является отклонением.

FE-OBS-006. Ограниченная кардинальность и объём

Уровень: MUST

Применяется к: именам и атрибутам RUM и трасс

Имена маршрутов и span должны строиться по стабильному шаблону маршрута и не должны содержать фактический путь с идентификаторами, query string, текст ошибки или случайные значения. Объём собираемой телеметрии должен ограничиваться sampling, rate limit или исключением малозначимых событий.

Высокочастотные события должны ограничиваться агрегацией или sampling. События ошибок собираются отдельным каналом по FE-ERR-001 и не должны зависеть от sampling RUM.

Обоснование

Высокая кардинальность и неограниченный объём повышают стоимость и нарушают полезность агрегатов; это аналог OBS-MET-006.

Проверка

  • статическая проверка имён маршрутов и span;
  • анализ кардинальности и объёма в OpenObserve;
  • тест динамических URL и идентификаторов.

Исключения

Exemplar может содержать разрешённую связь с trace, если OpenObserve хранит её отдельно от набора атрибутов.

FE-OBS-007. Согласие и приватность

Уровень: MUST

Применяется к: сбору телеметрии о пользователе

Сбор RUM, идентификация сессии и пользователя, а также иное отслеживание должны соответствовать принятой политике согласия. До получения согласия приложение должно ограничить сбор данными, не идентифицирующими пользователя, или полностью приостановить соответствующие каналы.

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

Обоснование

Отслеживание пользовательского поведения без согласия нарушает приватность и регуляторные требования.

Проверка

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

Исключения

Минимальный технический сбор, не идентифицирующий пользователя и необходимый для безопасности, допускается по утверждённой политике.

FE-OBS-008. Отказоустойчивость SDK телеметрии

Уровень: MUST

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

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

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

Обоснование

Телеметрия не должна становиться причиной деградации приложения.

Проверка

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

Исключения

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