Sentry и GitLab для React: настройка и практика

TL;DR

Sentry помогает автоматически фиксировать ошибки в браузере и видеть стек-трейсы из исходников. GitLab может показывать список ошибок Sentry и создавать задачи на их исправление. В React интеграция включает установку @sentry/react, инициализацию в ранней точке приложения и (опционально) настройку трейсинга и source maps. В статье — пошаговая настройка, проверенные практики, готовые шаблоны задач и плейбук для команды.

Важно: сохраняйте DSN и API-токены в секретных переменных CI/CD. Не публикуйте их в публичных репозиториях.

Графика с логотипами GitLab и Sentry

Быстрая навигация

Getting Set up
Adding Sentry to Your Codebase
Capturing Errors
Error Boundaries
Adding GitLab Integration
Disabling Sentry in Development
Enabling Performance Profiling
Дополнительно: практики, чеклисты и шаблоны
Заключение

Введение

Sentry — платформа для отслеживания ошибок, которая собирает исключения, события и метрики производительности из приложений в продакшене. Она поддерживает большинство популярных языков и фреймворков. GitLab — платформа DevOps на базе Git, где можно управлять кодом, CI/CD и задачами команды. Интеграция GitLab и Sentry облегчает работу: ошибки отображаются в GitLab, а из Sentry можно создавать задачи и связывать инциденты с коммитами.

В этой статье показано, как настроить Sentry для React-проекта и связать его с GitLab. Материал подходит как для SaaS-версии сервисов, так и для self-hosted инстансов. Предполагается, что у вас уже есть React-проект в GitLab.

Getting Set up

И Sentry, и GitLab предлагают SaaS и self-hosted варианты. Процесс аналогичен, но у self-hosted инстанса Sentry нужно указывать свой API-адрес при интеграции.

Войдите в Sentry.
Нажмите Create Project (Создать проект) в правом верхнем углу.
Выберите React в разделе Choose a platform — Sentry предложит примеры кода специально для React.

Скриншот добавления нового React-проекта в Sentry

Установите параметры оповещений в Set your default alert settings: например, Alert me on every new issue, если вы хотите получать письмо на каждую новую ошибку. Параметр When there are more than помогает фильтровать шум от дублей в заданном окне времени.
Дайте проекту имя в поле Project name и нажмите Create Project.

Совет: создайте отдельный проект Sentry для production и другой для staging. Это упростит фильтрацию ошибок и корректировку уровня логирования.

Adding Sentry to Your Codebase

Добавьте библиотеку Sentry в зависимости проекта через npm или yarn:

npm install @sentry/react

Инициализируйте Sentry как можно раньше при загрузке приложения. Это даёт Sentry видимость ошибок, которые происходят в ранних фазах жизненного цикла React. Обычно инициализацию помещают в index.js перед первым ReactDOM.render(). В исходном примере код выглядит так:

import App from "./App.js";

import React from “react”;

import ReactDOM from “react-dom”;

import * as Sentry from “@sentry/react”;

Sentry.init({

dsn: “my-dsn”

});

ReactDOM.render(, document.getElementById(“react”));


Замените my-dsn на DSN, который показывает Sentry при создании проекта. DSN связывает события с вашим проектом.

Примеры и тонкие моменты:

- Для TypeScript-проектов используйте import * as Sentry from "@sentry/react" или import Sentry from "@sentry/react" в зависимости от настроек transpiler.
- Храните DSN в переменных окружения, а не в коде. Например, использовать process.env.REACT_APP_SENTRY_DSN.
- Инициализация должна выполняться в коде, который гарантированно загружается для большинства пользователей (например, index.js, service worker или bootstrap-скрипт).

Дополнение — пример безопасной инициализации с проверкой окружения:

// index.js import React from “react”; import ReactDOM from “react-dom”; import * as Sentry from “@sentry/react”; import App from “./App”;

if (process.env.NODE_ENV === “production” && process.env.REACT_APP_SENTRY_DSN) { Sentry.init({

dsn: process.env.REACT_APP_SENTRY_DSN,
// Дополнительные настройки по необходимости

}); }

ReactDOM.render(, document.getElementById(“root”));


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

## Capturing Errors

Sentry автоматически перехватывает необработанные исключения и unhandled promise rejections в браузере. Это не предотвращает падение приложения, но дает информацию, которую можно использовать для устранения причины.

Ниже пример поломанного App.js из исходного текста:

import React from “react”;


export default () => {

const data = null;

return data.map((val, key) => {

{val};

});

};

В этом примере data = null, и вызов data.map() вызывает ошибку. Sentry зарегистрирует её и создаст issue в вашем проекте.

Что Sentry собирает автоматически:

URL страницы и путь
Заголовки запроса и реферер
User agent и информация об устройстве
Минимизированные или маппированные стек-трейсы (если доступны source maps)
Дополнительные теги и контекст (если вы их добавите вручную)

Source maps

Sentry автоматически подтягивает source maps, если они доступны по корректному пути. Создатель приложения create-react-app генерирует source maps при npm run build. Важно логически и физически доставить .map-файлы на ваш веб-сервер и настроить доступ Sentry к ним. Тогда вы увидите красивый стек из оригинального кода, а не из минифицированного файла.

Советы:

Не выставляйте source maps публично на продакшне без контроля: по умолчанию это безопасно, но при строгих требованиях безопасности можно загружать source maps в Sentry напрямую через CLI или API и не размещать их общедоступно.
Проверяйте, что пути в sourcemap соответствуют URL в Sentry (особенно важны базовые пути и CDN).

Скриншот ошибки в Sentry

Управление статусом ошибок

Resolved — используйте, когда уверены, что проблема исправлена.
Ignored — используйте для ошибок, которые вы не планируете исправлять (например, специфичные ошибки старых браузеров).

Sentry будет группировать похожие события в Issue. Это помогает понять, повторяется ли проблема и насколько она массовая.

Error Boundaries

React error boundaries позволяют рендерить запасной UI, когда компонент внутри дерева бросает ошибку. Sentry предоставляет свой ErrorBoundary-обёртчик, который рендерит fallback UI и логирует ошибку в Sentry.

В вашем исходнике был пример с импортом import * as Sentry from "sentry";, который некорректен — правильный импорт — из пакета @sentry/react.

Правильный пример использования ErrorBoundary:

import * as Sentry from "@sentry/react";
import React from "react";

export default function FaultyWrapper() {
  const data = null;

  return (
    Что-то пошло не так.}>
      {data.map((val, key) => (
        {val}
      ))}
    
  );
}

Пояснения:

ErrorBoundary перехватывает ошибки только в фазе рендера, lifecycle-методах и конструкторах дочерних компонентов.
Он не поймает ошибки внутри обработчиков событий (event handlers). Для них используйте try/catch и/или Sentry.captureException.
Вы можете создать глобальный ErrorBoundary вокруг всего приложения и локальные вокруг критичных фрагментов UI.

Пример ручного логирования ошибки:

try {
  // код, который может выбросить
} catch (err) {
  Sentry.captureException(err);
}

Adding GitLab Integration

Интеграция работает в двух направлениях:

GitLab показывает список ошибок Sentry в разделе Error Tracking проекта. Оттуда можно пометить ошибки Resolved/Ignored и создать GitLab issue.
Sentry может автоматически создавать задачи в GitLab при появлении новых ошибок, если интеграция настроена.

Создание API-токена в Sentry

В Sentry нажмите на своё имя пользователя (в левом верхнем углу) -> API Keys.
Нажмите Create New Token.
Выберите scope’ы (права) для токена. Рекомендуемый набор для GitLab-интеграции:

alerts:read
alerts:write
event:admin
event:read
event:write
project:read

Эти права позволяют GitLab читать и обновлять ошибки в Sentry.

Скриншот создания API-ключа в Sentry

Подключение в GitLab

В GitLab откройте нужный проект -> Settings -> Operations -> Error tracking.
Вставьте ваш Auth Token и (если нужно) Sentry API URI для self-hosted инстанса.
Выберите проект из выпадающего списка Project и Save changes.

После этого в GitLab появится список ошибок из Sentry. По клику на ошибку можно открыть стек-трейс внутри интерфейса GitLab.

Скриншот настроек error tracking в GitLab

Настройка интеграции из Sentry в GitLab

В Sentry откройте Settings -> Integrations -> найдите GitLab.
Нажмите Add Installation и следуйте шагам установки.
Sentry покажет параметры для создания приложения в GitLab — Client ID и Redirect URI.

На стороне GitLab:

Нажмите на иконку пользователя -> Preferences -> Applications.
Add new application и вставьте данные из Sentry.
Скопируйте Application ID и Secret Key и верните их в попап Sentry.
Укажите адрес вашего GitLab (gitlab.com для SaaS) и относительный путь к группе (например, my-group). Интеграция не работает с личными проектами — нужна группа.

Скриншот добавления интеграции GitLab в Sentry

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

Скриншот добавления интеграции GitLab в Sentry

Важно:

Для self-hosted Sentry проверьте, что Sentry доступен по публичному URL из GitLab, или используйте VPN/проксирование.
Проверьте timezone и формат путей к файлам, если ссылки на коммиты не работают.

Disabling Sentry in Development

Обычно вы не хотите собирать «шум» из локальной разработки. Простейший способ отключить Sentry — не вызывать Sentry.init() в development или выставить пофлаговую переменную.

Исходный кусок показывает идею:

if (process.env.NODE_ENV === "production") {

Sentry.init({

dsn: "my-dsn"

});

}

Реальная реализация обычно использует REACTAPP* переменные:

if (process.env.NODE_ENV === "production" && process.env.REACT_APP_SENTRY_DSN) {
  Sentry.init({ dsn: process.env.REACT_APP_SENTRY_DSN });
}

Советы:

В CI/CD храните DSN и токены в секретах (GitLab CI/CD variables, GitHub Secrets и т.д.).
Для staging можно включать Sentry, но фильтровать события по тегу environment: “staging”.

Enabling Performance Profiling

Sentry поддерживает профилирование и трассировку (tracing) браузерных действий. Это помогает обнаружить узкие места и медленные участки кода.

Установка:

npm install @sentry/tracing

Пример конфигурации:

import { Integrations } from "@sentry/tracing";

Sentry.init({
  dsn: "my-dsn",
  integrations: [new Integrations.BrowserTracing()],
  tracesSampleRate: 1.0
});

Пояснения:

tracesSampleRate управляет долей трафика, для которого собираются данные трассировки. 1.0 означает 100% — в продакшне это обычно снижают (например, 0.1 или 0.01), чтобы сократить объём данных и затраты.
BrowserTracing автоматически собирает основные навигационные транзакции и взаимодействия.

Совет: начните с малого sample rate и постепенно увеличивайте, ориентируясь на полезность собранных данных и бюджет.

Практические рекомендации по логированию и контексту

Чтобы повысить ценность событий в Sentry, добавляйте контекст:

Sentry.setUser({ id, email }) — привязывает событие к пользователю.
Sentry.setTag(“feature”, “checkout”) — добавляет тег для фильтрации.
Sentry.setContext(“order”, { id: 123, value: 10.5 }) — добавляет структуру данных.

Пример:

Sentry.setUser({ id: currentUser.id, email: currentUser.email });
Sentry.setTag("env", process.env.NODE_ENV);
Sentry.configureScope(scope => {
  scope.setExtra("cart", cartItems);
});

Ограничьте объём персональных данных, которые вы отправляете в Sentry, чтобы соответствовать политике приватности и требованиям GDPR.

Безопасность и приватность

Не отправляйте чувствительные данные (пароли, полные номера карт, личную переписку) в Sentry.
Используйте redaction (фильтрацию полей) и функцию beforeSend в Sentry.init для удаления или маскировки данных перед отправкой.

Пример beforeSend:

Sentry.init({
  dsn: process.env.REACT_APP_SENTRY_DSN,
  beforeSend(event, hint) {
    // Удалить или заменить поля
    if (event.user && event.user.email) {
      event.user.email = "[redacted]";
    }
    return event;
  }
});

Тонкости при использовании create-react-app, Next.js и SSR

create-react-app: генерирует source maps при npm run build. Перенесите .map файлы на сервер или загрузите их в Sentry.
Next.js: поддерживает интеграцию и серверный рендеринг. Инициализация Sentry должна учитывать серверную и клиентскую части отдельно. Используйте @sentry/node на сервере и @sentry/react в браузере.
SSR: логирование ошибок на сервере помогает фиксировать ошибки рендеринга и быстро реагировать.

Модель зрелости: как расти с Sentry

Начальный уровень — установка и автоматический сбор исключений.
Нормализованный сбор — добавление тегов, связывание с пользователями, source maps.
Интеграция с процессом разработки — привязка к коммитам, автоматическое создание задач в GitLab.
Профилирование и SLO — сбор перформанс-метрик и установка порогов.

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

Когда Sentry не подходит или где он слаб

Маленькие экспериментальные проекты, где достаточно логирования в консоль.
Сильно ограниченные бюджеты: платные функции Sentry (например, интеграции, расширенный ретеншн) могут быть дорогими.
Сценарии, где нельзя отправлять пользовательские данные за пределы инфраструктуры из-за регуляторных требований — тогда лучше self-hosted Sentry или внутренние решения.

Альтернативные подходы

Использовать другие SaaS: Bugsnag, Rollbar, Honeybadger — схожая функциональность, но отличаются интерфейсом и моделью ценообразования.
Собрать собственную систему логирования + агрегацию (ELK/EFK) — более гибко, но требует поддержки и ресурсов.

Роль-ориентированные чеклисты

Разделены по ролям: разработчик, инженер DevOps, QA и менеджер.

Чеклист для разработчика

Установил @sentry/react и инициализацию в index.js.
Использует переменную окружения для DSN.
Добавляет контекст (user, tags, extras) там, где нужно.
Обрабатывает обработчики событий с try/catch и Sentry.captureException.

Чеклист для DevOps

Хранит DSN и токены в секретах CI/CD.
Проверил загрузку source maps и доступность URL для Sentry.
Настроил интеграцию GitLab ↔ Sentry и проверил callback URL.

Чеклист для QA

Смоделировал ошибки и проверил их появление в Sentry.
Убедился, что в issue есть достаточный контекст для воспроизведения.

Чеклист для менеджера/продукта

Прозрачные правила triage для критичных ошибок.
SLA на реакцию и закрытие багов, связанные с продакшн-инцидентами.

Плейбук для triage новой ошибки (SOP)

Новая ошибка появилась в Sentry и помечена критичной.
Назначьте ответственного из команды (owner).
Оцените impact: сколько пользователей затронуто, упала ли функциональность.
При необходимости создайте GitLab issue из Sentry/GitLab Error Tracking.
Если проблема связана с недавним релизом, пометьте suspect commit и откатите релиз при необходимости.
Внесите временную меру (feature flag, фолбек) для уменьшения влияния.
Закрывайте issue после проверки в продакшне.

Критерии приёмки

Коммит, исправляющий баг, связан с задачей GitLab и ссылается на Sentry issue.
В продакшне количество событий снизилось до нуля или до приемлемого уровня.
Произведён post-mortem, если инцидент критичный.

Incident runbook для критичных инцидентов

Триггер: рост ошибок > порога или падение ключевой функциональности.
Шаг 1: объявить инцидент и собрать команду.
Шаг 2: назначить коммуникацию (человек для внешних уведомлений).
Шаг 3: собрать ведомые данные: трассировки, теги, user context.
Шаг 4: найти suspect commit или последнее изменение в релизе.
Шаг 5: при необходимости — откат релиза, включить feature flag или временно отключить функционал.
Шаг 6: по завершении — провести разбор и обновить документацию.

Тесты и критерии приёмки интеграции

Тестовые сценарии:

Инициализация Sentry не выполняется в development (проверка отсутствия сетевых вызовов).
Искусственно сгенерированное исключение появляется в Sentry с правильным тегом environment.
Source maps корректно отображают оригинальные имена файлов в Sentry.
Интеграция с GitLab создает задачу и связывает ее с Sentry issue.

Критерии приёмки:

Все тесты выполняются на CI и проходят стабильнее чем X прогонов подряд.
Sentry принимает ошибки из production сборки и показывает читаемые stack traces.

Шаблон задачи GitLab для багов из Sentry

Название: [bug][sentry] {короткое описание ошибки}

Описание шаблона:

Sentry issue: {вставить ссылку}
Environment: {production|staging}
Количество событий за последние 24 часа: {число}
Suspect commit: {коммит}
Шаги для воспроизведения:
1. …
2. …
Ожидаемое поведение:
Фактическое поведение:

Теги: bug, needs-triage, sentry

Этот шаблон помогает быстро начать работу над инцидентом.

Snippets и чеклист конфигураций

Пример TypeScript инициализации с tracing и beforeSend:

import * as Sentry from "@sentry/react";
import { BrowserTracing } from "@sentry/tracing";

Sentry.init({
  dsn: process.env.REACT_APP_SENTRY_DSN,
  integrations: [new BrowserTracing()],
  tracesSampleRate: 0.1,
  beforeSend(event) {
    // Маскировать PII
    if (event.user && event.user.email) event.user.email = undefined;
    return event;
  }
});

Пример использования feature flag для отключения Sentry в runtime:

if (window.__ENABLE_SENTRY__ === true && process.env.REACT_APP_SENTRY_DSN) {
  Sentry.init({ dsn: process.env.REACT_APP_SENTRY_DSN });
}

Совместимость и миграция

Если вы переходите с другого трекера (например, Rollbar) на Sentry, экспортируйте основные события и настройте теги, чтобы сохранить историю инцидентов в контексте.
Для монорепозиториев используйте отдельные проекты Sentry для видимых boundary (frontend/backend) или используйте tags/environment для фильтрации.

Локальные альтернативы и подводные камни для России и соседних регионов

Если ваша инфраструктура размещена в локальных дата-центрах, рассмотрите self-hosted Sentry, чтобы данные не покидали контролируемую область.
При использовании SaaS GitLab (gitlab.com) и self-hosted Sentry убедитесь, что убедительный внешний доступ настроен или используйте обратный прокси.

Галерея сложно-воспроизводимых случаев

Ошибки, появляющиеся только у конкретных браузеров или плагинов — смотрите user agent и дополнительные поля.
Проблемы, вызванные некорректно загруженными source maps — проверьте соответствие путей.
Интеграция с CDN, которая меняет относительные пути — используйте sourceMappingURL и корректные base paths.

Social preview

OG title: Sentry и GitLab для React — настройка и рабочие практики OG description: Настройте сбор ошибок в React, интегрируйте Sentry с GitLab и внедрите плейбук для обработки инцидентов в команде.

Короткое объявление (100–200 слов)

Sentry помогает автоматически фиксировать и агрегировать ошибки из вашего React-приложения. В сочетании с GitLab вы можете просматривать Sentry-ошибки прямо в интерфейсе проекта и автоматически создавать задачи для багфикса. В статье описан пошаговый путь: от установки @sentry/react и инициализации в index.js до настройки API-токенов и полной интеграции с GitLab. Также предложены практики безопасности, плейбук для triage, шаблоны задач и примеры кода для профилирования и защиты персональных данных. Это руководство поможет сократить среднее время реагирования на инциденты и сделать процесс работы с багами прозрачным для всей команды.

Заключение

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

Следуйте простым шагам: