Sentry в Next.js App Router: серверные и клиентские ошибки, source maps без PII
Co powinno się stać
Błąd w komponencie serwera, Route Handler, Server Action lub w przeglądarce trafia do Sentry z czytelnym stosem (nazwy plików i linie źródłowe, a nie zminimalizowany pakiet), ze wskazaniem wydania i bez osobistych danych użytkownika w tym przypadku.
Instalacja
npx @sentry/wizard@latest -i nextjs
Kreator tworzy pliki i edytuje next.config. Dowiedz się, co zrobił, a następnie ich wesprzyj:
instrumentation-client.ts(w starszych wersjach SDK -sentry.client.config.ts) - inicjalizacja w przeglądarce.sentry.server.config.tsisentry.edge.config.ts- dla środowiska wykonawczego Node.js i Edge.instrumentation.tsto punkt wejścia, który wywołuje Next.js podczas uruchamiania serwera.app/global-error.tsx— limit błędów dla układu głównego.
[[VB_1_KOD]]
onRequestError to hak Next.js 15, który jest wywoływany w przypadku błędów renderowania w procedurach obsługi tras i akcjach serwera. Bez tej linii błędy serwera często nie docierają do Sentry: Next.js sam je przechwytuje i wyświetla użytkownikowi stronę błędu.
Konfiguracja serwera bez 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(jest to ustawienie domyślne, ale lepsze jest jawne) - SDK nie dołącza adresu IP, plików cookie ani nagłówków danych użytkownika.beforeSend- ostatnia linia: usuwa to, co mogłoby przedostać się przez integracje lub własny kontekst. Szczególnie niebezpieczna jest treść żądania (request.data), która zawiera hasła z formularza logowania oraz dane dotyczące płatności.- Określ użytkownika tylko poprzez identyfikator:
Sentry.setUser({ id: user.id }). Adres e-mail i nazwa w zdarzeniach błędów nie są potrzebne do debugowania, ale są przechowywane przez stronę trzecią. tracesSampleRate: 0.1- 10% żądań śledzenia wydajności. Wartość 1,0 w produkcji szybko wyczerpie limit.
Sprawdź także teksty błędów. `throw new Error(Nie znaleziono użytkownika ${email}) отправит адрес в Sentry в сообщении, и никакой sendDefaultPii` nie zatrzyma tego.
Powtórka klienta i sesji
// 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 zapisuje DOM strony. maskAllText i blockAllMedia są domyślnie włączone - nie wyłączaj ich bez upewnienia się, że strony nie zawierają danych osobowych. Rejestrowanie tylko nieudanych sesji (replaysOnErrorSampleRate) zapewnia kontekst do debugowania bez ciągłego monitorowania użytkowników.
DSN w przeglądarce jest z natury publiczny: umożliwia jedynie wysyłanie zdarzeń. Ogranicz dozwolone domeny w ustawieniach projektu Sentry (Dozwolone domeny), aby witryny innych osób nie blokowały Twojego projektu.
Mapy źródłowe
[[VB_4_KOD]]
Podczas next build wtyczka ładuje mapy źródłowe do Sentry. deleteSourcemapsAfterUpload usuwa pliki .map z kompilacji po przesłaniu, dzięki czemu kod źródłowy nie jest udostępniany wszystkim w Twojej witrynie. Sprawdź po wdrożeniu: żądanie do dowolnego .js.map z /_next/static/chunks/ powinno zwrócić 404.
SENTRY_AUTH_TOKEN to sekret z uprawnieniami do zapisu w projekcie. Jest potrzebny tylko w CI na etapie kompilacji, a nie w czasie wykonywania i nie w zmiennych z przedrostkiem NEXT_PUBLIC_.
Diagnostyka
- Stos jest zminimalizowany. Mapy źródłowe nie zostały załadowane lub wydanie wydarzenia nie pokrywa się z wydaniem do pobrania. Komenda
sentry-cli sourcemaps explain <event_id>wyjaśnia, dlaczego dane zdarzenie nie zostało symbolizowane. - Błędy serwera nie wychodzą. Nie ma
onRequestErrorwinstrumentation.tslub pliku nie ma w katalogu głównym projektu (jeśli jestsrc/- wsrc/). - U niektórych użytkowników nie występują błędy przeglądarki. Blokery reklam blokują żądania do Sentry. Opcja
tunnelRoute: "/monitoring"wwithSentryConfigbędzie przesyłać zdarzenia przez Twoją domenę. Jeśli witryna ma ścisły CSP, dodaj domenę odbiorczą doconnect-src. - W ogóle nic nie dociera. Tymczasowo włącz
debug: truewSentry.initi spójrz na logi serwera i konsolę przeglądarki.
Hałas i limity
Nie każdy błąd jest warty wydarzenia. Odfiltruj oczekiwane: anulowane żądania, błędy rozszerzeń przeglądarki, 404 od botów. Użyj ignoreErrors dla znanych wiadomości i denyUrls dla skryptów rozszerzeń. Projekt, w którym każdego dnia pojawia się tysiąc identycznych, nieistotnych błędów, uczy zespół, aby w ogóle nie patrzeć na Sentry'ego.
Kiedy Sentry jest zbędny
W przypadku małej usługi wewnętrznej mogą wystarczyć logi strukturalne z poziomem error i alertem o ich liczbie. Sentry opłaca się, gdy istnieje JavaScript po stronie klienta, wielu użytkowników i trzeba pogrupować błędy i zobaczyć, która wersja je spowodowała.