Sentry в Next.js App Router: серверные и клиентские ошибки, source maps без 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, багато користувачів і потрібно групувати помилки та бачити, який реліз їх приніс.