كيفية إضافة Sentry إلى مشروع Node.js باستخدام TypeScript

تُعد Sentry.io واحدة من أبرز خدمات المراقبة الخارجية وتسجيل الأخطاء، إذ تساعد المطورين على اكتشاف الأعطال البرمجية وتحليلها بسرعة وبدقة. وعند دمجها مع مشروع Node.js المكتوب باستخدام TypeScript، يصبح من السهل تتبع الاستثناءات، وفهم مسار الخطأ، والاطلاع على معلومات إضافية مثل stack trace وbreadcrumbs، مما يختصر وقت التشخيص ويرفع جودة التطبيق.

في هذا الدليل، ستتعرف على الخطوات العملية لإضافة Sentry إلى مشروعك، بدءاً من إنشاء الحساب وحتى تهيئة لوحة التحكم والتقاط الأخطاء داخل الكود.

ما هي خدمة Sentry ولماذا تحتاجها في مشاريع Node.js؟

عند تشغيل أي تطبيق حقيقي في بيئة الإنتاج، فإن الاعتماد على رسائل console أو السجلات المحلية فقط لا يكون كافياً لفهم الأعطال المعقدة. هنا تظهر أهمية Sentry كأداة متقدمة لمراقبة الأخطاء.

• تجميع الأخطاء في مكان مركزي يسهل مراجعته.
• عرض stack trace بشكل منظم لفهم مصدر المشكلة.
• تسجيل تسلسل الأحداث السابقة للخطأ عبر breadcrumbs.
• المساعدة في تسريع عمليات triage وتشخيص المشكلات.
• إمكانية ضبط التنبيهات وربطها مع أدوات خارجية مثل Discord.

كيفية تجهيز حساب Sentry للمشروع

ابدأ بالتوجه إلى موقع Sentry ثم اضغط على خيار Get Started لإنشاء حساب جديد.

يمكنك التسجيل عبر OAuth أو إنشاء بيانات دخول مستقلة خاصة بك. وإذا اخترت التسجيل اليدوي، فسيُطلب منك إدخال اسم organization، ويمكنك تعديله لاحقاً إذا رغبت.

بعد إنشاء الحساب، ستنتقل إلى معالج إعداد أول مشروع. اضغط على I’m Ready للبدء.

عند اختيار المنصة، يجب تحديد NODE.JS لأنه الخيار الملائم لهذا النوع من المشاريع، ثم اضغط على Create Project. بعد ذلك ستظهر لك صفحة تتضمن تعليمات دمج SDK، ومن المهم إبقاء هذه الصفحة مفتوحة لأنك ستحتاج إلى قيمة dsn لاحقاً.

تثبيت حزم Sentry داخل مشروع Node.js

الخطوة التالية هي تثبيت الحزم المطلوبة لدمج الخدمة مع مشروعك:

npm install @sentry/node @sentry/integrations

تؤدي كل حزمة دوراً محدداً:

• @sentry/node: الحزمة الأساسية الخاصة بدمج Sentry في تطبيقات Node.js.
• @sentry/integrations: تتضمن أدوات إضافية من بينها RewriteFrames المستخدمة لتحسين مسارات الملفات داخل تقارير الأخطاء.

يفضل دائماً تحميل Sentry في أقرب نقطة من بداية تشغيل التطبيق، وغالباً يكون ذلك في ملف الدخول الرئيسي مثل index.ts.

كيفية تهيئة Sentry في ملف TypeScript الرئيسي

ابدأ أولاً باستيراد الحزم داخل ملف التشغيل الرئيسي:

import * as Sentry from "@sentry/node";
import { RewriteFrames } from "@sentry/integrations";

الاستيراد الأول يفعّل أدوات Sentry-Node، بينما يوفّر الاستيراد الثاني التكامل RewriteFrames الذي يساعد على ضبط مسارات stack trace بشكل صحيح، خاصة عند العمل على ملفات TypeScript التي تُحوَّل لاحقاً إلى JavaScript.

بعد ذلك، قم بتهيئة Sentry عبر استدعاء Sentry.init() وتمرير إعدادات الاتصال:

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
  integrations: [
    new RewriteFrames({
      root: global.__dirname,
    }),
  ],
});

شرح إعدادات Sentry الأساسية

• dsn: رابط فريد يربط تطبيقك بمشروعك داخل لوحة تحكم Sentry.
• tracesSampleRate: يحدد نسبة الأحداث التي سيتم إرسالها. القيمة 1.0 تعني إرسال 100% من الأحداث الملتقطة.
• integrations: قائمة بالتكاملات الإضافية التي تريد تشغيلها.
• RewriteFrames: يُستخدم لإعادة ضبط المسارات داخل stack trace بحيث تشير بشكل صحيح إلى الملفات الناتجة عن عملية البناء.

إذا وجدت أن إرسال جميع الأحداث ينتج عنه ضوضاء زائدة في لوحة التحكم، يمكنك تخفيض قيمة tracesSampleRate إلى رقم أقل مثل 0.5 أو 0.2 وفقاً لطبيعة مشروعك.

كيفية إرسال الأخطاء إلى Sentry من داخل الكود

بعد إتمام التهيئة، يمكنك إرسال الأخطاء التي يتم التقاطها داخل التطبيق إلى Sentry بسهولة. ويتم ذلك غالباً داخل كتل try / catch أو في سلاسل .catch().

try {
  // some code
} catch (error) {
  Sentry.captureException(error);
}

كلما وقع استثناء وتم تمريره إلى Sentry.captureException(error)، ستتم إضافته إلى لوحة التحكم مع التفاصيل اللازمة لتحليله.

ربط المشروع بلوحة تحكم Sentry بأمان

في صفحة إعداد المشروع داخل Sentry، ستجد قيمة dsn المطلوبة ضمن إعدادات التكوين.

ينبغي التعامل مع dsn على أنه قيمة حساسة، لذلك من الأفضل عدم تضمينه مباشرة داخل الشيفرة المصدرية. بدلاً من ذلك، ضعه داخل ملف .env بالشكل التالي:

SENTRY_DSN=your_dsn_value_here

بهذه الطريقة، سيقرأ التطبيق القيمة من متغير البيئة عبر process.env.SENTRY_DSN.

ملاحظة مهمة لمشاريع Front-End

في مشاريع الواجهة الأمامية، لا يكون استخدام .env بالطريقة نفسها ممكناً دائماً، وقد تضطر إلى كشف dsn بشكل علني. ولتقليل المخاطر، يمكنك ضبط Allowed Domains داخل إعدادات Sentry حتى لا تُقبل البيانات إلا من النطاقات المسموح بها.

بعد إكمال الربط، يمكنك الضغط على خيار View a sample event for this SDK الموجود في أسفل صفحة الإعداد لتوليد حدث تجريبي والتأكد من أن الاتصال يعمل كما يجب.

فهم لوحة تحكم Sentry وتحليل الأخطاء

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

تعرض لوحة الخطأ عادة نوع الاستثناء، ورسالة الخطأ، وبيانات البيئة أو المتصفح إن وُجدت، بالإضافة إلى stack trace وbreadcrumbs. وهذه المعلومات مفيدة جداً عند محاولة إعادة إنتاج الخطأ ومعرفة الخطوات التي أدت إليه.

ما المعلومات التي تقدمها لوحة الخطأ؟

• نوع الخطأ ورسالة الاستثناء.
• الملفات والأسطر المرتبطة بالمشكلة.
• تسلسل الأحداث السابقة لوقوع الخطأ.
• معلومات متعلقة بالبيئة أو المستخدم أو الطلب.

ضبط إعدادات المشروع داخل Sentry

في أعلى لوحة المشروع ستجد اسم المشروع وأيقونة الإعدادات. اضغط على رمز الترس للانتقال إلى إعدادات المشروع.

من هذه الصفحة يمكنك إدارة مجموعة من الخيارات المهمة:

• تغيير Name لتعديل اسم المشروع.
• ضبط Platform بما يتناسب مع بيئة التطبيق حتى تظهر stack traces بشكل صحيح.
• استكشاف خيارات أخرى لتخصيص سلوك المراقبة بما يلائم احتياجات فريقك.

إدارة مفاتيح DSN والتنبيهات

من الشريط الجانبي، ستجد خيار Client Keys (DSN) الذي يسمح لك بنسخ قيمة dsn مرة أخرى عند الحاجة، كما يمكنك حذفها أو إعادة إنشائها إذا تعرضت للكشف عن طريق الخطأ.

أما خيار Alerts فيمنحك القدرة على إعداد آلية استقبال التنبيهات عند وقوع أخطاء جديدة أو تصاعد أخطاء قائمة. ويمكن ربط التنبيهات بعدة وسائل خارجية مثل Discord Webhook.

أفضل الممارسات عند استخدام Sentry في مشاريع TypeScript

• فعّل Sentry في بداية تشغيل التطبيق لتجنب فقدان الأخطاء المبكرة.
• استخدم متغيرات البيئة لحماية dsn في تطبيقات الخادم.
• لا ترسل جميع الأحداث دون مراجعة في المشاريع الكبيرة، بل اضبط tracesSampleRate بعناية.
• احرص على تمرير الأخطاء الملتقطة من كتل try / catch إلى Sentry.captureException.
• راجع لوحة التنبيهات بانتظام لتحديد الأعطال الأكثر تأثيراً على المستخدمين.

الخلاصة التقنية

يُعد دمج Sentry مع مشروع Node.js وTypeScript خطوة عملية لرفع موثوقية التطبيق وتسريع اكتشاف الأعطال قبل تفاقمها. الميزة الأهم ليست مجرد تسجيل الخطأ، بل توفير سياق تحليلي شامل يساعد المطور على فهم السبب الحقيقي للمشكلة واتخاذ قرار إصلاحي أسرع. وإذا تم ضبط الإعدادات بعناية، فستحصل على نظام مراقبة احترافي يدعم استقرار مشروعك على المدى الطويل.