Sentry nel router dell'app Next.js: errori del server e del client, mappe di origine senza PII
Cosa dovrebbe succedere
Un errore in un componente server, Route Handler, Server Action o nel browser arriva a Sentry con uno stack leggibile (nomi di file e righe di origine, non un bundle minimizzato), con un'indicazione di rilascio e senza dati personali dell'utente nell'evento.
Installazione
npx @sentry/wizard@latest -i nextjs
La procedura guidata crea file e modifica next.config. Scopri cosa ha fatto, poi li sostieni:
instrumentation-client.ts(nelle versioni precedenti dell'SDK -sentry.client.config.ts) - inizializzazione nel browser.sentry.server.config.tsesentry.edge.config.ts- per Node.js e Edge runtime.instrumentation.tsè il punto di ingresso che Next.js chiama all'avvio del server.app/global-error.tsx— limite di errore per il layout root.
[[VB_1_CODICE]]
onRequestError è un hook Next.js 15 che viene chiamato in caso di errori di rendering nei gestori di route e nelle azioni del server. Senza questa riga, gli errori del server spesso non raggiungono Sentry: Next.js li intercetta lui stesso e mostra all'utente una pagina di errore.
Configurazione del server senza PII
[[VB_2_CODICE]]
sendDefaultPii: false(questa è l'impostazione predefinita, ma esplicito è migliore) - L'SDK non allega l'indirizzo IP, i cookie e le intestazioni dei dati utente.beforeSend- ultima riga: rimuove ciò che potrebbe ottenere attraverso le integrazioni o il proprio contesto. Particolarmente pericoloso è il corpo della richiesta (request.data): contiene le password del modulo di login e i dati di pagamento.- Specificare l'utente solo tramite identificatore:
Sentry.setUser({ id: user.id }). L'e-mail e il nome negli eventi di errore non sono necessari per il debug, ma vengono archiviati da terze parti. tracesSampleRate: 0.1- 10% delle richieste di tracciamento delle prestazioni. Un valore pari a 1,0 nella produzione esaurirà rapidamente la quota.
Controlla anche i testi degli errori. `throw new Error(Utente ${email} non trovato) отправит адрес в Sentry в сообщении, и никакой sendDefaultPii` non lo interromperà.
Riproduzione del client e della sessione
[[VB_3_CODICE]]
Replay scrive il DOM della pagina. maskAllText e blockAllMedia sono abilitati per impostazione predefinita: non disabilitarli senza assicurarsi che le pagine non contengano informazioni personali. La registrazione delle sole sessioni non riuscite (replaysOnErrorSampleRate) fornisce il contesto per il debug senza monitorare costantemente gli utenti.
Il DSN nel browser è pubblico per natura: consente solo di inviare eventi. Limita i domini consentiti nelle impostazioni del progetto Sentry (Domini consentiti) in modo che i siti di altre persone non intasino il tuo progetto.
Mappe di origine
[[VB_4_CODICE]]
Durante next build il plugin carica le mappe sorgente in Sentry. deleteSourcemapsAfterUpload rimuove i file .map dalla build dopo il caricamento in modo che il codice sorgente non venga condiviso con tutti sul tuo sito. Controllo dopo la distribuzione: una richiesta a qualsiasi .js.map da /_next/static/chunks/ dovrebbe restituire 404.
SENTRY_AUTH_TOKEN è un segreto con permesso di scrittura sul progetto. È necessario solo in CI in fase di creazione, non in runtime e non nelle variabili con il prefisso NEXT_PUBLIC_.
Diagnostica
- Lo stack è ridotto. Le mappe di origine non sono state caricate o il rilascio dell'evento non coincide con il rilascio del download. Il comando
sentry-cli sourcemaps explain <event_id>spiega perché un particolare evento non è stato simbolizzato. - Gli errori del server non si verificano. Non c'è
onRequestErrorininstrumentation.ts, oppure il file non è nella radice del progetto (se c'èsrc/- all'interno disrc/). - Gli errori del browser non si verificano per alcuni utenti. I blocchi degli annunci tagliano le richieste a Sentry. L'opzione
tunnelRoute: "/monitoring"inwithSentryConfigproxyerà gli eventi attraverso il tuo dominio. Se il sito ha un CSP rigoroso, aggiungi il dominio ricevente aconnect-src. - Non arriva proprio nulla. Abilita temporaneamente
debug: trueinSentry.inite controlla i registri del server e la console del browser.
Rumore e quote
Non tutti gli errori valgono l’evento. Filtra quelli attesi: richieste annullate, errori di estensione del browser, 404 da bot. Utilizzare ignoreErrors per i messaggi conosciuti e denyUrls per gli script di estensione. Un progetto in cui ogni giorno si commettono mille errori identici e non importanti insegna al team a non guardare affatto Sentry.
Quando Sentry è ridondante
Per un servizio interno di piccole dimensioni potrebbero essere sufficienti i log strutturati con il livello error e un avviso per il loro numero. Sentry ripaga quando c'è JavaScript lato client, molti utenti ed è necessario raggruppare gli errori e vedere quale versione li ha portati.