Sentry в Next.js App Router: серверные и клиентские ошибки, source maps без 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 بنفسه ويعرض للمستخدم صفحة خطأ.
تكوين الخادم بدون معلومات تحديد الهوية الشخصية
// 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 وملفات تعريف الارتباط ورؤوس بيانات المستخدم.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 من الإصدار بعد التحميل بحيث لا تتم مشاركة كود المصدر مع الجميع على موقعك. التحقق بعد النشر: يجب أن يُرجع الطلب إلى أي .js.map من /_next/static/chunks/ 404.
SENTRY_AUTH_TOKEN هو سر مع إذن الكتابة للمشروع. إنه مطلوب فقط في CI في مرحلة الإنشاء، وليس في وقت التشغيل وليس في المتغيرات ذات البادئة NEXT_PUBLIC_.
التشخيص
- تم تصغير المكدس. لم يتم تحميل خرائط المصدر أو أن إصدار الحدث لا يتزامن مع إصدار التنزيل. يشرح الأمر
sentry-cli sourcemaps explain <event_id>سبب عدم ترميز حدث معين. - لا تأتي أخطاء الخادم. لا يوجد
onRequestErrorفيinstrumentation.ts، أو الملف ليس في جذر المشروع (إذا كان هناكsrc/- داخلsrc/). - لا تحدث أخطاء في المتصفح لبعض المستخدمين. تقوم أدوات حظر الإعلانات بقطع الطلبات إلى Sentry. الخيار
tunnelRoute: "/monitoring"فيwithSentryConfigسوف يقوم بتوكيل الأحداث من خلال المجال الخاص بك. إذا كان الموقع يحتوي على CSP صارم، أضف مجال الاستلام إلىconnect-src. - لم يصل أي شيء على الإطلاق. قم بتمكين
debug: trueمؤقتًا فيSentry.initوانظر إلى سجلات الخادم ووحدة تحكم المتصفح.
الضوضاء والحصص
ليس كل خطأ يستحق الحدث. قم بتصفية الطلبات المتوقعة: الطلبات الملغاة، وأخطاء امتداد المتصفح، و404 من الروبوتات. استخدم ignoreErrors للرسائل المعروفة وdenyUrls للبرامج النصية الملحقة. المشروع الذي يوجد فيه ألف خطأ متطابق غير مهم كل يوم يعلم الفريق عدم النظر إلى Sentry على الإطلاق.
عندما يكون الحراسة زائدة عن الحاجة
بالنسبة لخدمة داخلية صغيرة، قد تكون السجلات المنظمة بمستوى error والتنبيه بأرقامها كافية. يؤتي Sentry ثماره عندما يكون هناك JavaScript من جانب العميل، ويحتاج الكثير من المستخدمين إلى تجميع الأخطاء ومعرفة الإصدار الذي جلبها.