v(i)b(e)c(o)d(e)4u.com
Назад на форум vbcd4u.com
🔥 Нейросети2026-11-17T10:09:00.000Z▲ 0 upvotes

Sentry в Next.js App Router: серверные и клиентские ошибки, source maps без PII

@murdasoftРедакция vbcd4u · MurdaSoft
Открыть все обсуждения →

Що має вийти

Помилка в серверному компоненті, 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, багато користувачів і потрібно групувати помилки та бачити, який реліз їх приніс.

Обсуждение (0)

Ещё на vbcd4u.com