Sentry in Next.js App Router: server- en clientfouten, bronkaarten zonder PII
Wat zou er moeten gebeuren
Een fout in een servercomponent, Route Handler, Server Action of in de browser gaat naar Sentry met een leesbare stack (bestandsnamen en bronregels, geen verkleinde bundel), met een release-indicatie en in het geval zonder persoonlijke gebruikersgegevens.
Installatie
npx @sentry/wizard@latest -i nextjs
De wizard maakt bestanden aan en bewerkt next.config. Zoek uit wat hij deed, en steun ze dan:
instrumentation-client.ts(in oudere versies van de SDK -sentry.client.config.ts) - initialisatie in de browser.sentry.server.config.tsensentry.edge.config.ts- voor Node.js en Edge-runtime.instrumentation.tsis het toegangspunt dat Next.js aanroept wanneer de server start.app/global-error.tsx— foutlimiet voor de hoofdindeling.
// 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 is een Next.js 15-hook die wordt aangeroepen bij weergavefouten in routehandlers en serveracties. Zonder deze regel bereiken serverfouten Sentry vaak niet: Next.js onderschept ze zelf en toont de gebruiker een foutpagina.
Serverconfiguratie zonder 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(dit is de standaard, maar expliciet is beter) - De SDK voegt het IP-adres, de cookies en de headers van gebruikersgegevens niet toe.beforeSend- laatste regel: verwijdert wat via integraties of uw eigen context zou kunnen binnendringen. Vooral de inhoud van het verzoek (request.data) is gevaarlijk: deze bevat wachtwoorden van het inlogformulier en betalingsgegevens.- Geef de gebruiker alleen op via ID:
Sentry.setUser({ id: user.id }). Het e-mailadres en de naam in foutgebeurtenissen zijn niet nodig voor foutopsporing, maar worden opgeslagen door een derde partij. tracesSampleRate: 0.1- 10% van de verzoeken voor prestatietracering. Een waarde van 1,0 in de productie zal het quotum snel opgebruikt hebben.
Controleer ook de foutteksten. `throw new Error(Gebruiker ${email} niet gevonden) отправит адрес в Sentry в сообщении, и никакой sendDefaultPii` zal het niet stoppen.
Klant- en sessieherhaling
// 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 schrijft de DOM van de pagina. maskAllText en blockAllMedia zijn standaard ingeschakeld - schakel ze niet uit zonder ervoor te zorgen dat de pagina's geen persoonlijke informatie bevatten. Alleen het opnemen van mislukte sessies (replaysOnErrorSampleRate) biedt context voor het opsporen van fouten zonder gebruikers voortdurend te moeten controleren.
De DSN in de browser is van nature openbaar: u kunt er alleen gebeurtenissen mee verzenden. Beperk de toegestane domeinen in de Sentry-projectinstellingen (Toegestane domeinen), zodat de sites van anderen uw project niet verstoppen.
Bronkaarten
// 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 },
});Tijdens next build laadt de plug-in bronkaarten in Sentry. deleteSourcemapsAfterUpload verwijdert .map bestanden uit de build na het uploaden, zodat de broncode niet met iedereen op uw site wordt gedeeld. Controle na implementatie: een verzoek aan een .js.map van /_next/static/chunks/ zou 404 moeten retourneren.
SENTRY_AUTH_TOKEN is een geheim met schrijfrechten voor het project. Het is alleen nodig in CI in de bouwfase, niet in runtime en niet in variabelen met het voorvoegsel NEXT_PUBLIC_.
Diagnostiek
- De stapel is verkleind. Bronkaarten zijn niet geladen of de release van het evenement valt niet samen met de downloadrelease. Het
sentry-cli sourcemaps explain <event_id>commando legt uit waarom een bepaalde gebeurtenis niet werd gesymboliseerd. - Serverfouten komen niet voor. Er is geen
onRequestErrorininstrumentation.ts, of het bestand bevindt zich niet in de hoofdmap van het project (als ersrc/is - insrc/). - Bij sommige gebruikers treden geen browserfouten op. Advertentieblokkers knippen verzoeken naar Sentry. De optie
tunnelRoute: "/monitoring"inwithSentryConfigproxy-evenementen via uw domein. Als de site een strikte CSP heeft, voegt u het ontvangende domein toe aanconnect-src. - Er komt helemaal niets aan. Schakel tijdelijk
debug: trueinSentry.initin en bekijk de serverlogboeken en browserconsole.
Lawaai en quota
Niet elke fout is de gebeurtenis waard. Filter de verwachte verzoeken eruit: geannuleerde verzoeken, fouten in browserextensies, 404 van bots. Gebruik ignoreErrors voor bekende berichten en denyUrls voor extensiescripts. Een project waarbij elke dag duizend identieke, onbelangrijke fouten voorkomen, leert het team helemaal niet naar Sentry te kijken.
Wanneer Sentry overbodig is
Voor een kleine interne dienst kunnen gestructureerde logboeken met het niveau error en een waarschuwing voor hun aantal voldoende zijn. Sentry loont als er JavaScript aan de clientzijde is, veel gebruikers en u fouten moet groeperen en kijken welke release deze heeft veroorzaakt.