Next.js қолданба маршрутизаторындағы Sentry: сервер мен клиент қателері, PII жоқ бастапқы карталар
Не болуы керек
Сервер құрамдас бөлігі, Маршрут өңдеушісі, Сервер әрекеті немесе шолғыштағы қате оқылатын стекпен (файл атаулары мен бастапқы жолдар, кішірейтілген бума емес), шығарылым көрсеткішімен және оқиға кезінде жеке пайдаланушы деректерінсіз Sentry-ге өтеді.
Орнату
npx @sentry/wizard@latest -i nextjs
Шебер файлдарды жасайды және next.config өңдейді. Оның не істегенін анықтаңыз, содан кейін сіз оларды қолдайсыз:
instrumentation-client.ts(SDK ескі нұсқаларында -sentry.client.config.ts) - браузерде баптандыру.sentry.server.config.tsжәнеsentry.edge.config.ts- Node.js және Edge жұмыс уақыты үшін.instrumentation.ts— сервер іске қосылғанда Next.js шақыратын кіру нүктесі.app/global-error.tsx— түбірлік орналасу үшін қате шегі.
// 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 — маршрут өңдеушілері мен сервер әрекеттеріндегі қателерді көрсету кезінде шақырылатын Next.js 15 ілгегі. Бұл жолсыз сервер қателері жиі Sentry-ге жетпейді: Next.js оларды өзі ұстап алады және пайдаланушыға қате бетін көрсетеді.
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(бұл әдепкі, бірақ анық жақсырақ) - SDK IP мекенжайын, cookie файлдарын және пайдаланушы деректерінің тақырыптарын тіркемейді.beforeSend- соңғы жол: интеграциялар немесе жеке контекст арқылы алуға болатын нәрсені жояды. Сұраныстың негізгі бөлігі (request.data) ерекше қауіпті: онда кіру пішініндегі құпия сөздер мен төлем деректері бар.- Пайдаланушыны тек идентификатор арқылы көрсетіңіз:
Sentry.setUser({ id: user.id }). Қате оқиғаларындағы электрондық пошта және атау отладтау үшін қажет емес, бірақ үшінші тарапта сақталады. tracesSampleRate: 0.1- өнімділікті бақылауға арналған сұраулардың 10%. Өндірістегі 1,0 мәні квотаны тез аяқтайды.
Сондай-ақ қате мәтіндерін тексеріңіз. `throw new Error(${email} пайдаланушысы табылмады) отправит адрес в Sentry в сообщении, и никакой sendDefaultPii` оны тоқтатпайды.
Клиент және сеансты қайталау
// 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 })],
});Қайталау беттің DOM мәнін жазады. maskAllText және blockAllMedia әдепкі бойынша қосылған - беттерде жеке ақпарат жоқ екеніне көз жеткізбестен оларды өшірмеңіз. Тек сәтсіз сеанстарды жазу (replaysOnErrorSampleRate) пайдаланушыларды үнемі бақыламай күйді түзету үшін мәтінмән береді.
Браузердегі DSN табиғаты бойынша жалпыға ортақ: ол тек оқиғаларды жіберуге мүмкіндік береді. Басқа адамдардың сайттары жобаңызды бітеп алмас үшін Sentry жобасының параметрлерінде (Рұқсат етілген домендер) рұқсат етілген домендерді шектеңіз.
Бастапқы карталар
// 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 },
});next build кезінде плагин бастапқы карталарды Sentry-ге жүктейді. deleteSourcemapsAfterUpload жүктеп салғаннан кейін .map файлдарын құрастырудан жояды, осылайша бастапқы код сіздің сайтыңыздағы барлық адамдармен бөлісілмейді. Орналастырудан кейін тексеру: /_next/static/chunks/ жіберген кез келген .js.map сұрауы 404 мәнін қайтаруы керек.
SENTRY_AUTH_TOKEN - жобаға жазу рұқсаты бар құпия. Ол орындау уақытында және NEXT_PUBLIC_ префиксі бар айнымалыларда емес, құрастыру сатысында тек CI жүйесінде қажет.
Диагностика
- Стек кішірейтілді. Бастапқы карталар жүктелмеді немесе оқиға шығарылымы жүктеп алу шығарылымымен сәйкес келмейді.
sentry-cli sourcemaps explain <event_id>пәрмені белгілі бір оқиғаның неліктен таңбаланбағанын түсіндіреді. - Сервер қателері келмейді.
instrumentation.tsішіндеonRequestErrorжоқ немесе файл жоба түбірінде жоқ (егерsrc/болса -src/ішінде). - Кейбір пайдаланушылар үшін шолғыш қателері орын алмайды. Жарнамалық блокаторлар Sentry қызметіне сұрауларды қысқартады.
withSentryConfigішіндегіtunnelRoute: "/monitoring"опциясы доменіңіз арқылы оқиғаларды проксиге жібереді. Егер сайтта қатаң CSP болса, қабылдау доменінconnect-srcішіне қосыңыз. - Ештеңе мүлде келмейді.
Sentry.initішіндеdebug: trueуақытша қосыңыз және сервер журналдары мен шолғыш консолін қараңыз.
Шу және квоталар
Әрбір қателік оқиғаға тұрарлық емес. Күтілетіндерді сүзгіден өткізіңіз: жойылған сұраулар, шолғыш кеңейтімі қателері, боттардан 404. Белгілі хабарлар үшін ignoreErrors және кеңейтім сценарийлері үшін denyUrls пайдаланыңыз. Күн сайын мыңдаған бірдей маңызды емес қателер болатын жоба команданы Сентриге мүлде қарамауға үйретеді.
Sentry артық болғанда
Шағын ішкі қызмет үшін error деңгейіндегі құрылымдық журналдар және олардың саны туралы ескерту жеткілікті болуы мүмкін. Sentry клиенттік JavaScript, пайдаланушылар көп болған кезде өтеледі және қателерді топтап, олардың қай шығарылым әкелгенін көру керек.