كيف تُعدّ تتبّع الأخطاء مع Gurulu

تتوقف معظم منصات التحليلات عند مشاهدات الصفحة والنقرات. تذهب Gurulu أبعد من ذلك بالتقاط الاستثناءات غير المعالجة، ورفض الوعود، وأخطاء الشبكة إلى جانب بيانات تحليلاتك. يرشدك هذا الدليل خلال إعداد تتبّع الأخطاء من الصفر.

لماذا تتتبّع الأخطاء في منصة التحليلات الخاصة بك؟

عندما تعيش الأخطاء في أداة منفصلة، تفقد السياق. تعرف أن مستخدمًا رأى خطأً، لكنك لا تعرف ما فعله قبله أو بعده. تربط Gurulu الأخطاء بجدول الجلسة الزمني الكامل -- مشاهدات الصفحة، والنقرات، وإرسال النماذج -- حتى تتمكن من رؤية ما أدى إلى التعطل بالضبط وما إذا كان المستخدم قد تعافى أو ارتد.

الخطوة 1: أضف برنامج تتبّع الأخطاء النصي

إذا كان لديك بالفعل متتبّع t.js الرئيسي مثبّتًا، فإن تتبّع الأخطاء نشط بالفعل افتراضيًا. تلتقط Gurulu تلقائيًا أحداث window.onerror وunhandledrejection.

لتتبّع الأخطاء المتقدم مع فك تعمية تتبّع المكدس، أضف برنامج الأخطاء النصي المخصص:

<script
  src="https://cdn.gurulu.io/t-errors.js"
  data-site-id="YOUR_SITE_ID"
  data-token="YOUR_TOKEN"
  async
></script>

أو عبر حزمة npm:

import { initErrors } from '@gurulu/web';

initErrors({
  siteId: 'YOUR_SITE_ID',
  token: 'YOUR_TOKEN',
  captureConsole: true,   // optional: capture console.error
  captureNetwork: true,   // optional: capture failed fetch/XHR
});

الخطوة الثانية: رفع خرائط المصدر (Source Maps)

تكون حزم الإنتاج مُصغَّرة (minified)، مما يجعل تتبُّعات المكدس غير قابلة للقراءة. يدعم Gurulu رفع خرائط المصدر حتى ترى أسماء الملفات الأصلية وأرقام الأسطر وأسماء الدوال.

استخدم واجهة CLI لرفع خرائط المصدر كجزء من خط أنابيب البناء لديك:

npx @gurulu/cli sourcemaps upload \
  --site-id YOUR_SITE_ID \
  --release v1.2.0 \
  --directory ./dist

تُخزَّن خرائط المصدر بشكل آمن ولا يتم كشفها أبداً للمستخدمين النهائيين. يمكنك أيضاً تكوين الرفع التلقائي في CI من خلال ضبط متغير البيئة GURULU_TOKEN.

الخطوة الثالثة: عرض الأخطاء في لوحة التحكم

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

عدد الأخطاء والمستخدمون المتأثرون — مدى انتشار المشكلة
أول وآخر ظهور — متى ظهرت وما إذا كانت لا تزال نشطة
تتبُّع المكدس — مع إزالة التعمية إذا تم رفع خرائط المصدر
رابط إعادة تشغيل الجلسة — الانتقال إلى جلسة المستخدم التي حدث فيها الخطأ
تفصيل المتصفح ونظام التشغيل — تحديد العلل الخاصة ببيئة معينة

الخطوة الرابعة: إعداد التنبيهات

يمكن لـ Gurulu إشعارك عند ظهور نوع خطأ جديد أو عند ارتفاع حاد في خطأ قائم. اذهب إلى الإعدادات > التنبيهات وأنشئ قاعدة. يمكنك توجيه التنبيهات إلى Slack أو البريد الإلكتروني أو أي نقطة نهاية webhook.

نصائح لتتبُّع الأخطاء بفعالية

وسِّم الإصدارات. مرِّر دائماً مُعرِّف إصدار حتى تتمكن من تصفية الأخطاء حسب النشر ورؤية ما إذا كان إصدار جديد قد أدخل تراجعات (regressions) بسرعة.

أضِف السياق. استخدم gurulu.setUser() لربط هوية المستخدم بالأخطاء. يسهِّل هذا معرفة العملاء المتأثرين والتواصل معهم بشكل استباقي.

راقب أخطاء الشبكة. فعِّل captureNetwork لالتقاط استدعاءات API الفاشلة. غالباً ما تكون هذه هي السبب الجذري وراء الشاشات الفارغة وواجهات المستخدم المعطّلة.