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

Sentry no Next.js App Router: erros de servidor e cliente, mapas de origem sem 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