Sentry в Next.js App Router: серверные и клиентские ошибки, source maps без PII
Was soll passieren
Ein Fehler in einer Serverkomponente, Route Handler, Server Action oder im Browser geht mit einem lesbaren Stack (Dateinamen und Quellzeilen, kein minimiertes Bundle), mit Release-Hinweis und ohne persönliche Benutzerdaten im Eventfall an Sentry.
Installation
npx @sentry/wizard@latest -i nextjs
Der Assistent erstellt Dateien und bearbeitet next.config. Finden Sie heraus, was er getan hat, und unterstützen Sie sie dann:
instrumentation-client.ts(in älteren Versionen des SDK -sentry.client.config.ts) – Initialisierung im Browser.
– sentry.server.config.ts und sentry.edge.config.ts – für Node.js und Edge-Laufzeit. – instrumentation.ts ist der Einstiegspunkt, den Next.js beim Start des Servers aufruft.
app/global-error.tsx– Fehlergrenze für das Root-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 ist ein Next.js 15-Hook, der bei Renderingfehlern in Routenhandlern und Serveraktionen aufgerufen wird. Ohne diese Zeile erreichen Serverfehler Sentry oft nicht: Next.js fängt sie selbst ab und zeigt dem Benutzer eine Fehlerseite an.
Serverkonfiguration ohne 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 (dies ist die Standardeinstellung, aber explizit ist besser) – Das SDK hängt die IP-Adresse, Cookies und Benutzerdaten-Header nicht an.
beforeSend– letzte Zeile: Entfernt, was durch Integrationen oder Ihren eigenen Kontext gelangen könnte. Der Hauptteil der Anfrage (request.data) ist besonders gefährlich: Er enthält Passwörter aus dem Anmeldeformular und Zahlungsdaten.- Geben Sie den Benutzer nur anhand der Kennung an:
Sentry.setUser({ id: user.id }). Die E-Mail-Adresse und der Name in Fehlerereignissen werden nicht zum Debuggen benötigt, sondern von Dritten gespeichert.
– tracesSampleRate: 0.1 – 10 % der Anfragen zur Leistungsverfolgung. Ein Wert von 1,0 in der Produktion wird das Kontingent schnell erschöpfen.
Überprüfen Sie auch die Fehlertexte. `throw new Error(Benutzer ${email} nicht gefunden) отправит адрес в Sentry в сообщении, и никакой sendDefaultPii` wird es nicht stoppen.
Client- und Sitzungswiedergabe
// 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 schreibt das DOM der Seite. maskAllText und blockAllMedia sind standardmäßig aktiviert. Deaktivieren Sie sie nicht, ohne sicherzustellen, dass die Seiten keine persönlichen Informationen enthalten. Die Aufzeichnung nur fehlgeschlagener Sitzungen (replaysOnErrorSampleRate) bietet Kontext für das Debuggen, ohne dass Benutzer ständig überwacht werden müssen.
Der DSN im Browser ist von Natur aus öffentlich: Er ermöglicht nur das Senden von Ereignissen. Beschränken Sie die zulässigen Domänen in den Sentry-Projekteinstellungen (Zulässige Domänen), damit die Websites anderer Personen Ihr Projekt nicht verstopfen.
Quellkarten
// 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 },
});Während next build lädt das Plugin Quellkarten in Sentry. deleteSourcemapsAfterUpload entfernt .map-Dateien nach dem Hochladen aus dem Build, sodass der Quellcode nicht mit jedem auf Ihrer Website geteilt wird. Überprüfung nach der Bereitstellung: Eine Anfrage an einen beliebigen .js.map von /_next/static/chunks/ sollte 404 zurückgeben.
SENTRY_AUTH_TOKEN ist ein Geheimnis mit Schreibberechtigung für das Projekt. Es wird nur in CI in der Build-Phase benötigt, nicht zur Laufzeit und nicht in Variablen mit dem Präfix NEXT_PUBLIC_.
Diagnose
- Der Stapel ist minimiert. Quellkarten wurden nicht geladen oder die Ereignisversion stimmt nicht mit der Download-Version überein. Der Befehl
sentry-cli sourcemaps explain <event_id>erklärt, warum ein bestimmtes Ereignis nicht symbolisiert wurde. - Serverfehler treten nicht auf. Es gibt keinen
onRequestErrorininstrumentation.ts, oder die Datei befindet sich nicht im Projektstamm (wennsrc/vorhanden ist – innerhalb vonsrc/). - Bei einigen Benutzern treten keine Browserfehler auf. Werbeblocker unterdrücken Anfragen an Sentry. Die Option
tunnelRoute: "/monitoring"inwithSentryConfigleitet Ereignisse über Ihre Domain weiter. Wenn die Site über einen strengen CSP verfügt, fügen Sie die empfangende Domäne zuconnect-srchinzu. - Es kommt überhaupt nichts an. Aktivieren Sie vorübergehend
debug: trueinSentry.initund sehen Sie sich die Serverprotokolle und die Browserkonsole an.
Lärm und Quoten
Nicht jeder Fehler ist die Veranstaltung wert. Filtern Sie die erwarteten heraus: abgebrochene Anfragen, Browser-Erweiterungsfehler, 404 von Bots. Verwenden Sie ignoreErrors für bekannte Nachrichten und denyUrls für Erweiterungsskripte. Ein Projekt, bei dem es jeden Tag tausend identische unwichtige Fehler gibt, lehrt das Team, Sentry überhaupt nicht anzuschauen.
Wenn Sentry überflüssig ist
Für einen kleinen internen Dienst können strukturierte Protokolle mit der Ebene error und eine Benachrichtigung über deren Anzahl ausreichen. Sentry zahlt sich aus, wenn clientseitiges JavaScript vorhanden ist, viele Benutzer vorhanden sind und Sie Fehler gruppieren und sehen müssen, welche Version sie verursacht hat.