DevOps и облакоНачальный9 мин чтенияПолезно знать

Sentry

Узнавайте об ошибках раньше, чем о них сообщат пользователи, — со stack trace, релизом и контекстом.

Error tracking
Releases
Source maps
Performance

Шаг 1/6

Checkout длится 8 секунд, пользователи в ярости. Пора звать детективов: metrics, traces и logs.

За 30 секунд

Sentry — сервис мониторинга приложений, сфокусированный на ошибках. SDK в вашем приложении перехватывает исключения, добавляет контекст (браузер, пользователь, запрос, breadcrumbs — что происходило перед этим) и отправляет их в Sentry, который группирует одинаковые ошибки в issues и присылает алерты. С релизами и source maps вы видите точную строку исходного кода, коммит, который принёс баг, и сколько пользователей он затрагивает. Также он предлагает трассировку, session replay, логи, мониторинг cron и доступности.

Не в моём ежедневном стеке — я понимаю принципы и изучу детали, когда это понадобится проекту.

Почему это важно

Пользователи редко сообщают о багах — они просто уходят. Error tracking превращает тихие сбои в алерты с достаточными деталями, чтобы быстро их исправить.
Stack trace минифицированного JavaScript нечитаемы; с загруженными source maps Sentry показывает исходный файл, строку и окружающий код.
Отслеживание релизов связывает ошибки с деплоями и коммитами, так что команда за минуты видит, что «это началось с версии 1.4.2», и откатывается.
Начать дёшево (бесплатный уровень и мастер, настраивающий популярные фреймворки), поэтому часто это первый инструмент мониторинга, который добавляет команда.

Как это работает

01Как это работает: события, issues и DSN

Когда происходит ошибка, Sentry SDK в вашем приложении фиксирует её как событие (event): тип и сообщение исключения, stack trace и контекст — браузер и ОС, URL, релиз, окружение, ID пользователя, если вы это разрешаете, и breadcrumbs, короткую хронологию последних действий (клики, навигация, сетевые запросы, сообщения консоли). SDK отправляет его в Sentry по DSN — URL конкретного проекта, который говорит SDK, куда отправлять данные. DSN не является секретом в привычном смысле, потому что через него можно только отправлять события, поэтому он может жить в браузерном коде. Затем Sentry вычисляет для события fingerprint, в основном по stack trace, и группирует похожие события в issue. Вы работаете с issues, а не с миллионами событий: один issue говорит «TypeError в CheckoutForm, 312 событий, 87 пользователей, впервые в 1.4.2». Необработанные ошибки перехватываются автоматически; обработанные вы отправляете через captureException.

02Настройка в приложении на Next.js

Мастер Sentry настраивает большинство фреймворков за несколько минут: устанавливает SDK, создаёт конфиги и подключает загрузку source maps в сборке. Для Next.js он создаёт instrumentation-client.ts для браузера, sentry.server.config.ts и sentry.edge.config.ts для серверных рантаймов, instrumentation.ts, который их загружает и экспортирует onRequestError, и оборачивает next.config в withSentryConfig. На других платформах похоже: @sentry/react, @sentry/node, sentry/sentry-laravel, @sentry/react-native. После настройки задайте окружение и релиз, понизьте trace sample rate для продакшена и решите, какие данные о пользователе отправлять. Затем бросьте тестовую ошибку и убедитесь, что она приходит с читаемым stack trace.

1// instrumentation-client.ts (created by: npx @sentry/wizard@latest -i nextjs)
2import * as Sentry from "@sentry/nextjs";
3 
4Sentry.init({
5  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
6  environment: process.env.NEXT_PUBLIC_APP_ENV ?? "development",
7  integrations: [Sentry.replayIntegration()],
8  tracesSampleRate: 0.1,          // 10% of transactions in production
9  replaysSessionSampleRate: 0.0,  // no replays for normal sessions
10  replaysOnErrorSampleRate: 1.0,  // replay every session that hits an error
11});
12 
13export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;

03Релизы и source maps

Релиз — метка версии, прикрепляемая к каждому событию, обычно SHA Git-коммита или семантическая версия. С релизами Sentry знает, когда issue появился впервые, может пометить issue как «resolved in next release» и переоткрыть его, если он вернётся (регрессия), а с интеграцией коммитов подсказывает, какой коммит и автор, вероятно, его вызвали. Source maps переводят минифицированный продакшен-код обратно в ваш исходный. Загружайте их во время сборки через плагин бандлера или sentry-cli и не отдавайте публично; плагины умеют удалять их после загрузки. Sentry сопоставляет загруженные файлы с ошибками по Debug ID, встроенным в бандл, — это гораздо надёжнее старого сопоставления по URL. Мобильным приложениям нужна та же идея: dSYM для iOS, mapping-файлы ProGuard/R8 для Android и source maps для JavaScript-бандла React Native.

bash

1# CI step after the build (if not using a bundler plugin)
2export SENTRY_AUTH_TOKEN=***            # from CI secrets, never committed
3export SENTRY_ORG=your_org SENTRY_PROJECT=web
4VERSION=$(git rev-parse --short HEAD)
5 
6npx @sentry/cli releases new "$VERSION"
7npx @sentry/cli releases set-commits "$VERSION" --auto
8npx @sentry/cli sourcemaps inject ./dist
9npx @sentry/cli sourcemaps upload --release "$VERSION" ./dist
10npx @sentry/cli releases finalize "$VERSION"
11npx @sentry/cli deploys new --release "$VERSION" -e production
12find ./dist -name "*.map" -delete

04Добавление контекста: пользователи, теги и breadcrumbs

Ошибка без контекста — головоломка. Добавьте анонимизированный ID пользователя через Sentry.setUser, чтобы считать затронутых пользователей и находить все ошибки одного клиента, который обратился в поддержку. Добавляйте теги для того, по чему хотите фильтровать и искать: тариф тенанта, feature flag, платёжный провайдер, локаль приложения. Теги индексируются, и у них должен быть ограниченный набор значений. Для более крупной структурированной информации, которую вы читаете только на странице события, используйте contexts или extra data. Breadcrumbs записываются автоматически для навигации, кликов, консоли и сетевых вызовов; добавляйте свои для важных бизнес-шагов. Относитесь к приватности осознанно: не отправляйте email, имена или токены без причины и правового основания и удаляйте чувствительные поля в beforeSend. Серверная очистка данных в настройках проекта — второй уровень защиты.

1import * as Sentry from "@sentry/nextjs";
2 
3Sentry.setUser({ id: account.id });               // id only, no email
4Sentry.setTag("plan", account.plan);               // "free" | "pro" | "enterprise"
5 
6try {
7  await chargeCard(order);
8} catch (err) {
9  Sentry.captureException(err, {
10    tags: { payment_provider: "stripe" },
11    contexts: { order: { id: order.id, total: order.total } },
12  });
13  throw err;
14}

05Алерты, шум и квоты

Sentry полезен, только если люди доверяют его алертам. Начните с трёх видов: новый issue в продакшене, регрессия (решённый issue вернулся) и резкий рост частоты или числа затронутых пользователей. Направляйте их в Slack-канал команды-владельца по правилам ownership на основе путей файлов или URL, а будите дежурного только по метрическим алертам с большим влиянием — например, падение доли crash-free-сессий или доля ошибок выше порога. Держите шум низким: игнорируйте известные ошибки браузерных расширений через ignoreErrors и denyUrls, используйте inbound-фильтры для устаревших браузеров и поисковых краулеров и архивируйте issues, которые не будете исправлять. Тарифы включают месячную квоту ошибок, спанов, replay и логов; один баг в цикле может сжечь её за час. Используйте spike protection и rate limits на ключ, сэмплируйте транзакции и задайте лимит расходов на платных тарифах.

Когда применять

Любое продакшен-веб- или мобильное приложение, где вы хотите узнавать об ошибках раньше, чем пожалуются пользователи.
Фронтенд-приложения с минифицированным кодом, где для читаемых stack trace нужны source maps.
Команды, которые часто деплоят и хотят связывать ошибки с релизами, коммитами и откатами.
Мобильные приложения, которым нужны отчёты о крашах, доля crash-free-сессий и release health.

Когда не стоит

В качестве единственного мониторинга: Sentry не заменяет проверки доступности, серверные метрики, бэкапы или хранение логов.
Строгие требования к локализации данных или приватности, которым не соответствуют hosted-регионы, — если только вы не self-host.
Когда главная цель — глубокие инфраструктурные метрики и распределённая трассировка через множество сервисов; лучше подойдёт OpenTelemetry с tracing-бэкендом.

Альтернативы

Self-hosted Sentry
Тот же продукт на ваших серверах через Docker Compose; лицензия бесплатна, но стек тяжело запускать и обновлять.
GlitchTip
Лёгкий open-source error tracker, совместимый с SDK Sentry; меньше возможностей, но намного проще в self-host.
Datadog / New Relic
Полноценные observability-платформы со встроенным error tracking; шире и дороже.
Firebase Crashlytics / Bugsnag
Сильные отчёты о крашах на мобильных; Crashlytics бесплатен и популярен у чисто мобильных команд.

Лучшие практики

Задавайте environment и release для каждого события; в качестве релиза используйте Git SHA.
Загружайте source maps (и dSYM или mapping-файлы) в CI и не публикуйте их.
Отправляйте анонимизированный ID пользователя, а не персональные данные, и очищайте чувствительные поля в beforeSend.
Сэмплируйте performance-трейсы в продакшене (часто 5–20%), а сэмплирование ошибок держите на 100%.
Настройте правила ownership, чтобы каждый issue попадал к команде, и раз в неделю разбирайте новые issues.
Фильтруйте известный шум (браузерные расширения, боты, прерванные запросы), чтобы настоящие ошибки были заметны.
Включите spike protection и rate limits, чтобы защитить квоту от зациклившегося кода.

Частые ошибки

Выпускать без source maps и получать stack trace, указывающие на строку 1 минифицированного бандла.
Оставить tracesSampleRate равным 1.0 в продакшене и израсходовать квоту за несколько дней.
Перехватывать ошибки и «глотать» их без captureException, так что Sentry их никогда не видит.
Отправлять с событиями email, токены или полные тела запросов, создавая проблему с приватностью.
Слать алерт на каждое событие в общий канал, пока все его не замьютят.

Глубже

06Сэмплирование, квоты и контроль расходов

Sentry тарифицирует по объёму в каждой категории данных: ошибки, спаны, replay, вложения, логи и мониторы, у каждой — месячная квота и опциональный pay-as-you-go-бюджет. Контроль работает на трёх уровнях. В SDK: tracesSampler (функция) позволяет сэмплировать по маршруту — например, 100% для checkout, 1% для health checks, 0 для ботов; replaysOnErrorSampleRate сохраняет replay только там, где он помогает; beforeSend и beforeSendTransaction отбрасывают события, которые заведомо являются шумом. На уровне проекта: inbound-фильтры, rate limits на ключ DSN и spike protection, который временно отбрасывает события, когда объём резко превышает норму. На уровне организации: лимиты расходов и алерты. Решения о сэмплировании распространяются вместе с трейсом в заголовках sentry-trace и baggage, так что фронтенд и бэкенд сохраняют или отбрасывают один и тот же трейс вместе.

1Sentry.init({
2  dsn: process.env.SENTRY_DSN,
3  tracesSampler: ({ name, inheritOrSampleWith }) => {
4    if (name.includes("/healthz")) return 0;        // never trace health checks
5    if (name.includes("/checkout")) return 1.0;     // always trace checkout
6    return inheritOrSampleWith(0.05);               // follow parent, else 5%
7  },
8  beforeSend(event) {
9    if (event.request?.headers) delete event.request.headers["authorization"];
10    return event;
11  },
12});

07Распределённая трассировка между фронтендом и бэкендом

Когда браузерная страница вызывает ваш API, браузерный SDK Sentry добавляет заголовки sentry-trace и baggage к исходящим запросам, которые подходят под tracePropagationTargets. SDK бэкенда читает их и продолжает тот же трейс, так что один трейс показывает загрузку страницы, fetch, API-обработчик и SQL-запросы. Указывайте в tracePropagationTargets только свои API-origin: отправка этих заголовков на сторонние домены может сломать их CORS preflight. Ваш API тоже должен разрешать эти заголовки в CORS. Для страниц с серверным рендерингом сервер встраивает trace meta-теги, чтобы браузер продолжил серверный трейс. Поскольку JavaScript SDK построен на OpenTelemetry, он понимает и W3C traceparent, а OTel-данные из других сервисов можно отправлять в Sentry через его OTLP-эндпоинт — так Sentry становится частью более широкой OTel-инфраструктуры, а не отдельным островом.

08Self-hosting или SaaS

Код Sentry доступен под Functional Source License, а self-hosted-дистрибутив работает через Docker Compose. Он немаленький: Kafka, ClickHouse, PostgreSQL, Redis, Snuba, Relay, Symbolicator и множество воркеров; рекомендуемый минимум — около 4 ядер CPU, 16 GB RAM плюс swap и быстрые диски. Обновляться нужно через определённые версии по порядку, бэкапить Postgres и ClickHouse и мониторить сам стек. Некоторые новые возможности, например AI-агент для отладки, есть только в SaaS. Self-hosting имеет смысл при строгой локализации данных или в изолированных (air-gapped) окружениях, либо при таком объёме, когда экономия на лицензии перевешивает время инженера. Для большинства команд SaaS с регионом данных EU или US и серверной очисткой в сумме дешевле. Лёгкий промежуточный вариант — GlitchTip, который принимает данные SDK Sentry и состоит из гораздо меньшего числа компонентов.

Реальные ситуации

Ошибки приходят с минифицированными stack trace

Проблема

Sentry установлен в приложении на Vite и React, но каждый stack trace показывает index-3f9a.js, строка 1, и минифицированные имена.

Как решить

Source maps не загружаются или не сопоставляются. Включите build.sourcemap в Vite (hidden source maps подойдут), добавьте @sentry/vite-plugin с org, project и SENTRY_AUTH_TOKEN из секретов CI, дайте ему встроить Debug ID и загрузить карты, затем удалите .map-файлы из результата сборки. Убедитесь, что release в Sentry.init совпадает с релизом, который создаёт плагин. Задеплойте, вызовите тестовую ошибку и проверьте в событии раздел processing errors — там объясняется, каких карт не хватает или какие не совпали. Если всё ещё не работает, используйте npx @sentry/cli sourcemaps explain с ID события. Добавьте этот шаг в CI, чтобы каждая сборка загружала карты автоматически.

Баг в цикле сжигает месячную квоту

Проблема

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

Как решить

Сначала откатите или исправьте баг хотфиксом. В Sentry убедитесь, что spike protection включён, и задайте rate limit на ключ DSN затронутого проекта, например несколько тысяч событий в минуту. В SDK исправьте участок кода, который повторно бросает ошибку в цикле, и подумайте о дедупликации ошибок на клиенте; интеграция Dedupe отбрасывает одинаковые события подряд. Настройте pay-as-you-go-бюджет с лимитом, чтобы будущий всплеск поглощался без неограниченных расходов. Добавьте метрический алерт на объём событий по проекту, чтобы аномальный всплеск оповещал команду за минуты, а не обнаруживался в конце месяца.

Связать мобильный краш с проблемой на бэкенде

Проблема

Приложение на React Native падает на экране заказа, но бэкенд-команда говорит, что их API в порядке.

Как решить

Включите трассировку и в React Native SDK, и в SDK бэкенда и укажите в tracePropagationTargets домен API, чтобы запросы несли заголовки sentry-trace и baggage. Загружайте JavaScript source maps и нативные debug-файлы (dSYM, mapping-файлы ProGuard) в мобильном пайплайне сборки, чтобы краши были читаемы. Теперь откройте краш и пройдите по его трейсу: возможно, API возвращает 200 с неожиданным полем null, которое приложение не обрабатывает. Добавьте теги для версии приложения и версии API. Исправление часто нужно в обоих местах: защитный парсинг в приложении и контрактный тест на API.

Шпаргалка

Настроить фреймворк через мастер: npx @sentry/wizard@latest -i nextjs
Отправить обработанную ошибку: Sentry.captureException(err)
Отправить событие-сообщение: Sentry.captureMessage("Payment webhook retried", "warning")
Прикрепить анонимизированного пользователя: Sentry.setUser({ id: account.id })
Добавить тег для поиска: Sentry.setTag("plan", "pro")
Загрузить source maps из CI: npx @sentry/cli sourcemaps inject ./dist && npx @sentry/cli sourcemaps upload --release "$VERSION" ./dist
Разобраться, почему не сработала source map: npx @sentry/cli sourcemaps explain <event-id>
Игнорировать шум браузерных расширений: denyUrls: [/extensions\//i, /^chrome:\/\//i]
Установка в Laravel: composer require sentry/sentry-laravel && php artisan sentry:publish --dsn=<your-dsn>

Вопросы и ответы

Q1Что такое DSN и безопасно ли показывать его в браузере?

DSN (Data Source Name) — это URL, содержащий публичный ключ и ID проекта и сообщающий SDK, куда отправлять события. Он позволяет только отправлять события в этот проект, но не читать данные и не менять настройки, поэтому он изначально рассчитан на встраивание в браузерные и мобильные приложения. Настоящий секрет — auth token, которым sentry-cli и плагины сборки создают релизы и загружают source maps; он должен оставаться в секретах CI. Риск открытого DSN — спам: кто-то может слать фейковые события и расходовать квоту. Снижайте его разрешёнными доменами, rate limits на ключ и inbound-фильтрами.

Q2Почему source maps важны и как сохранить их приватными?

Продакшен-JavaScript минифицирован и собран в бандлы, поэтому «сырой» stack trace указывает на что-то вроде main.4f2a.js, строка 1, колонка 48211, — это бесполезно. Source maps сопоставляют эти позиции с исходным файлом, строкой и функцией. Sentry использует их на своих серверах, чтобы показывать читаемые stack trace с окружающим кодом. Чтобы исходники оставались приватными, загружайте карты в Sentry во время сборки и не деплойте их на публичный сервер: плагины бандлеров умеют удалять их после загрузки, либо можно исключить .map-файлы из деплоя. Debug ID, встроенные в каждый файл, позволяют Sentry надёжно сопоставлять карты, не полагаясь на публичные URL.

Q3Как Sentry группирует ошибки в issues?

Каждое событие получает fingerprint. По умолчанию он основан на stack trace, в основном на in-app-фреймах, то есть на вашем коде, а не на библиотеках; если stack trace нет, используется тип и сообщение исключения. События с одинаковым fingerprint относятся к одному issue. Иногда поведение по умолчанию ошибается: одна общая ошибка с разными причинами сливается в один issue, или динамическое сообщение порождает тысячи issues. Это исправляется правилами fingerprint и stack trace в настройках проекта или заданием своего fingerprint в SDK — например, группировкой всех таймаутов одного API-клиента по эндпоинту.

Q4Чем error tracking в Sentry отличается от трассировки?

Error tracking перехватывает исключения и краши со stack trace и контекстом, группирует их и присылает алерты. Трассировка (performance monitoring) записывает спаны для загрузок страниц, навигаций, API-запросов и запросов к базе, так что вы видите, сколько всё длится и куда уходит время, даже когда ничего не падает. Sentry связывает одно с другим: ошибка несёт trace ID, поэтому можно открыть упавший запрос и увидеть медленный SQL-запрос перед ней. Ошибки обычно сохраняются на 100%, а трейсы сэмплируются, потому что их объём намного больше. Начиная с версии 8 JavaScript SDK Sentry внутри использует OpenTelemetry, поэтому может работать рядом с другой OTel-инструментацией.

Q5Клиент спрашивает: зачем платить за Sentry, если у нас есть серверные логи?

Логи говорят, что делал сервер; Sentry говорит, с какими проблемами реально сталкиваются пользователи и как часто. Большинство ошибок фронтенда и мобильных приложений вообще не попадает в серверные логи: краш в браузере или приложении происходит на устройстве пользователя. Sentry их перехватывает, сворачивает тысячи событий в короткий список issues, показывает точную строку исходного кода, релиз и коммит, которые принесли ошибку, сколько пользователей затронуто, и replay действий пользователя. Он сообщает команде, когда после деплоя появляется новая проблема. Обычно это превращает баг из нескольких дней догадок в час исправления, и тариф быстро окупается.

Вопросы уровня senior

S1Как сделать Sentry полезным для большой организации, а не шумным почтовым ящиком?

Сначала — структура и ответственность. Создавайте проекты на каждое деплоящееся приложение, последовательно используйте окружения (production, staging) и релизы и добавьте правила ownership или интеграцию code owners, чтобы каждый issue автоматически назначался команде. Алертите о важном: новые issues в продакшене, регрессии и метрические алерты на долю ошибок или crash-free-сессии, привязанные к SLO, — в канал команды-владельца, а дежурного будите только при порогах, влияющих на пользователей. Снижайте шум inbound-фильтрами, правилами игнорирования и правилами fingerprint для известных групп. Проводите в каждой команде еженедельный разбор с простым правилом: решить, назначить или заархивировать с указанием причины. Отслеживайте crash-free rate по релизам как критерий выпуска. Компромисс — начальная работа по настройке, которая окупается доверием к алертам.

S2Sentry или стек на основе OpenTelemetry: это конкуренты?

Они пересекаются, но сфокусированы по-разному. OpenTelemetry — стандарт инструментации и конвейер: он даёт переносимые трейсы, метрики и логи, но без бэкенда, без группировки issues и без рабочего процесса. Sentry — продукт, построенный вокруг рабочих процессов разработчиков: группировка, регрессии, release health, подозрительные коммиты, replay и работа с source maps, плюс трассировка. Поскольку его JavaScript SDK внутри работает на OpenTelemetry, а Sentry принимает OTLP, они хорошо сочетаются: OTel-инструментация для бэкенд-сервисов с Collector, экспортирующим трейсы в ваш tracing-бэкенд, и Sentry для ошибок, крашей и replay на фронтенде и мобильных, с общим контекстом трейса. Выбирайте по вопросам: «какой код сломан у пользователей?» — это к Sentry; «куда уходит задержка в 30 сервисах?» — к tracing-бэкенду на OTel.

S3Как обеспечить приватность и GDPR при использовании Sentry и Session Replay?

Собирайте минимум. Используйте внутренний ID пользователя вместо email или имени, держите сбор PII по умолчанию выключенным и удаляйте в beforeSend заголовки, cookies, query-строки и тела запросов, которые могут содержать персональные данные. Включите серверную очистку данных и расширенные правила очистки как страховочную сетку. Для Session Replay оставьте настройки по умолчанию, которые маскируют весь текст и блокируют медиа, и снимайте маску только с конкретных безопасных элементов; никогда не записывайте платёжные или медицинские формы. Выберите регион данных EU, если ваши пользователи в Европе, подпишите соглашение об обработке данных (DPA) и задайте срок хранения настолько коротким, насколько это полезно. Укажите Sentry как обработчика данных в политике конфиденциальности. Наконец, уважайте согласие: инициализируйте replay только после того, как пользователь согласится, если этого требует ваше правовое основание.

Глоссарий

DSN: URL проекта и публичный ключ, которые сообщают SDK, куда отправлять события; безопасно встраивать в клиенты.
Событие (Event): Одна перехваченная ошибка, сообщение или транзакция со stack trace, контекстом и breadcrumbs.
Issue: Группа похожих событий с общим fingerprint, которую команда разбирает и решает.
Fingerprint: Значение, по которому Sentry решает, какие события относятся к одному issue; настраивается.
Breadcrumbs: Хронология действий перед ошибкой: клики, навигация, сетевые вызовы и сообщения консоли.
Релиз (Release): Идентификатор версии, прикреплённый к событиям и связывающий ошибки с деплоями и коммитами.
Debug ID: Уникальный ID, встраиваемый в бандлы и source maps, чтобы Sentry мог надёжно их сопоставлять.
Session Replay: Похожая на видео реконструкция действий пользователя перед ошибкой, с маскированием ради приватности.
Spike protection: Функция Sentry, которая временно отбрасывает события, когда объём внезапно намного превышает норму.

Что изучить дальше

Есть идея продукта?Давайте создадим его.

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

Начать разговор