مقدمة
بعد إكمال تثبيت 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
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) تتبّع الطلب الخاص به.
الإبلاغ عن خطأ يدوياً
orders.py
except يمكنك حذف الاستثناء وستلتقط capture_exception()
الاستثناء الجاري معالجته. لا تُلقي استثناءً أبداً ولا تحجب التنفيذ: يُرسَل
التقرير من خيط في الخلفية، ويكتمل Future المُعاد عند قبول التقرير أو
التخلي عنه. استخدم capture_message لشيء لم يُلقَ كاستثناء:
المعاملات
قيم BugType
قيم BugSeverity
ما يُرفق بالتقرير
الإرسال قبل الخروج
تُرسَل التقارير في الخلفية. لا تحتاج الخوادم طويلة التشغيل إلى فعل شيء، وتُرسل الحزمة ما تبقى عند خروج المفسّر الطبيعي. في السكربتات القصيرة والعمّال ومعالجات serverless، استدعِflush() قبل العودة:
دوال أخرى
يمكن أيضاً إنشاء
LerixClient مباشرة بالخيارات نفسها التي تقبلها init()
عندما تحتاج إلى أكثر من عميل في العملية الواحدة.
التعطيل في الاختبارات
مرّرenabled=False لتحويل كل استدعاء إلى لا شيء دون تغيير الكود: