#المسجل (Logger)

يوفر NocoBase نظام تسجيل عالي الأداء يعتمد على pino. في أي مكان يتوفر فيه context، يمكنك الحصول على مثيل للمسجل (logger) عبر ctx.logger لتسجيل السجلات الرئيسية أثناء تشغيل الإضافة (plugin) أو النظام.

#الاستخدام الأساسي

// يسجل الأخطاء الفادحة (على سبيل المثال: فشل التهيئة)
ctx.logger.fatal('Application initialization failed', { error });

// يسجل الأخطاء العامة (على سبيل المثال: خطأ في طلب واجهة برمجة التطبيقات)
ctx.logger.error('Data loading failed', { status, message });

// يسجل رسائل التحذير (على سبيل المثال: مخاطر الأداء أو عمليات المستخدم غير المتوقعة)
ctx.logger.warn('Current form contains unsaved changes');

// يسجل معلومات التشغيل العامة (على سبيل المثال: تم تحميل المكون)
ctx.logger.info('User profile component loaded');

// يسجل معلومات التصحيح (على سبيل المثال: تغييرات الحالة)
ctx.logger.debug('Current user state', { user });

// يسجل معلومات التتبع التفصيلية (على سبيل المثال: تدفق العرض)
ctx.logger.trace('Component rendered', { component: 'UserProfile' });

تتوافق هذه الطرق مع مستويات تسجيل مختلفة (من الأعلى إلى الأدنى):

#تنسيق السجل

يكون كل إخراج سجل بتنسيق JSON منظم، ويحتوي افتراضيًا على الحقول التالية:

مثال على الإخراج:

{
  "level": 30,
  "time": 1730540153064,
  "pid": 12765,
  "hostname": "nocobase.local",
  "msg": "HelloModel rendered",
  "a": "a"
}

#ربط السياق

يقوم ctx.logger تلقائيًا بحقن معلومات السياق، مثل الإضافة (plugin) الحالية أو الوحدة النمطية أو مصدر الطلب، مما يجعل السجلات قابلة للتتبع بدقة أكبر إلى مصدرها.

plugin.context.logger.info('Plugin initialized');
model.context.logger.error('Model validation failed', { model: 'User' });

مثال على الإخراج (مع السياق):

{
  "level": 30,
  "msg": "Plugin initialized",
  "plugin": "plugin-audit-trail"
}

#المسجل المخصص

يمكنك إنشاء مثيلات مسجل (logger) مخصصة في الإضافات (plugins)، مع وراثة أو توسيع التكوينات الافتراضية:

const logger = ctx.logger.child({ module: 'MyPlugin' });
logger.info('Submodule started');

ترث المسجلات الفرعية (child loggers) تكوين المسجل الرئيسي (main logger) وتُرفق السياق تلقائيًا.

#تسلسل مستويات السجل الهرمي

تتبع مستويات سجل Pino تعريفًا رقميًا من الأعلى إلى الأدنى، حيث تشير الأرقام الأصغر إلى أولوية أقل.
فيما يلي الجدول الكامل لتسلسل مستويات السجل الهرمي:

يقوم Pino فقط بإخراج السجلات التي تكون أكبر من أو تساوي إعداد level الحالي. على سبيل المثال، عندما يكون مستوى السجل info، سيتم تجاهل سجلات debug و trace.

#أفضل الممارسات في تطوير الإضافات (Plugins)

1. استخدام مسجل السياق (Context Logger)
   استخدم ctx.logger في سياقات الإضافة (plugin) أو النموذج أو التطبيق، ليحمل معلومات المصدر تلقائيًا.

2. التمييز بين مستويات السجل

   • استخدم error لتسجيل استثناءات العمل
   • استخدم info لتسجيل تغييرات الحالة
   • استخدم debug لتسجيل معلومات تصحيح الأخطاء الخاصة بالتطوير

3. تجنب الإفراط في التسجيل
   خاصةً عند مستويي debug و trace، يُنصح بتمكينهما فقط في بيئات التطوير.

4. استخدام البيانات المنظمة
   مرر معاملات الكائنات (object parameters) بدلاً من ربط السلاسل النصية (concatenating strings)، مما يساعد في تحليل السجلات وتصفيتها.

باتباع هذه الممارسات، يمكن للمطورين تتبع تنفيذ الإضافات (plugins) بشكل أكثر كفاءة، واستكشاف المشكلات وإصلاحها، والحفاظ على نظام تسجيل منظم وقابل للتوسيع.