Сбор ошибок frontend-приложений¶

Требования этого документа применяются к сбору ошибок browser-части frontend-приложений профилей CSR, SSR, SSG и edge по frontend/rendering-profiles.md. Ошибки SSR-, SSG build- и edge-runtime регулируются документом backend/error-collection.md. Уровни обязательности определены в корневом README.md.

Сбор browser-side ошибок в GlitchTip является рекомендуемой возможностью. Требования FE-ERR-002, FE-ERR-005–FE-ERR-007 и FE-ERR-009 применяются только если проект выбрал этот канал.

FE-ERR-001. Канал сбора ошибок¶

Уровень: SHOULD

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

Приложению следует отправлять расследуемые события ошибок через совместимый Sentry Browser SDK в GlitchTip. При выборе этого канала не следует связывать прикладной код с внутренним API или моделью хранения GlitchTip.

Отправку события в GlitchTip не следует считать заменой пользовательского сообщения или единственным результатом операции.

Обоснование¶

Sentry-протокол сохраняет переносимость интеграции и единообразие с backend по OBS-ERR-001.

Проверка¶

review зависимостей и DSN-конфигурации;
интеграционный тест появления события в GlitchTip;
проверка отсутствия прямых вызовов API GlitchTip.

Исключения¶

Проект MAY не интегрировать GlitchTip без ADR, если расследуемые ошибки обнаруживаются и диагностируются другим проверяемым каналом.

FE-ERR-002. Автоматически собираемые ошибки¶

Уровень: MUST

Применяется к: верхней границе выполнения в браузере

Автоматически должны собираться:

необработанные исключения;
отклонённые и необработанные промисы (unhandledrejection);
ошибки рендеринга, перехваченные механизмом error boundary framework или эквивалентной верхней границей.

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

Обоснование¶

Центральный перехват обеспечивает полный и единообразный сбор непредвиденных отказов в асинхронной среде браузера.

Проверка¶

интеграционный тест каждого поддерживаемого типа отказа;
проверка единственного события на одну ошибку;
review инициализации SDK и error boundary.

Исключения¶

Отказ до инициализации SDK должен фиксироваться отдельным механизмом, например ранним обработчиком, и быть явно задокументирован.

FE-ERR-005. Идентификация приложения, выпуска и ошибки¶

Уровень: MUST

Применяется к: каждому событию ошибки

Событие должно содержать доступные для поиска атрибуты service.name, service.version и deployment.environment.name. Их значения должны совпадать с атрибутами RUM и трасс по FE-OBS-003 и с метаданными артефакта по DEV-BUILD-003.

Событие должно содержать стабильные event.name и error.type. event.name должен определять тип наблюдаемого события, а error.type — класс ошибки. Динамический текст и идентификаторы экземпляров не должны использоваться как значения этих полей.

Обоснование¶

Расследование и определение регрессии требуют точного сопоставления ошибки с кодом, окружением, классом и другими сигналами.

Проверка¶

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

Исключения¶

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

FE-ERR-006. Корреляция с трассой и сессией¶

Уровень: MUST

Применяется к: событию ошибки внутри активной трассы или сессии

Событие внутри активной трассы должно содержать trace_id и span_id. Идентификатор сессии должен передаваться только при его наличии и допустимости по FE-OBS-005 и FE-OBS-007. Формат идентификаторов трассы должен соответствовать OBS-LOG-004 и совпадать с браузерной трассой.

При отсутствии активной трассы запрещено создавать фиктивные идентификаторы.

Обоснование¶

Корреляция связывает контекст исключения в GlitchTip с ходом операции в OpenObserve и с сессией пользователя.

Проверка¶

сквозной тест GlitchTip, трассы и RUM;
поиск одной тестовой ошибки по trace_id;
тест отсутствия фиктивных идентификаторов без активной трассы.

Исключения¶

Идентификатор сессии может отсутствовать по FE-OBS-007; это не освобождает от передачи идентификаторов активной трассы.

FE-ERR-007. Защита чувствительных данных¶

Уровень: MUST

Применяется к: событиям, breadcrumbs, user context и дополнительным данным

Запрещено отправлять в GlitchTip секреты, пароли, токены, cookies, заголовки авторизации, полные платёжные данные и персональные данные без утверждённого маскирования. URL с токенами в фрагменте или query, тела запросов и ответы, а также введённые пользователем данные должны удаляться или маскироваться до отправки в hook before-send или эквивалентном фильтре.

Обоснование¶

Автоматический сбор контекста SDK может незаметно передать чувствительные данные во внешнюю систему.

Проверка¶

тест before-send фильтра с маркерами чувствительных данных;
security review breadcrumbs и user context;
контролируемая проверка тестового события в GlitchTip.

Исключения¶

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

FE-ERR-009. Отказоустойчивость SDK¶

Уровень: MUST

Применяется к: отправке событий ошибок

Sentry Browser SDK должен отправлять события асинхронно, с конечными лимитами очереди и времени ожидания. Недоступность GlitchTip не должна блокировать взаимодействие пользователя или приводить к неограниченному росту ресурсов.

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

Обоснование¶

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

Проверка¶

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

Исключения¶

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