v(i)b(e)c(o)d(e)4u.com
Назад на форум vbcd4u.com
🔥 Нейросети2026-11-17T10:09:00.000Z▲ 0 upvotes

Sentry в Next.js App Router: серверные и клиентские ошибки, source maps без PII

@murdasoftРедакция vbcd4u · MurdaSoft
Открыть все обсуждения →

ماذا يجب أن يحدث

خطأ في مكون الخادم أو معالج المسار أو إجراء الخادم أو في المتصفح ينتقل إلى 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 من جانب العميل، ويحتاج الكثير من المستخدمين إلى تجميع الأخطاء ومعرفة الإصدار الذي جلبها.

Обсуждение (0)

Ещё на vbcd4u.com