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

مقدمة

بعد إكمال تثبيت Python، يُبلَّغ عن الاستثناءات غير المعالَجة تلقائياً. استدعِ lerix.capture_exception() للإبلاغ عن الاستثناءات المعالَجة بنفسك مع سياق إضافي.

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

تثبّت lerix.init() خطافين على مستوى العملية:
  • sys.excepthook. يُبلَّغ عن الاستثناء الذي يفلت من الخيط الرئيسي، ويُمنح مهلة flush_timeout ثانية للإرسال، ثم يُسلَّم إلى الخطاف السابق فيُطبع التتبّع ويخرج المفسّر كالمعتاد. لا يُبلَّغ عن KeyboardInterrupt وSystemExit.
  • threading.excepthook. يُبلَّغ عن الاستثناء الذي يُنهي threading.Thread مع اسم الخيط في metadata.thread.
اضبط capture_unhandled=False لتخطي الخطافين.

asyncio

الاستثناءات داخل المهام التي لا يُنتظر ناتجها أبداً لا يسجّلها asyncio إلا في السجل. استدعِ install_asyncio_handler بعد إنشاء الحلقة للإبلاغ عنها أيضاً:

أطر الويب

تحوّل الأطر الاستثناءات إلى استجابة 500 قبل أن تصل إلى خطافات العملية، لذلك لكل إطار خطافه الخاص. ترفق جميعها طريقة الطلب وعنوانه ومساره ورمز الحالة وترويسة X-Request-Id إن وُجدت، تحت metadata.request، ثم تترك معالجة الأخطاء الخاصة بالإطار تعمل دون تغيير.

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

يقبل كل خطاف دالة should_capture تتلقى الاستثناء ورمز حالة HTTP الذي سيُرسَل (إن كان معروفاً) وتُعيد ما إذا كان يجب الإبلاغ عنه:
main.py
مع Flask مرّرها إلى LerixFlask(app, should_capture=...). مع Django اضبطها على الصنف في settings.py:
settings.py

عدة عملاء

تستخدم الخطافات العميل الذي أنشأته lerix.init(). مرّر client= إلى الخطاف (أو اضبط LerixMiddleware.client مع Django) عندما تبلّغ عملية واحدة إلى أكثر من مشروع.

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

يتطلّب lerix بالإصدار 0.4.0 أو أحدث. يحدّد خياران ما يغادر العملية (process). ينطبقان على كل تقرير أياً كان مصدره: تكاملات أطر العمل، وsys.excepthook / threading.excepthook / معالج asyncio، وcapture_exception / capture_message. استخدمهما للترشيح حسب الرسالة، واستخدم should_capture (أعلاه) للقرار حسب الاستثناء أو حالة HTTP.
main.py
  • تعمل ignore_errors (list[str | re.Pattern]) أولاً، ثم لا ترى before_send إلا ما تبقّى.
  • الرسالة التي تُطابَق وتُمرَّر إلى before_send هي عنوان المشكلة المعروض في لوحة التحكم، مثل ValueError: boom.
  • lerix.ErrorEvent هو dataclass يحتوي على message وstack (قائمة نصوص الإطارات) وtype (BugType) وseverity (BugSeverity) وmetadata (ما مرّرته إلى دالة الالتقاط، أو سياق الطلب من التكامل). تُضاف تفاصيل الجهاز والتطبيق وبيئة التشغيل بعد الدالة، التي تعمل على الخيط (thread) الذي التقط الخطأ.
  • إذا رفعت before_send استثناءً، يُرسَل الحدث الأصلي ويُسجَّل الخطأ فقط، ولا يُبلَّغ عنه ولا يُعاد رفعه أبداً.
  • التقرير المحذوف لا يثبّت (pin) تتبّع الطلب الخاص به.
كما يجمّع Lerix الأخطاء المتكرّرة في مشكلة واحدة ويرشّح الضوضاء الشائعة على الخادم، لكل إصدارات الـ SDK. راجع كيف تُجمَّع الأخطاء في مشكلات.

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

orders.py
داخل كتلة except يمكنك حذف الاستثناء وستلتقط capture_exception() الاستثناء الجاري معالجته. لا تُلقي استثناءً أبداً ولا تحجب التنفيذ: يُرسَل التقرير من خيط في الخلفية، ويكتمل Future المُعاد عند قبول التقرير أو التخلي عنه. استخدم capture_message لشيء لم يُلقَ كاستثناء:

المعاملات

قيم BugType

قيم BugSeverity

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

الإرسال قبل الخروج

تُرسَل التقارير في الخلفية. لا تحتاج الخوادم طويلة التشغيل إلى فعل شيء، وتُرسل الحزمة ما تبقى عند خروج المفسّر الطبيعي. في السكربتات القصيرة والعمّال ومعالجات serverless، استدعِ flush() قبل العودة:

دوال أخرى

يمكن أيضاً إنشاء LerixClient مباشرة بالخيارات نفسها التي تقبلها init() عندما تحتاج إلى أكثر من عميل في العملية الواحدة.

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

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