Sentry no Next.js App Router: erros de servidor e cliente, mapas de origem sem PII
Что должно получиться
Ошибка в серверном компоненте, Route Handler, Server Action или в браузере попадает в Sentry с читаемым стеком (имена файлов и строки исходников, а не минифицированный бандл), с указанием релиза и без персональных данных пользователя в событии.
Установка
npx @sentry/wizard@latest -i nextjs
Мастер создаёт файлы и правит next.config. Разберитесь, что он сделал, — дальше их поддерживаете вы:
instrumentation-client.ts(в старых версиях SDK —sentry.client.config.ts) — инициализация в браузере.sentry.server.config.tsиsentry.edge.config.ts— для Node.js и Edge-рантайма.instrumentation.ts— точка входа, которую Next.js вызывает при старте сервера.app/global-error.tsx— граница ошибок корневого layout.
// instrumentation.ts
import * as Sentry from "@sentry/nextjs";
export async function register() {
if (process.env.NEXT_RUNTIME === "nodejs") await import("./sentry.server.config");
if (process.env.NEXT_RUNTIME === "edge") await import("./sentry.edge.config");
}
export const onRequestError = Sentry.captureRequestError;onRequestError — хук Next.js 15, который вызывается при ошибках рендеринга, в Route Handlers и Server Actions. Без этой строки серверные ошибки часто не доходят до Sentry: Next.js перехватывает их сам и показывает пользователю страницу ошибки.
Конфигурация сервера без PII
// sentry.server.config.ts
import * as Sentry from "@sentry/nextjs";
Sentry.init({
dsn: process.env.SENTRY_DSN,
environment: process.env.APP_ENV ?? "production",
release: process.env.SENTRY_RELEASE,
sendDefaultPii: false,
tracesSampleRate: 0.1,
beforeSend(event) {
if (event.request) {
delete event.request.cookies;
delete event.request.data;
if (event.request.headers) {
delete event.request.headers.authorization;
delete event.request.headers.cookie;
}
}
return event;
},
});sendDefaultPii: false(это значение по умолчанию, но лучше явно) — SDK не прикрепляет IP-адрес, cookie и заголовки с пользовательскими данными.beforeSend— последняя линия: удаляет то, что могло попасть через интеграции или ваш собственный контекст. Тело запроса (request.data) особенно опасно: в нём пароли из формы входа и данные платежей.- Пользователя указывайте только идентификатором:
Sentry.setUser({ id: user.id }). Email и имя в событиях ошибок не нужны для отладки, а хранятся у третьей стороны. tracesSampleRate: 0.1— 10% запросов для трассировки производительности. Значение 1.0 в продакшене быстро исчерпает квоту.
Также проверьте тексты ошибок. `throw new Error(User ${email} not found) отправит адрес в Sentry в сообщении, и никакой sendDefaultPii` это не остановит.
Клиент и Session Replay
// instrumentation-client.ts
import * as Sentry from "@sentry/nextjs";
Sentry.init({
dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
tracesSampleRate: 0.1,
replaysSessionSampleRate: 0,
replaysOnErrorSampleRate: 0.2,
integrations: [Sentry.replayIntegration({ maskAllText: true, blockAllMedia: true })],
});Replay записывает DOM страницы. maskAllText и blockAllMedia включены по умолчанию — не выключайте их, не проверив, что на страницах нет персональных данных. Запись только сессий с ошибками (replaysOnErrorSampleRate) даёт контекст для отладки без постоянного наблюдения за пользователями.
DSN в браузере публичен по своей природе: он позволяет только отправлять события. Ограничьте допустимые домены в настройках проекта Sentry (Allowed Domains), чтобы чужие сайты не засоряли ваш проект.
Source maps
// next.config.ts
import { withSentryConfig } from "@sentry/nextjs";
const nextConfig = { /* ... */ };
export default withSentryConfig(nextConfig, {
org: "my-org",
project: "web",
authToken: process.env.SENTRY_AUTH_TOKEN,
silent: !process.env.CI,
widenClientFileUpload: true,
sourcemaps: { deleteSourcemapsAfterUpload: true },
});Во время next build плагин загружает source maps в Sentry. deleteSourcemapsAfterUpload удаляет .map-файлы из сборки после загрузки, чтобы исходный код не раздавался всем с вашего сайта. Проверьте после деплоя: запрос к любому .js.map из /_next/static/chunks/ должен возвращать 404.
SENTRY_AUTH_TOKEN — секрет с правом записи в проект. Он нужен только в CI на этапе сборки, не в рантайме и не в переменных с префиксом NEXT_PUBLIC_.
Диагностика
- Стек минифицирован. Source maps не загрузились или релиз события не совпадает с релизом загрузки. Команда
sentry-cli sourcemaps explain <event_id>объясняет, почему конкретное событие не символизировалось. - Серверные ошибки не приходят. Нет
onRequestErrorвinstrumentation.ts, или файл лежит не в корне проекта (при наличииsrc/— внутриsrc/). - Ошибки браузера не приходят у части пользователей. Блокировщики рекламы режут запросы к Sentry. Опция
tunnelRoute: "/monitoring"вwithSentryConfigпроксирует события через ваш домен. Если у сайта строгая CSP, добавьте домен приёма вconnect-src. - Ничего не приходит вообще. Временно включите
debug: trueвSentry.initи смотрите логи сервера и консоль браузера.
Шум и квоты
Не каждая ошибка стоит события. Отфильтруйте ожидаемые: отменённые запросы, ошибки расширений браузера, 404 от ботов. Используйте ignoreErrors для известных сообщений и denyUrls для скриптов расширений. Проект, где каждый день тысяча одинаковых неважных ошибок, приучает команду не смотреть в Sentry вовсе.
Когда Sentry избыточен
Для маленького внутреннего сервиса может хватить структурированных логов с уровнем error и алерта на их количество. Sentry окупается, когда есть клиентский JavaScript, много пользователей и нужно группировать ошибки и видеть, какой релиз их принёс.