تتبع الأخطاء

​

ما الذي تفعله

تلتقط وحدة تتبع الأخطاء الانهيارات والاستثناءات من تطبيقك وتحوّلها إلى مشاكل قابلة للتصرّف في لوحة التحكم — دون الحاجة لبناء خط أنابيب (pipeline) خاص بك للإبلاغ عن الانهيارات.

• التقاط تلقائي. بمجرد تهيئة الـ SDK، يتم الإبلاغ عن الأخطاء غير الملتقطة دون أي كود إضافي من جهتك.
• الإبلاغ اليدوي. التقط استثناءً بنفسك وأرسله مع سياق إضافي — bugType، وbugSeverity، وبيانات وصفية (metadata) حرّة (معرّف المستخدم، الإجراء الذي كان يُنفَّذ، أو أي شيء آخر مفيد للتصحيح).
• سياق الجهاز والتطبيق مع كل تقرير. طراز الجهاز، النظام/الإصدار، المعمارية (architecture)، المنطقة الزمنية، الدولة، وإصدار/رقم بناء تطبيقك تُرفَق تلقائياً — لا حاجة لجمعها وإرسالها بنفسك.
• ملخّصات مدعومة بالذكاء الاصطناعي. تتضمّن تفاصيل الخطأ في لوحة التحكم لوحة ملخّص بالذكاء الاصطناعي تساعدك على فهم ما حدث بشكل أسرع.
• إسناد ومناقشة. أسنِد خطأً لأحد زملائك وعلّق عليه مباشرة في لوحة التحكم أثناء العمل على إصلاحه.

​

التصنيف

تحمل التقارير bugType (مثل crash، networkError، uiBug، performance) وbugSeverity (من critical إلى low) لتتمكّن من الفرز حسب الأولوية. راجع دليل منصتك لمعرفة القائمة الكاملة للقيم.

​

كيف تُجمَّع الأخطاء في مشكلات

لا ينشئ Lerix مشكلة (issue) جديدة لكل تقرير. تُجمَّع التقارير المتكرّرة للخطأ نفسه في مشكلة واحدة، فالخطأ الذي يحدث 10,000 مرة يظهر مرة واحدة مع عدّاد. يحدّد أمران المشكلة التي ينتمي إليها التقرير:

• السطر الأول من رسالة الخطأ بعد إخفاء الأجزاء المتغيّرة. تُستبدَل الأرقام ومعرّفات UUID والمعرّفات الست عشرية (hex) وعناوين البريد الإلكتروني والروابط قبل المقارنة. فرسالتا Order 1234 not found و Order 5678 not found مشكلة واحدة. أما رموز الأخطاء مثل #441 أو PGRST202 فتبقى كما هي، فتظلّ الرموز المختلفة مشكلات مختلفة.
• أول إطار في المكدس (stack frame) ينتمي إلى تطبيقك. تُتجاوَز إطارات الـ SDK الخاص بـ Lerix وبيئة التشغيل (runtime) والاعتماديات (مثل node_modules أو package:flutter أو System.*). ويُستخدم اسم الدالة واسم الملف فقط، مع تجاهل أرقام الأسطر والأعمدة وبصمات المحتوى التي يضيفها المُجمِّع (bundler) إلى أسماء الملفات (مثل chunk-Cr8GYWvZ.js).

ولأن أرقام الأسطر وبصمات الحزم لا تُحتسب، يبقى خطأ الويب المشكلةَ نفسها عبر عمليات النشر بدلاً من أن يبدأ من جديد مع كل بناء. يجري التجميع على خادم Lerix، لذا ينطبق تلقائياً على جميع إصدارات الـ SDK.

​

ما تعرضه لوحة التحكم لكل مشكلة

تُرتَّب قائمة المشكلات حسب Last seen، فيظهر ما يحدث الآن في الأعلى.

​

الحالة والانتكاسات والمشكلات المتجاهَلة

تنطبق الحالة والخطورة والشخص المُسنَد إليه على المشكلة كلها، لا على تقرير واحد.

• الانتكاسات (regressions). إذا تكرّرت مشكلة وضعتَ عليها حالة «تم الحل» أو «مغلقة»، يُعاد فتحها تلقائياً ويتلقّى أعضاء المشروع بريد تغيّر الحالة.
• المشكلات المتجاهَلة. تستمر المشكلة المتجاهَلة في عدّ مرات الحدوث، لكنها تبقى متجاهَلة ولا ترسل أي إشعارات، وتُخفى من القائمة الافتراضية. استخدم مرشّح Ignored لعرضها.

​

قواعد الضوضاء المدمجة

يرشّح الخادم بضعة أنواع من التقارير لا تشير أبداً إلى خطأ في كودك. تنطبق هذه القواعد على كل مشروع وكل إصدار من الـ SDK: كذلك لا تُبلغ حزم SDK الخاصة بالخادم (NestJS وPython وASP.NET Core) عن استثناءات HTTP من فئة 4xx افتراضياً، فهي أخطاء من جهة العميل وليست أخطاء في الخادم.

​

ترشيح الأخطاء في تطبيقك

للضوضاء الخاصة بتطبيقك، تقبل كل حزمة SDK خيارين عند التهيئة:

• قائمة تجاهل. النص (string) يحذف أي خطأ تحتوي رسالته عليه، دون تمييز حالة الأحرف. والتعبير النمطي (regular expression) يحذف أي خطأ تطابقه رسالته. تُتجاوَز النصوص الفارغة.
• دالة قبل الإرسال (before-send). تستقبل حدث الخطأ، فتعيده كما هو لإرساله، أو تعيد نسخة معدّلة منه (مثلاً بعد إخفاء رمز وصول)، أو لا تعيد شيئاً (null أو nil أو None) لحذفه.

تعمل قائمة التجاهل أولاً، ولا ترى الدالة إلا ما تبقّى. إذا رمت الدالة استثناءً، يُرسَل الحدث الأصلي ولا يصل الاستثناء إلى تطبيقك. وتجري المطابقة في الحالتين على عنوان المشكلة، الذي يتضمّن صنف الخطأ، مثل TypeError: boom. تحصل حزم React وNext.js وAngular على هذين الخيارين من @lerix-dev/lerix-core 1.3.0. لا تحتوي حزم SDK على أنماط تجاهل مدمجة خاصة بها، إذ تتولّى قواعد الخادم أعلاه الضوضاء الشائعة.

​

خرائط المصدر (Source maps)

تكون بناءات الويب للإنتاج مُصغَّرة (minified)، لذا يشير تتبّع المكدس في المتصفح إلى مواضع داخل الأجزاء المُجمَّعة (bundled chunks)، مثل onConnMessage@https://app.com/chunk-Cr8GYWvZ.js:10:14780، بدلاً من كودك. ارفع خرائط المصدر الخاصة ببنائك عبر أداة Lerix CLI، وستعرض الأخطاء الجديدة الملف والسطر والدالة الأصلية (مثل src/app/chat/chat.page.ts:142) مع الكود المحيط. تُرفَع الخرائط بشكل خاص وتُزال من مخرجات البناء قبل النشر، فلا يُقدَّم كودك المصدري علناً أبداً. ويرى المساعد الذكي وقضايا GitHub وخادم MCP المكدس المقروء أيضاً. لا تحتاج حزم SDK الخاصة بالخادم إلى أي رفع. يقرأ NestJS ملفات .js.map التي يكتبها nest build (راجع ملفات TypeScript وأرقام الأسطر)، ويقرأ ASP.NET Core معلومات التصحيح (debug info) في بنائك (راجع الملفات وأرقام الأسطر).

​

ابدأ الآن

المزيد من أدلة المنصات قادمة قريباً — راجع صفحة البدء لمعرفة حالة كل منصة.