الانتقال إلى المحتوى الرئيسي

مقدمة

بعد إكمال تثبيت NestJS، يُبلَّغ عن الاستثناءات غير المعالَجة تلقائياً. احقن LerixService للإبلاغ عن الاستثناءات المعالَجة بنفسك مع سياق إضافي.

الالتقاط التلقائي

تسجّل LerixModule أمرين:
  • مرشّح استثناءات عام. يمرّ عبره كل استثناء يُلقى من متحكم أو حارس أو أنبوب أو معترض. يبلّغ افتراضياً عن الاستثناءات التي ليست HttpException، وعن HttpException برمز 500 فأكثر. لا يُبلَّغ عن أخطاء العميل المتوقعة مثل NotFoundException أو فشل ValidationPipe. ثم يسلّم المرشّح الاستثناء إلى مرشّح Nest الافتراضي، فتبقى استجابة HTTP كما كانت ستكون بدون Lerix.
  • معالجات على مستوى العملية. يُبلَّغ عن uncaughtException وunhandledRejection، ويُمنح التقرير مهلة flushTimeoutMs للإرسال، ثم تخرج العملية برمز 1 كما يفعل Node. اضبط exitOnUnhandled: false لإبقاء العملية حية، أو captureUnhandled: false لتخطي المعالجات.
يحمل كل تقرير تلقائي طريقة الطلب وعنوانه ومساره ورمز الحالة، وترويسة x-request-id (أو x-correlation-id) إن وُجدت، تحت metadata.request.

تغيير ما يُبلَّغ عنه

تتلقى shouldCapture الاستثناء وكائن سياق يحوي تفاصيل الطلب:
app.module.ts

استخدام مرشّحك الخاص

إن كان تطبيقك يسجّل بالفعل APP_FILTER شاملاً، فاضبط captureHttpExceptions: false وأبلغ من ذلك المرشّح:
all-exceptions.filter.ts
يمكنك أيضاً وراثة LerixExceptionFilter وتجاوز catch لتخصيص الاستجابة مع الإبقاء على الإبلاغ.

ترشيح الأخطاء

يتطلّب @lerix-dev/lerix-nestjs بالإصدار 1.4.0 أو أحدث. يحدّد خياران ما يغادر العملية (process). ينطبقان على كل تقرير أياً كان مصدره: المرشّح العام، والاستثناءات غير الملتقطة والوعود المرفوضة غير المعالَجة، وcaptureException / captureMessage. استخدمهما للترشيح حسب الرسالة، واستخدم shouldCapture (أعلاه) للقرار حسب الاستثناء أو الطلب.
app.module.ts
  • تعمل ignoreErrors أولاً، ثم لا ترى beforeSend إلا ما تبقّى.
  • الرسالة التي تُطابَق وتُمرَّر إلى beforeSend هي عنوان المشكلة المعروض في لوحة التحكم، مثل TypeError: Cannot read properties of undefined.
  • يحتوي الحدث على message وstack (أسطر at ...) وtype (BugType) وseverity (BugSeverity) وmetadata (ما مرّرته إلى دالة الالتقاط، أو سياق الطلب من المرشّح). تُضاف تفاصيل الجهاز والتطبيق وبيئة التشغيل بعد الدالة.
  • إذا رمت beforeSend استثناءً، يُرسَل الحدث الأصلي ويُسجَّل الخطأ فقط، ولا يُبلَّغ عنه ولا يُعاد رميه أبداً.
  • التقرير المحذوف لا يثبّت (pin) تتبّع الطلب الخاص به.
استثناءات HttpException التي تقل عن 500 تُتجاوَز أصلاً عبر shouldCapture الافتراضية. كما يجمّع Lerix الأخطاء المتكرّرة في مشكلة واحدة ويرشّح الضوضاء الشائعة على الخادم، لكل إصدارات الـ SDK. راجع كيف تُجمَّع الأخطاء في مشكلات.

الإبلاغ عن خطأ يدوياً

orders.service.ts
لا تُلقي captureException استثناءً أبداً وتكتمل عند قبول التقرير أو التخلي عنه. استخدم captureMessage لشيء لم يُلقَ كاستثناء:

المعاملات

قيم BugType

قيم BugSeverity

ما يُرفق بالتقرير

ملفات TypeScript وأرقام الأسطر

تُعاد تتبّعات المكدس (stack traces) إلى كود TypeScript المصدري تلقائياً. عند الإبلاغ عن خطأ، يقرأ الـ SDK ملفات .js.map التي يكتبها nest build بجانب الكود المُترجَم، فيُبلَّغ عن إطار مثل dist/src/orders/orders.service.js:58 على أنه src/orders/orders.service.ts:42. لا شيء لرفعه، ولا خيار (flag) لـ Node.js، ولا شيء لإعداده. يفعّل Nest الخيار "sourceMap": true في tsconfig.json افتراضياً. تعمل أيضاً خرائط المصدر المضمّنة (inline) وحزم nest build --webpack. تُجعل المسارات نسبية إلى مجلد العمل (working directory) للتطبيق (وهو عادةً جذر المستودع)، فتُقرأ كمسارات داخل المستودع. تظهر إطارات الاعتماديات (dependencies) بصيغة node_modules/....
إذا لم تُنشر ملفات .js.map، تحتفظ الإطارات بموضعها في الكود المُترجَم. يحدث هذا مثلاً مع صورة Docker تنسخ ملفات .js فقط. أبقِ ملفات .js.map بجانب dist/**/*.js داخل الصورة.

دوال LerixService الأخرى

التعطيل في الاختبارات

مرّر enabled: false لتحويل كل استدعاء إلى لا شيء دون تغيير الكود: