Сбор ошибок backend-приложений¶
Требования этого документа применяются к backend-приложениям, API,
worker-процессам, consumer-процессам и data pipelines. Уровни обязательности
определены в корневом README.md.
Сбор событий ошибок в GlitchTip является рекомендуемой возможностью.
Требования OBS-ERR-002–OBS-ERR-009 применяются только если проект выбрал
этот канал.
OBS-ERR-001. Канал сбора ошибок¶
Уровень: SHOULD
Применяется к: решению о централизованном сборе расследуемых ошибок
Приложению следует отправлять расследуемые события ошибок через совместимый Sentry SDK в GlitchTip. При выборе этого канала не следует связывать прикладной код с внутренним API или моделью хранения GlitchTip.
Отправку события в GlitchTip не следует считать заменой корректного результата операции или статуса активного span. Отдельную запись той же ошибки в диагностический лог следует создавать только для необходимого дополнительного контекста или диагностики при недоступности GlitchTip.
Обоснование¶
Sentry-протокол сохраняет переносимость интеграции, а разделение сигналов предотвращает неоднозначность и избыточный объём.
Проверка¶
- review зависимостей и DSN-конфигурации;
- интеграционный тест появления события в GlitchTip;
- проверка отсутствия прямых вызовов API GlitchTip.
Исключения¶
Проект MAY не интегрировать GlitchTip без ADR, если расследуемые ошибки обнаруживаются и диагностируются другим проверяемым каналом.
OBS-ERR-002. Автоматически собираемые ошибки¶
Уровень: MUST
Применяется к: верхней границе процесса или операции
Автоматически должны собираться:
- необработанные исключения;
- panic и crash, доступные SDK до завершения процесса;
- ошибки framework или middleware, дошедшие до верхнего уровня.
Интеграция должна устанавливаться в общей точке обработки, а не дублироваться в каждом handler.
Автоматический сбор не должен повторно отправлять ошибку, уже явно отправленную на нижнем уровне.
Обоснование¶
Центральный перехват обеспечивает полный и единообразный сбор непредвиденных отказов.
Проверка¶
- интеграционный тест каждого поддерживаемого типа отказа;
- проверка единственного события на одну ошибку;
- review инициализации SDK и framework integration.
Исключения¶
Crash, который технически невозможно отправить до остановки процесса, должен фиксироваться средствами среды выполнения или платформы и иметь отдельный способ обнаружения.
OBS-ERR-003. Явно собираемые обработанные ошибки¶
Уровень: MUST
Применяется к: вызовам явной отправки события
Обработанная ошибка должна отправляться явно только тогда, когда она требует расследования или действия команды. Ожидаемые ошибки валидации, авторизации, отсутствия ресурса, конфликт бизнес-правил и успешно восстановленные временные ошибки отправляться не должны, если отдельный проектный контракт не классифицирует их как инцидент.
Решение об отправке должно основываться на стабильном классе ошибки, а не на сравнении текста сообщения.
Обоснование¶
GlitchTip должен содержать расследуемые события, а не поток штатных отрицательных результатов.
Проверка¶
- unit-тест классификации ошибок;
- анализ доли и типов событий в GlitchTip;
- code review явных вызовов Sentry SDK.
Исключения¶
Временный расширенный сбор допускается для ограниченного расследования с владельцем, средой и сроком отключения.
OBS-ERR-004. Корреляция с трассой¶
Уровень: MUST
Применяется к: событию ошибки внутри активной трассы
Событие должно содержать trace_id и span_id активного span как доступные для поиска атрибуты. Формат и семантика идентификаторов должны соответствовать OBS-LOG-004, а значения — совпадать с трассой и связанными логами. Если используются request_id или correlation_id, они также должны передаваться как структурированные атрибуты.
При отсутствии активной трассы запрещено создавать фиктивные идентификаторы.
Обоснование¶
Корреляция связывает контекст исключения в GlitchTip с полным ходом операции в OpenObserve.
Проверка¶
- сквозной тест GlitchTip, трассы и логов;
- поиск одного тестового отказа по каждому идентификатору;
- тест сохранения контекста при асинхронном выполнении.
Исключения¶
Не допускаются при наличии активного span.
OBS-ERR-005. Идентификация приложения и выпуска¶
Уровень: MUST
Применяется к: каждому событию ошибки
Событие должно содержать доступные для поиска атрибуты service.name, service.version и deployment.environment.name. Их значения должны совпадать с OTel resource.
Версия выпуска должна однозначно сопоставляться с Git commit и развёрнутым артефактом. Должна быть доступна информация, необходимая для deobfuscation или symbolication применяемого стека.
Обоснование¶
Расследование и определение регрессии требуют точного сопоставления ошибки с кодом и окружением.
Проверка¶
- сравнение события с OTel resource и метаданными артефакта;
- проверка release в GlitchTip;
- тест symbolication или source map для применимого стека.
Исключения¶
Не допускаются для production.
OBS-ERR-006. Диагностический контекст¶
Уровень: MUST
Применяется к: каждому событию ошибки
Событие должно содержать error.type, сообщение, stack trace при его наличии и стабильный event.name. error.type должен определять класс ошибки, а event.name — тип наблюдаемого события. Дополнительный контекст должен передаваться типизированными tags или extra-полями с ограниченным объёмом.
Полные тела запросов и ответов, содержимое очередей, локальные переменные и произвольные объекты не должны прикладываться автоматически.
Обоснование¶
Минимальный структурированный контекст достаточен для группировки и диагностики без неконтролируемого объёма.
Проверка¶
- review настройки SDK;
- автоматический тест состава тестового события;
- анализ размера событий и кардинальности tags.
Исключения¶
Расширенный контекст допускается только в непроизводственной среде с синтетическими данными.
OBS-ERR-007. Защита чувствительных данных¶
Уровень: MUST
Применяется к: событиям, breadcrumbs, attachments, user context и stack context
Запрещено отправлять в GlitchTip секреты, пароли, токены, cookies, заголовки авторизации, приватные ключи, полные платёжные данные и персональные данные без утверждённого маскирования.
SDK должен использовать allowlist допустимых заголовков и полей. Фильтрация должна выполняться в приложении до отправки события; серверная фильтрация является только дополнительным защитным слоем.
Обоснование¶
Автоматический сбор контекста SDK может незаметно передать чувствительные данные во внешнюю по отношению к процессу систему.
Проверка¶
- тест before-send hook или эквивалентного фильтра;
- security review настроек request, user и breadcrumbs;
- контролируемая проверка тестового события в GlitchTip.
Исключения¶
Секреты, аутентификационные данные и полные платёжные данные — без исключений. Персональные данные возможны только по утверждённой политике классификации и маскирования.
OBS-ERR-008. Группировка и отпечаток ошибки¶
Уровень: SHOULD
Применяется к: настройке grouping
По умолчанию следует использовать группировку SDK/GlitchTip по типу ошибки и stack trace. Ручной fingerprint допускается только для исправления подтверждённо неверной группировки и должен строиться из стабильных низкокардинальных признаков.
Динамический текст, идентификаторы пользователей, запросов и сущностей не должны входить в fingerprint.
Обоснование¶
Стабильная группировка превращает повторения одной причины в один расследуемый issue.
Проверка¶
- тест объединения повторов и разделения разных причин;
- code review ручных fingerprints;
- анализ роста новых групп в GlitchTip.
Исключения¶
Не допускаются для использования высококардинальных значений.
OBS-ERR-009. Отказоустойчивость SDK¶
Уровень: MUST
Применяется к: отправке событий ошибок
Sentry SDK должен отправлять события асинхронно, с конечными лимитами очереди, повторов и времени ожидания. Недоступность GlitchTip не должна изменять результат бизнес-операции или приводить к неограниченному потреблению ресурсов.
Для crash и штатного завершения процесс должен предоставить SDK ограниченное время на отправку. Потеря события из-за недоступности GlitchTip должна быть наблюдаема через отдельную ограниченную диагностическую запись или метрику без рекурсивной отправки ошибки.
Обоснование¶
Система сбора ошибок не должна становиться критической зависимостью приложения.
Проверка¶
- тест недоступности и замедления GlitchTip;
- нагрузочный тест очереди SDK;
- тест завершения процесса.
Исключения¶
Не допускаются.