تسجيل السجلات لـ TypeScript: مكتبة Winston

ما هو Winston ولماذا هو مطلوب؟

Winston هي مكتبة قوية ومرنة لتسجيل السجلات (logging) في تطبيقات TypeScript و JavaScript. تتيح لك كتابة السجلات في أماكن مختلفة (وحدة التحكم، الملفات، قواعد البيانات) بمستويات أهمية مختلفة. على عكس console.log البسيط، يمنحك Winston تحكمًا كاملاً في تنسيق السجلات، وتدويرها، وتصفيتها.

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

التثبيت

لتثبيت Winston في مشروع TypeScript، قم بتنفيذ الأمر التالي:

npm install winston

يوصى أيضًا بتثبيت الأنواع (types):

npm install --save-dev @types/winston

إذا كنت تستخدم yarn:

yarn add winston

الوظائف الأساسية

• مستويات التسجيل: error, warn, info, http, verbose, debug, silly. كل مستوى له أولوية، ويمكنك تكوين المستويات التي سيتم إخراجها في وسائط النقل (transports) المختلفة.
• وسائط النقل (Transports): طرق إخراج السجلات. المضمنة: Console, File, Http, Stream. يمكنك إنشاء وسائط نقل خاصة بك.
• التنسيقات (Formats): تخصيص مظهر السجلات (JSON، طابع زمني، إخراج ملون).
• تدوير الملفات: من خلال الوحدة الإضافية winston-daily-rotate-file، يمكنك إنشاء ملفات سجلات جديدة تلقائيًا حسب اليوم أو الحجم.
• البيانات الوصفية: تمرير سياق إضافي (مثل معرف الطلب، اسم المستخدم).

مثال على كود TypeScript

لنقم بإنشاء مسجل (logger) بسيط مع إخراج إلى وحدة التحكم وملف:

import winston from 'winston';

const logger = winston.createLogger({  level: 'info',  format: winston.format.combine(    winston.format.timestamp(),    winston.format.json()  ),  transports: [    new winston.transports.Console({      format: winston.format.combine(        winston.format.colorize(),        winston.format.simple()      )    }),    new winston.transports.File({ filename: 'error.log', level: 'error' }),    new winston.transports.File({ filename: 'combined.log' })  ]});

// الاستخدامlogger.info('الخادم يعمل على المنفذ 3000');logger.error('خطأ في الاتصال بقاعدة البيانات', { database: 'main' });

في هذا المثال: يتم إخراج الرسائل المعلوماتية إلى وحدة التحكم (ملونة) وإلى ملف combined.log، بينما يتم إخراج الأخطاء بالإضافة إلى ذلك في ملف error.log. تنسيق السجلات هو JSON مع طابع زمني.

متى نستخدم Winston؟

• في بيئة الإنتاج (production) لمراقبة الأخطاء.
• في بنية الخدمات المصغرة (microservices) لتجميع السجلات في مخزن مركزي.
• عند الحاجة إلى تدقيق إجراءات المستخدمين.
• في المشاريع التي تتطلب تحليل السجلات باستخدام ELK (Elasticsearch, Logstash, Kibana) أو أنظمة أخرى.

Winston هو المعيار الصناعي لتسجيل السجلات في TypeScript. إنه سهل الإعداد، ولكنه في نفس الوقت قابل للتوسع لتلبية المتطلبات المعقدة.