Как использовать встроенный в GitLab сервис отслеживания ошибок Sentry

Sentry — это популярная платформа для отслеживания ошибок, которая позволяет в режиме реального времени отслеживать проблемы в производственных средах. Функция отчетов об ошибках GitLab позволяет переносить отчеты Sentry на платформу управления версиями, предлагая централизованное представление, объединяющее ошибки Sentry и проблемы GitLab.

Первоначально эта функция основывалась на интеграции с существующей службой Sentry, будь то официальный Sentry.io или ваш собственный сервер. Это изменилось с GitLab 14.4, который добавил облегченный Sentry-совместимый бэкэнд в сам GitLab. Вам больше не нужна фактическая установка Sentry, чтобы получать отчеты об ошибках в GitLab.

Вот как начать работу с интегрированной серверной частью Sentry. Прежде чем мы продолжим, стоит отметить, что эта возможность может вам не подойти, если вы уже знакомы с панелью управления Sentry. Серверная часть GitLab представляет собой базовое решение, которое отображает ошибки в виде простого списка. Это лучше всего подходит для небольших приложений, где вам не нужны накладные расходы на управление отдельным проектом Sentry.

Начиная

Создайте новый проект на GitLab.com или на собственном сервере GitLab. Перейдите в «Настройки» > «Мониторинг» на боковой панели вашего проекта, а затем разверните раздел «Отслеживание ошибок». Установите флажок «Включить отслеживание ошибок». Убедитесь, что для переключателя «Error tracking backend» установлено значение «GitLab». Нажмите синюю кнопку «Сохранить изменения», чтобы продолжить.

Страница перезагрузится. Теперь вы можете снова развернуть раздел «Отслеживание ошибок», чтобы показать строку DSN. Этот URL-адрес используется для настройки вашей клиентской библиотеки Sentry для отправки событий на сервер GitLab.

Настройка клиента

Теперь вы можете добавить Sentry в свой код. Вот базовый пример использования официальной клиентской библиотеки Sentry для Node.js. Вы можете установить пакет, запустив npm install @sentry/node. Документацию по всем доступным клиентам можно получить в Sentry.

const sentry = require("@sentry/node");
 
sentry.init({
    dsn: "https://glet_abc123@gitlab.example.com/api/v4/error_tracking/collector/1"
});

Замените значение DSN строкой, которую вы скопировали из пользовательского интерфейса GitLab. Часть перед @ — это специальный токен аутентификации, который разрешает доступ к серверу GitLab. Оставшаяся часть состоит из уникальной конечной точки API приема отслеживания ошибок для вашего проекта.

Тестирование вашей интеграции

Официальные клиентские библиотеки Sentry начинают перехватывать необработанные ошибки, как только они настроены с помощью DSN. Если какой-либо следующий код выдает ошибку, которую вы не улавливаете, о событии будет сообщено на ваш сервер GitLab.

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

Sentry.captureException(new Error("Sentry test"));

Используйте боковую панель вашего проекта в веб-интерфейсе GitLab, чтобы перейти на страницу «Монитор» > «Отслеживание ошибок». Ошибка, которую вы зафиксировали, должна появиться в списке. Щелкните его запись, чтобы просмотреть полный отчет и трассировку стека.

Проблемы GitLab можно создавать из отчетов с помощью синей кнопки «Создать задачу» в правом верхнем углу. Это позволяет поручить работу по исправлению членам команды и начать обсуждение проблемы. Проблема сохранит ссылку на отчет об ошибке, а трассировка стека будет отображаться под описанием проблемы.

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

Ограничения

Интегрированный бэкенд GitLab Sentry в настоящее время предназначен для небольших ситуаций, когда развертывание Sentry кажется слишком сложным или ненужным. Полная платформа Sentry представляет собой обширную систему, для настройки и обслуживания которой может потребоваться время. Интеграция с GitLab — это всего лишь один флажок в настройках вашего проекта, но за эту простоту приходится платить.

Список отслеживания ошибок — это ваш единственный просмотр отчетов. В настоящее время вы не можете отображать их в виде графиков, просматривать изменения объемов отчетов с течением времени или фильтровать по отдельным пользователям или клиентам. Подробная информация, отображаемая пользовательским интерфейсом Sentry, такая как данные браузера и сервера, в настоящее время не поддерживается и не отображается нигде в GitLab.

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

Поскольку GitLab реализует основные функции Sentry API, он совместим с большинством основных SDK и клиентских библиотек. Начиная с GitLab 14.5 подтверждено, что он работает с Ruby, JavaScript, Java и Python; другие языки либо имеют частичную поддержку, либо будут добавлены в будущих выпусках GitLab.

Краткое содержание

Серверная часть GitLab Sentry предоставляет простой способ сбора отчетов об ошибках из вашего приложения и хранения их вместе с вашим кодом. Хотя его текущие ограничения делают его непригодным для всех случаев использования, кроме самых простых, он по-прежнему является привлекательным вариантом для небольших сайтов и личных проектов, которым не требуется сложность полноценного сервиса Sentry.

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

Компонент отслеживания ошибок GitLab все еще находится в разработке и будет расширяться на последующих этапах. Это должно привести к тому, что он превратится в более полноценный вариант, который может заменить автономный Sentry в более широком наборе сред.