Logging در Django: راهنمای کامل لاگ‌گیری، ساختار، امنیت و پیکربندی

مقدمه

بسیاری از برنامه‌نویسان پایتون برای دیباگ سریع از print() استفاده می‌کنند، اما سیستم logging بسیار قدرتمندتر، ساخت‌یافته‌تر و قابل‌کنترل‌تر است. Django سیستم logging پایتون را گسترش می‌دهد تا اطلاعات دقیق‌تری دربارهٔ وضعیت و سلامت برنامه ارائه دهد.

مروری بر Logging در Django

Django از ماژول داخلی logging پایتون استفاده می‌کند. یک پیکربندی logging از چهار بخش تشکیل می‌شود:

• Loggers
• Handlers
• Filters
• Formatters

Loggers

Logger نقطهٔ ورود به سیستم logging است. هر logger یک نام دارد و پیام‌ها را دریافت می‌کند.

سطوح لاگ (Log Levels)

• DEBUG: اطلاعات سطح پایین برای دیباگ
• INFO: اطلاعات عمومی سیستم
• WARNING: هشدار دربارهٔ مشکل کوچک
• ERROR: خطای مهم
• CRITICAL: خطای بحرانی

هر پیام یک Log Record است و سطح خودش را دارد. اگر سطح پیام ≥ سطح logger باشد، پردازش می‌شود؛ در غیر این صورت نادیده گرفته می‌شود.

پس از تأیید سطح، پیام به Handler ارسال می‌شود.

Handlers

Handler تعیین می‌کند پیام کجا و چگونه ذخیره یا نمایش داده شود:

• نوشتن در فایل
• نمایش در کنسول
• ارسال به شبکه
• ارسال ایمیل

Handler نیز سطح لاگ دارد. اگر سطح پیام کمتر از سطح handler باشد، پیام نادیده گرفته می‌شود.

یک logger می‌تواند چند handler داشته باشد. مثلاً:

• ERROR و CRITICAL → ارسال به سرویس هشدار
• تمام پیام‌ها → ذخیره در فایل

Filters

Filter کنترل بیشتری روی پیام‌ها فراهم می‌کند. کاربردها:

• فقط اجازهٔ عبور پیام‌های ERROR از یک ماژول خاص
• تغییر سطح پیام‌ها (مثلاً تبدیل ERROR به WARNING)

Filter می‌تواند روی logger یا handler نصب شود و چندین filter می‌توانند زنجیره شوند.

Formatters

Formatter تعیین می‌کند پیام نهایی چگونه نمایش داده شود. معمولاً یک رشتهٔ قالب‌بندی پایتون است که شامل ویژگی‌های LogRecord می‌شود:

• زمان
• سطح پیام
• نام logger
• متن پیام

می‌توان Formatter سفارشی نیز نوشت.

پیامدهای امنیتی

لاگ‌ها ممکن است شامل اطلاعات حساس باشند:

• درخواست‌های وب
• Stack trace
• مقادیر متغیرهای محلی
• تنظیمات Django

بنابراین باید بدانید:

• چه اطلاعاتی جمع‌آوری می‌شود
• کجا ذخیره می‌شود
• چه کسانی به آن دسترسی دارند

Django امکان فیلتر کردن اطلاعات حساس را فراهم می‌کند.

AdminEmailHandler

این handler هنگام وقوع خطاهای مهم، ایمیل‌هایی به مدیران سایت ارسال می‌کند. اگر include_html فعال باشد، ایمیل شامل:

• traceback کامل
• مقادیر متغیرهای محلی
• تنظیمات Django

ارسال چنین اطلاعات حساسی از طریق ایمیل معمولاً توصیه نمی‌شود. بهتر است از سرویس‌های شخص ثالث مدیریت خطا استفاده کنید.

پیکربندی Logging

Django از فرمت dictConfig برای پیکربندی logging استفاده می‌کند. پیکربندی در تنظیمات LOGGING انجام می‌شود.

این تنظیمات شامل:

• loggers
• handlers
• filters
• formatters

اگر disable_existing_loggers=True باشد، تمام loggerهای پیش‌فرض غیرفعال می‌شوند. این معمولاً رفتار مطلوبی نیست.

Logging هنگام اجرای django.setup() پیکربندی می‌شود، بنابراین همیشه آمادهٔ استفاده است.

جمع‌بندی

سیستم logging در Django ابزاری قدرتمند برای نظارت، دیباگ و مدیریت خطاهاست. با شناخت Loggers، Handlers، Filters و Formatters می‌توانید ساختار لاگ‌گیری حرفه‌ای و امنی برای پروژهٔ خود ایجاد کنید. همچنین با پیکربندی صحیح LOGGING می‌توانید کنترل کاملی بر نحوهٔ ثبت و مدیریت پیام‌ها داشته باشید.

مقدمه

Django از سیستم logging پایتون و فرمت dictConfig برای پیکربندی لاگ‌ها استفاده می‌کند. در این مقاله چند نمونهٔ واقعی از پیکربندی لاگ‌گیری را بررسی می‌کنیم تا ببینید چگونه می‌توان رفتار لاگ‌گیری را مطابق نیازهای پروژه تنظیم کرد.

۱. پیکربندی ساده: نمایش لاگ‌ها در کنسول

این پیکربندی تمام پیام‌های سطح WARNING و بالاتر را در کنسول نمایش می‌دهد.

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
        },
    },
    "root": {
        "handlers": ["console"],
        "level": "WARNING",
    },
}

با تغییر سطح به INFO یا DEBUG می‌توانید پیام‌های بیشتری ببینید.

۲. لاگ‌گیری دقیق‌تر: فقط پیام‌های Django

این پیکربندی پیام‌های logger با نام django را در کنسول نمایش می‌دهد.

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
        },
    },
    "root": {
        "handlers": ["console"],
        "level": "WARNING",
    },
    "loggers": {
        "django": {
            "handlers": ["console"],
            "level": os.getenv("DJANGO_LOG_LEVEL", "INFO"),
            "propagate": False,
        },
    },
}

با تنظیم DJANGO_LOG_LEVEL=DEBUG می‌توانید تمام لاگ‌های دیباگ Django را ببینید.

۳. ذخیرهٔ لاگ‌ها در فایل

این پیکربندی پیام‌های Django را در یک فایل ذخیره می‌کند.

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {
        "file": {
            "level": "DEBUG",
            "class": "logging.FileHandler",
            "filename": "/path/to/django/debug.log",
        },
    },
    "loggers": {
        "django": {
            "handlers": ["file"],
            "level": "DEBUG",
            "propagate": True,
        },
    },
}

حتماً مسیر فایل را به مکانی قابل‌نوشتن تغییر دهید.

۴. پیکربندی پیشرفته: فیلترها، فرمت‌ها و چندین handler

این مثال یک پیکربندی پیچیده‌تر را نشان می‌دهد.

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "verbose": {
            "format": "{levelname} {asctime} {module} {process:d} {thread:d} {message}",
            "style": "{",
        },
        "simple": {
            "format": "{levelname} {message}",
            "style": "{",
        },
    },
    "filters": {
        "special": {
            "()": "project.logging.SpecialFilter",
            "foo": "bar",
        },
        "require_debug_true": {
            "()": "django.utils.log.RequireDebugTrue",
        },
    },
    "handlers": {
        "console": {
            "level": "INFO",
            "filters": ["require_debug_true"],
            "class": "logging.StreamHandler",
            "formatter": "simple",
        },
        "mail_admins": {
            "level": "ERROR",
            "class": "django.utils.log.AdminEmailHandler",
            "filters": ["special"],
        },
    },
    "loggers": {
        "django": {
            "handlers": ["console"],
            "propagate": True,
        },
        "django.request": {
            "handlers": ["mail_admins"],
            "level": "ERROR",
            "propagate": False,
        },
        "myproject.custom": {
            "handlers": ["console", "mail_admins"],
            "level": "INFO",
            "filters": ["special"],
        },
    },
}

این پیکربندی چه می‌کند؟

• دو formatter:
  • simple: فقط سطح و پیام
  • verbose: سطح، زمان، ماژول، پردازش، thread و پیام
• دو filter:
  • special: فیلتر سفارشی با پارامتر
  • require_debug_true: فقط هنگام DEBUG=True
• دو handler:
  • console: نمایش پیام‌های INFO+
  • mail_admins: ارسال پیام‌های ERROR+ به مدیران
• سه logger:
  • django: ارسال پیام‌ها به کنسول
  • django.request: ارسال خطاها به ایمیل مدیران
  • myproject.custom: ارسال INFO+ به کنسول و ERROR+ به ایمیل

پیکربندی سفارشی Logging

اگر نمی‌خواهید از dictConfig استفاده کنید، می‌توانید سیستم لاگ‌گیری را کاملاً سفارشی کنید.

تنظیم LOGGING_CONFIG مشخص می‌کند Django از چه تابعی برای پیکربندی لاگ‌ها استفاده کند.

LOGGING_CONFIG = "myproject.logging.configure"

غیرفعال‌سازی کامل پیکربندی Logging

برای غیرفعال کردن پیکربندی خودکار Django:

LOGGING_CONFIG = None

import logging.config
logging.config.dictConfig(...)

توجه: پیکربندی دستی باید بعد از تنظیماتی که به آن وابسته است قرار گیرد.

جمع‌بندی

Django یک سیستم logging بسیار انعطاف‌پذیر ارائه می‌دهد که از پیکربندی سادهٔ کنسول تا ساختارهای پیچیده با فیلترها، فرمت‌ها و چندین handler را پشتیبانی می‌کند. با شناخت dictConfig و نحوهٔ کنترل loggers، می‌توانید یک سیستم لاگ‌گیری قدرتمند و مناسب برای توسعه و محیط تولید ایجاد کنید.