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
Открыть все обсуждения →

¿Qué debería pasar?

Un error en un componente del servidor, controlador de ruta, acción del servidor o en el navegador va a Sentry con una pila legible (nombres de archivos y líneas de origen, no un paquete minificado), con una indicación de lanzamiento y sin datos personales del usuario en el caso.

Instalación

npx @sentry/wizard@latest -i nextjs

El asistente crea archivos y edita next.config. Averigua qué hizo y luego los apoyarás:

  • instrumentation-client.ts (en versiones anteriores del SDK - sentry.client.config.ts) - inicialización en el navegador.
  • sentry.server.config.ts y sentry.edge.config.ts - para Node.js y Edge runtime.
  • instrumentation.ts es el punto de entrada al que llama Next.js cuando se inicia el servidor.
  • app/global-error.tsx — límite de error para el diseño raíz.
// 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 es un gancho de Next.js 15 que se invoca ante errores de representación en controladores de ruta y acciones del servidor. Sin esta línea, los errores del servidor a menudo no llegan a Sentry: Next.js los intercepta y muestra al usuario una página de error.

Configuración del servidor sin 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 (este es el valor predeterminado, pero explícito es mejor) - El SDK no adjunta la dirección IP, las cookies ni los encabezados de datos del usuario.
  • beforeSend - última línea: elimina lo que podría obtenerse a través de integraciones o de su propio contexto. El cuerpo de la solicitud (request.data) es especialmente peligroso: contiene contraseñas del formulario de inicio de sesión y datos de pago.
  • Especificar el usuario únicamente por identificador: Sentry.setUser({ id: user.id }). El correo electrónico y el nombre en los eventos de error no son necesarios para la depuración, pero los almacena un tercero.
  • tracesSampleRate: 0.1 - 10% de las solicitudes de seguimiento del rendimiento. Un valor de 1,0 en producción agotará rápidamente la cuota.

Consulte también los textos de error. `throw new Error(Usuario ${email} no encontrado) отправит адрес в Sentry в сообщении, и никакой sendDefaultPii` no lo detendrá.

Cliente y repetición de sesión

// 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 })],
});

La reproducción escribe el DOM de la página. maskAllText y blockAllMedia están habilitados de forma predeterminada; no los desactive sin asegurarse de que las páginas no contengan información personal. Grabar solo sesiones fallidas (replaysOnErrorSampleRate) proporciona contexto para la depuración sin monitorear constantemente a los usuarios.

El DSN en el navegador es público por naturaleza: sólo permite enviar eventos. Limite los dominios permitidos en la configuración del proyecto Sentry (Dominios permitidos) para que los sitios de otras personas no obstruyan su proyecto.

Mapas fuente

// 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 },
});

Durante next build el complemento carga mapas fuente en Sentry. deleteSourcemapsAfterUpload elimina los archivos .map de la compilación después de cargarlos para que el código fuente no se comparta con todos en su sitio. Verifique después de la implementación: una solicitud a cualquier .js.map desde /_next/static/chunks/ debe devolver 404.

SENTRY_AUTH_TOKEN es un secreto con permiso de escritura en el proyecto. Solo es necesario en CI en la etapa de compilación, no en tiempo de ejecución ni en variables con el prefijo NEXT_PUBLIC_.

Diagnóstico

  • La pila está minimizada. Los mapas de origen no se cargaron o la publicación del evento no coincide con la publicación de la descarga. El comando sentry-cli sourcemaps explain <event_id> explica por qué un evento en particular no fue simbolizado.
  • Los errores del servidor no llegan. No hay onRequestError en instrumentation.ts, o el archivo no está en la raíz del proyecto (si hay src/ - dentro de src/).
  • Los errores del navegador no ocurren para algunos usuarios. Los bloqueadores de anuncios cortan las solicitudes a Sentry. La opción tunnelRoute: "/monitoring" en withSentryConfig enviará eventos a través de su dominio. Si el sitio tiene un CSP estricto, agregue el dominio receptor a connect-src.
  • No llega nada. Habilite temporalmente debug: true en Sentry.init y mire los registros del servidor y la consola del navegador.

Ruido y cuotas

No todos los errores valen la pena. Filtre los esperados: solicitudes canceladas, errores de extensión del navegador, 404 de bots. Utilice ignoreErrors para mensajes conocidos y denyUrls para scripts de extensión. Un proyecto en el que hay mil errores idénticos sin importancia cada día le enseña al equipo a no mirar a Sentry en absoluto.

Cuando Sentry es redundante

Para un servicio interno pequeño, los registros estructurados con el nivel error y una alerta de su número pueden ser suficientes. Sentry vale la pena cuando hay JavaScript del lado del cliente, muchos usuarios y es necesario agrupar los errores y ver qué versión los generó.

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

Ещё на vbcd4u.com