التسجيل في Python: كيفية استخدام السجلات Debugging في مشاريع Django

ما هو Logging ولماذا يعد مهماً في Django؟

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

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

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

كيف يعمل Logging في Django؟

يوفر Django دعماً مدمجاً لنظام Logging بالاعتماد على مكتبة logging المضمنة في Python. وهذا يعني أنك لا تحتاج إلى بناء النظام من الصفر، لأن الإطار يتكفل بجزء كبير من البنية الأساسية.

يعتمد نظام Logging في Django على أربعة مكونات رئيسية:

• Loggers
• Handlers
• Filters
• Formatters

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

1) Loggers

تُعد Loggers نقطة الدخول الرئيسية إلى نظام السجلات. وهي الجزء الذي يتعامل معه المطور مباشرة عند إرسال الرسائل أو الأحداث للتسجيل.

عندما يستقبل Logger رسالة جديدة، فإنه يقارن مستوى الرسالة log level بالمستوى المحدد له. فإذا كان المستوى مساويًا أو أعلى، يتم تمرير الرسالة إلى Handler لمعالجتها.

أشهر مستويات السجلات هي:

• DEBUG: معلومات تفصيلية منخفضة المستوى تساعد أثناء التطوير.
• INFO: معلومات عامة عن سير النظام.
• WARNING: تنبيهات عن مشكلات بسيطة أو سلوك غير معتاد.
• ERROR: أخطاء مؤثرة تحتاج إلى انتباه.
• CRITICAL: أخطاء حرجة قد تعطل جزءاً مهماً من النظام.

2) Handlers

تحدد Handlers ما الذي سيحدث لكل رسالة يلتقطها Logger. بمعنى آخر، هي المسؤولة عن الوجهة النهائية للسجل.

فعلى سبيل المثال، يمكنك إعداد النظام بحيث:

• يتم حفظ رسائل INFO داخل ملف نصي.
• يتم إرسال رسائل ERROR أو CRITICAL إلى البريد الإلكتروني الخاص بالمطور.
• تظهر بعض الرسائل مباشرة في الطرفية أو شاشة التشغيل.

بالتالي، فإن Handler يخبر النظام أين يكتب الرسالة: داخل ملف، على الشاشة، أو حتى عبر الشبكة.

3) Filters

تُستخدم Filters لتصفية السجلات قبل معالجتها. وهي مفيدة عندما تريد قبول رسائل معينة فقط ورفض غيرها وفق شروط محددة.

على سبيل المثال، يمكنك إنشاء فلتر يسمح فقط بتمرير الرسائل CRITICAL القادمة من مصدر معين داخل التطبيق.

4) Formatters

كما يشير الاسم، فإن Formatters تتحكم في طريقة عرض نص السجل. من خلالها يمكنك تحديد شكل الرسالة، مثل تضمين:

• وقت الحدث
• اسم الملف أو الوحدة
• مستوى السجل
• نص الرسالة نفسه

وهذا مهم جداً عندما ترغب في قراءة السجلات بسرعة أو تحليلها لاحقاً بشكل منظم.

إعداد مشروع Django لتجربة Logging عملياً

سننتقل الآن إلى مثال تطبيقي يوضح كيفية تفعيل Logging داخل مشروع Django. يفترض هذا الشرح أنك تمتلك معرفة أساسية ببنية مشاريع Django وكيفية تشغيلها.

إنشاء البيئة الافتراضية والمشروع

ابدأ بإنشاء مجلد المشروع، ثم أنشئ بيئة افتراضية باسم venv وقم بتفعيلها:

mkdir django-logging-tutorial
virtualenv venv
source venv/bin/activate

بعد ذلك، أنشئ مشروع Django جديداً باسم django_logging_tutorial. لاحظ الفرق بين اسم المجلد الذي يحتوي على الشرطة – واسم المشروع الذي يحتوي على الشرطة السفلية _.

كيفية إعداد ملفات السجلات في settings.py

الخطوة الأهم هي ضبط إعدادات LOGGING داخل ملف settings.py. في المثال التالي سنقوم بحفظ رسائل WARNING داخل ملف باسم warning.log.

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'file': {
            'level': 'WARNING',
            'class': 'logging.FileHandler',
            'filename': BASE_DIR / 'warning.log',
        },
    },
    'loggers': {
        '': {
            'handlers': ['file'],
            'level': 'WARNING',
            'propagate': True,
        },
    },
}

شرح إعدادات Logging السابقة

• version: يحدد إصدار مخطط إعدادات Logging.
• disable_existing_loggers: عند تعيينه إلى False، فإنك تبقي على Loggers المدمجة التي يستخدمها Django داخلياً.
• handlers: هنا نعرف طريقة معالجة السجلات، وقد استخدمنا logging.FileHandler لكتابة الرسائل داخل ملف.
• filename: يحدد اسم ومكان ملف السجل، وفي هذا المثال هو warning.log.
• loggers: يحدد الـ Loggers التي ستتعامل مع الرسائل. استخدام المفتاح الفارغ ” يعني تطبيق الإعداد بشكل عام.
• level: يحدد الحد الأدنى للمستوى الذي سيتم تسجيله، وهنا اخترنا WARNING.
• propagate: يسمح بتمرير السجلات من Logger فرعي إلى Logger أب إذا كان ذلك مطلوباً.

ماذا يعني propagate في Django Logging؟

عند ضبط propagate على القيمة True، فإن السجلات التي تصدر من Loggers فرعية يمكن أن تنتقل إلى Logger أعلى في التسلسل الهرمي. هذا يفيد عندما يكون لديك Handler عام في الجذر وتريد أن ترثه بقية الأجزاء داخل التطبيق.

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

كيفية إنشاء رسائل Log داخل Django

بعد تهيئة الإعدادات، نحتاج إلى توليد رسالة فعلية حتى نختبر ما إذا كان النظام يعمل كما ينبغي. سننشئ صفحة رئيسية بسيطة تعرض رسالة للمستخدم، وفي كل مرة تتم زيارة الصفحة سنسجل رسالة WARNING داخل ملف warning.log.

اذهب إلى التطبيق logging_example ثم أضف الكود التالي إلى ملف views.py. وتأكد أيضاً من إضافة logging_example إلى INSTALLED_APPS داخل settings.py.

from django.http import HttpResponse
import datetime
import logging

logger = logging.getLogger(__name__)

def hello_reader(request):
    logger.warning('Homepage was accessed at ' + str(datetime.datetime.now()) + ' hours!')
    return HttpResponse("Hello FreeCodeCamp.org Reader :)")

في هذا المثال:

• قمنا باستيراد مكتبة logging.
• أنشأنا كائناً من Logger عبر logging.getLogger(__name__).
• عند كل زيارة للدالة hello_reader يتم تسجيل وقت الوصول إلى الصفحة الرئيسية.

ربط الـ View داخل ملف urls.py

لكي يتم استدعاء الدالة السابقة عند زيارة الصفحة الرئيسية، أضف التوجيه التالي داخل ملف urls.py الخاص بالمشروع:

from django.contrib import admin
from django.urls import path
from logging_example import views

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', views.hello_reader, name='hello_reader')
]

الآن، عندما يزور المستخدم الصفحة الرئيسية، سيتم تنفيذ الدالة hello_reader وتسجيل الرسالة في ملف السجلات.

اختبار Logging في Django خطوة بخطوة

بعد الانتهاء من الإعداد، شغّل خادم التطوير باستخدام الأمر التالي:

python manage.py runserver

ثم افتح الصفحة الرئيسية على العنوان:

127.0.0.1:8000

ستظهر لك الرسالة التي قمنا ببرمجتها، وبعد ذلك يمكنك التوجه إلى ملف warning.log لمعاينة السجلات الناتجة.

مثال على المخرجات المتوقعة داخل الملف:

Homepage was accessed at 2021-08-29 22:38:29.922510 hours!
Homepage was accessed at 2021-08-29 22:48:35.088296 hours!

أفضل الممارسات عند استخدام Logging في مشاريع Django

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

• استخدم مستويات السجلات بدقة، ولا تسجل كل شيء على أنه ERROR أو CRITICAL.
• تجنب تسجيل بيانات حساسة مثل كلمات المرور أو الرموز السرية.
• أنشئ رسائل واضحة ومفهومة تساعدك لاحقاً في التشخيص.
• خصص Loggers مختلفة لوحدات المشروع الكبيرة مثل django.request و django.db.backends عند الحاجة.
• فكر في استخدام البريد الإلكتروني أو خدمات مراقبة خارجية للأخطاء الحرجة في بيئات الإنتاج.

لماذا يفيد Logging في تحسين جودة التطبيق؟

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

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

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

يُعد Logging في Python وDjango من أهم الأدوات العملية في Debugging ومراقبة سلوك التطبيقات. ومن خلال إعداد بسيط داخل settings.py، يمكنك تسجيل الأحداث المهمة، تتبع الأخطاء، واختصار وقت التشخيص بشكل ملحوظ. إذا كنت تبني مشروع Django جاداً، فلا تتعامل مع السجلات كميزة إضافية، بل كجزء أساسي من البنية التقنية التي تحافظ على استقرار التطبيق وسهولة صيانته.