دليل شامل لتطبيق التسجيل (Logging) في بايثون باستخدام مكتبة Logzero

يُعد التسجيل (Logging) جزءًا حيويًا من أي تطبيق برمجي، فهو يساعد المطورين على تتبع سير العمليات، اكتشاف الأخطاء، وفهم سلوك البرنامج. في عالم بايثون، توفر مكتبة Logzero، التي أنشأها كريس هاجر (Chris Hager)، حلاً فعالاً ومبسطًا لهذه المهمة، مما يجعل عملية التسجيل سهلة مثل استخدام دالة print() لعرض المعلومات وتفاصيل التصحيح.

إذا كنت تتساءل عن ماهية التسجيل (Logging) وأهميته، فنوصي بالاطلاع على المفاهيم الأساسية للتسجيل في بايثون، والتي تغطي عادةً:

• ما هو التسجيل (Logging)؟
• لماذا يُعد التسجيل مهمًا؟
• تطبيقات التسجيل في مختلف الصناعات التقنية.

مقدمة إلى Logzero: تبسيط عملية التسجيل في بايثون

تتميز مكتبة Logzero بالعديد من الخصائص التي تجعلها خيارًا ممتازًا لدمج التسجيل في مشاريع بايثون الخاصة بك. هذه الميزات تساهم في تبسيط عملية التسجيل وتجعلها أكثر كفاءة:

الميزات الرئيسية لمكتبة Logzero

• سهولة التسجيل إلى وحدة التحكم (console) و/أو الملفات.
• توفر كائن مسجل (logger object) قياسيًا من بايثون ومُكوّنًا بالكامل.
• تنسيق جذاب للمخرجات، بما في ذلك ألوان خاصة بالمستوى في وحدة التحكم.
• يعمل مع جميع أنواع ترميزات الأحرف (character encodings) والأحرف الخاصة.
• متوافق مع بايثون 2 وبايثون 3.
• لا يتطلب أي تبعيات إضافية (dependencies) في بايثون.

تثبيت مكتبة Logzero

للبدء في استخدام Logzero، تحتاج أولاً إلى تثبيتها. يمكنك القيام بذلك بطريقتين رئيسيتين:

التثبيت عبر pip

لتثبيت Logzero باستخدام مدير الحزم pip، قم بتشغيل الأمر التالي في سطر الأوامر:

pip install -U logzero

التثبيت من مستودع GitHub

يمكنك أيضًا تثبيت Logzero مباشرةً من مستودعها العام على GitHub:

git clone https://github.com/metachris/logzero.git
cd logzero
python setup.py install

أمثلة عملية على التسجيل الأساسي

سنبدأ بمثال بسيط يوضح كيفية استخدام Logzero لتسجيل الرسائل بمستويات مختلفة. في ملف بايثون الخاص بك، سنقوم باستيراد كائن logger من مكتبة Logzero وتجربة أربعة مستويات مختلفة من التسجيل:

مستويات التسجيل المختلفة

#import logger from logzero
from logzero import logger

logger.debug("hello")
logger.info("info")
logger.warning("warning")
logger.error("error")

المخرجات ستكون ملونة، مما يسهل قراءتها وتمييز مستويات التسجيل المختلفة بصريًا.

كما ترى، كل مستوى تسجيل له لونه الخاص، مما يعني أنه يمكنك تحديد مستوى الرسالة بسهولة بمجرد النظر إلى اللون.

كتابة سجلات Logging إلى ملف

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

تكوين ملف السجل الأساسي

سنقوم باستيراد logger و logfile من Logzero. ستساعدنا دالة logfile() في تكوين ملف السجل لحفظ إدخالاتنا. الآن، سيتم تسجيل إدخالاتك في الملف المسمى my_logfile.log.

#import logger and logfile from logzero
from logzero import logger, logfile

#set logfile path
logfile('my_logfile.log')

# Log messages
logger.info("This log message saved in the log file")

يحتوي الإخراج في ملف my_logfile.log على تسمية مستوى التسجيل (على سبيل المثال، “I” لمستوى info)، والتاريخ، والوقت، واسم ملف بايثون، ورقم السطر، والرسالة نفسها.

[I 200409 23:49:59 demo:8] This log message saved in the log file

تدوير ملفات السجل (Rotating Log Files)

ليس من الضروري أن يكون لديك ملف سجل واحد يحفظ جميع إدخالات التسجيل. قد يؤدي ذلك إلى ملف سجل ضخم يصعب على النظام فتحه وإغلاقه. لتجنب هذه المشكلة، يمكنك استخدام المعاملين maxBytes و backupCount للسماح للملف بالتدوير عند الوصول إلى حجم محدد مسبقًا.

عندما يقترب حجم الملف من التجاوز، يتم إغلاق الملف الحالي ويتم فتح ملف جديد بصمت للإخراج. يحدث التدوير كلما اقترب ملف السجل الحالي من طول maxBytes. إذا كان أحد المعاملين maxBytes أو backupCount يساوي صفرًا، فلن يحدث التدوير أبدًا.

في المثال أدناه، قمنا بتعيين maxBytes ليكون 1000000 بايت (1 ميجابايت). هذا يعني أنه عندما يتجاوز الحجم 1 ميجابايت، يتم إغلاق الملف وفتح ملف جديد لحفظ إدخالات السجل. عدد النسخ الاحتياطية المراد الاحتفاظ بها تم تعيينه على 3.

# Set a rotating logfile
import logzero
logzero.logfile("my_logfile.log", maxBytes=1000000, backupCount=3)

تحديد الحد الأدنى لمستوى التسجيل

يشير مستوى التسجيل إلى تحديد مستوى الأهمية لرسالة سجل معينة. يمكنك أيضًا تعيين مستوى سجل مختلف لمعالج الملف (file handler) باستخدام وسيطة loglevel في دالة logfile().

في المثال أدناه، قمنا بتعيين loglevel ليكون logging.WARNING. هذا يعني أن جميع إدخالات السجل التي تقل عن مستوى التحذير (warning level) لن يتم حفظها في ملف السجل.

#import logzero package
from logzero import logger, logfile
import logging

# You can also set a different loglevel for the file handler
logfile("my_logfile.log", loglevel=logging.WARNING)

# Log messages
logger.info("This log message saved in the log file")
logger.warning("This log message saved in the log file")

تخصيص تنسيق السجل (Custom Formatter)

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

يوضح المثال أدناه كيف يمكنك تكوين تنسيق سجلاتك:

#import logzero package
import logzero
from logzero import logger, logfile
import logging

#set file path
logfile("my_logfile.log")

# Set a custom formatter
my_formatter = logging.Formatter('%(filename)s - %(asctime)s - %(levelname)s: %(message)s');
logzero.formatter(my_formatter)

# Log messages
logger.info("This log message saved in the log file")
logger.warning("This log message saved in the log file")

في المثال أعلاه، قمنا بتكوين تنسيق السجل عن طريق تضمين اسم الملف (filename)، والتاريخ والوقت (asctime)، واسم مستوى التسجيل (levelname)، والرسالة (message). هذا هو الإخراج في ملف my_logfile.log:

demo.py - 2020 – 04 – 10 00 : 51 : 44 , 706 - INFO: This log message saved in the log file
demo.py - 2020 – 04 – 10 00 : 51 : 44 , 707 - WARNING: This log message saved in the log file

إنشاء نُسخ مخصصة من المسجل (Custom Logger Instances)

بدلاً من استخدام المسجل الافتراضي، يمكنك أيضًا إعداد نُسخ مسجل محددة باستخدام الدالة logzero.setup_logger(). تتيح لك هذه الدالة تكوين وإرجاع نسخة مسجل مُكوّنة بالكامل مع معلمات مختلفة مثل الاسم (name)، واسم ملف السجل (logfile)، والمُنسّق (formatter)، والحد الأقصى للبايتات (maxBytes)، وعدد النسخ الاحتياطية (backupCount)، ومستوى التسجيل (level).

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

#import logzero package
from logzero import logger, logfile, setup_logger
import logging

# Set a custom formatter
my_formatter = logging.Formatter('%(filename)s - %(asctime)s - %(levelname)s: %(message)s');

#create custom logger instance
custom_logger = setup_logger(
    name="My Custom Logger",
    logfile="my_logfile.log",
    formatter=my_formatter,
    maxBytes=1000000,
    backupCount=3,
    level=logging.INFO
)

# Log messages
custom_logger.info("This log message saved in the log file")
custom_logger.warning("This log message saved in the log file")

في المثال أعلاه، قمنا بإعداد نسخة مسجل مخصصة تسمى custom_logger بقيم معلمات مختلفة ومُكوّنة خصيصًا لتلبية احتياجاتنا.

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

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

يمكنك استكشاف المزيد من الميزات المتوفرة في توثيق Logzero الرسمي. الآن، يمكنك البدء في تطبيق مكتبة Logzero في مشروعك القادم في بايثون.