آموزش پایتون - ثبت وقایع

ثبت وقایع (Logging) در پایتون

ثبت وقایع (لاگینگ) فرآیند ضبط و ذخیره پیام‌ها در طول اجرای یک برنامه است تا اطلاعات زمان اجرا را ارائه دهد؛ اطلاعاتی که می‌توانند برای مانیتورینگ، اشکال‌زدایی (Debugging) و حسابرسی (Auditing) مفید باشند.

در پایتون، ثبت وقایع از طریق ماژول داخلی logging انجام می‌شود که چارچوبی انعطاف‌پذیر برای تولید پیام‌های گزارش و ثبت وقایع فراهم می‌کند.

مزایای استفاده از ثبت وقایع

در ادامه مزایای استفاده از ثبت وقایع در پایتون آمده است −

• اشکال‌زدایی (Debugging) − به شناسایی و عیب‌یابی مشکلات با ثبت اطلاعات مرتبط در طول اجرای برنامه کمک می‌کند.

• مانیتورینگ (Monitoring) − دیدگاهی درباره رفتار و عملکرد برنامه ارائه می‌دهد.

• حسابرسی (Auditing) − سابقه‌ای از رویدادها و اقدامات مهم را برای اهداف امنیتی نگه می‌دارد.

• عیب‌یابی (Troubleshooting) − پیگیری روند اجرای برنامه و مقادیر متغیرها را برای درک رفتارهای غیرمنتظره تسهیل می‌کند.

مؤلفه‌های ثبت وقایع در پایتون

سیستم ثبت وقایع در پایتون از چند مؤلفه اصلی تشکیل شده است که در کنار هم برای مدیریت و خروجی دادن موثر پیام‌ها کار می‌کنند −

• Logger (ثبت‌کننده) − نقطه ورود اصلی است که شما برای ارسال پیام‌های گزارش از آن استفاده می‌کنید. هر نمونه از Logger نام‌گذاری می‌شود و می‌توان آن را به‌طور مستقل پیکربندی کرد.

• Handler (مدیریت‌کننده خروجی) − مشخص می‌کند که پیام‌های ثبت‌شده به کجا فرستاده شوند. Handlerها پیام‌ها را به مقاصد مختلفی مانند کنسول، فایل‌ها، سوکت‌ها و غیره ارسال می‌کنند.

• Formatter (فرمت‌کننده) − چیدمان و ساختار پیام‌های گزارش را تعیین می‌کند. Formatterها مشخص می‌کنند چه اطلاعاتی در گزارش گنجانده شود (مانند برچسب زمان، سطح اهمیت، متن پیام).

• Logger Level (سطح اهمیت) − میزان اهمیت پیام‌های گزارش را تعریف می‌کند. پیام‌های پایین‌تر از این سطح نادیده گرفته می‌شوند. سطوح رایج شامل DEBUG، INFO، WARNING، ERROR و CRITICAL هستند.

• Filter (فیلتر) − مؤلفه‌های اختیاری هستند که کنترل دقیق‌تری روی اینکه کدام پیام‌ها پردازش و منتشر شوند ارائه می‌دهند.

سطوح ثبت وقایع (Logging Levels)

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

• DEBUG (اشکال‌زدایی) − اطلاعات با جزئیات کامل که معمولاً فقط برای اهداف عیب‌یابی مفید است. این پیام‌ها برای ردیابی روند اجرای برنامه استفاده می‌شوند و معمولاً در محیط‌های واقعی و نهایی دیده نمی‌شوند.

• INFO (اطلاع‌رسانی) − تأیید اینکه بخش‌ها طبق انتظار کار می‌کنند. این پیام‌ها اطلاعات عمومی درباره پیشرفت برنامه ارائه می‌دهند.

• WARNING (هشدار) − نشان‌دهنده مشکلات بالقوه‌ای است که مانع از اجرای برنامه نمی‌شوند اما ممکن است نیاز به توجه داشته باشند. این پیام‌ها می‌توانند برای هشدار درباره شرایط غیرمنتظره استفاده شوند.

• ERROR (خطا) − نشان‌دهنده یک مشکل جدی‌تر است که مانع از تکمیل موفقیت‌آمیز یک تابع یا عملیات خاص می‌شود. این پیام‌ها خطاهایی را برجسته می‌کنند که نیاز به توجه فوری دارند اما لزوماً باعث متوقف شدن کامل برنامه نمی‌شوند.

• CRITICAL (بحرانی) − شدیدترین سطح که نشان‌دهنده یک خطای بحرانی است و ممکن است منجر به متوقف شدن برنامه شود. این پیام‌ها برای خرابی‌های بحرانی که نیاز به مداخله فوری دارند استفاده می‌شوند.

کاربرد

در ادامه سناریوهای کاربردی برای هر سطح از ثبت وقایع در برنامه‌های پایتون آمده است −

انتخاب سطح مناسب − انتخاب سطح مناسب تضمین می‌کند که پیام‌های ثبت‌شده اطلاعات مرتبط را بدون شلوغ کردن گزارش‌ها ارائه می‌دهند.

تنظیم سطوح − ثبت‌کننده‌ها (Loggerها)، مدیریت‌کننده‌ها (Handlerها) و پیام‌های خاص را می‌توان با سطوح مختلف پیکربندی کرد تا کنترل شود کدام پیام‌ها ثبت شوند و در کجا خروجی داده شوند.

سلسله‌مراتب (Hierarchy) − سطوح دارای ساختار سلسله‌مراتبی هستند، به این معنی که تنظیم یک سطح روی یک Logger روی Handlerها و پیام‌های مرتبط با آن نیز تأثیر می‌گذارد.

مثال ساده از ثبت وقایع

در ادامه یک مثال ساده در پایتون برای نشان دادن نحوه استفاده و عملکرد ثبت وقایع آورده شده است −

import logging

# Configure logging
logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(levelname)s - %(message)s')

# Example usage
def calculate_sum(a, b):
   logging.debug(f"Calculating sum of {a} and {b}")
   result = a + b
   logging.info(f"Sum calculated successfully: {result}")
   return result

# Main program
if __name__ == "__main__":
   logging.info("Starting the program")
   result = calculate_sum(10, 20)
   logging.info("Program completed")

خروجی

در ادامه خروجی کد بالا آورده شده است −

2024-06-19 09:00:06,774 - INFO - Starting the program
2024-06-19 09:00:06,774 - DEBUG - Calculating sum of 10 and 20
2024-06-19 09:00:06,774 - INFO - Sum calculated successfully: 30
2024-06-19 09:00:06,775 - INFO - Program completed

پیکربندی ثبت وقایع

پیکربندی ثبت وقایع در پایتون به راه‌اندازی مؤلفه‌های مختلفی مانند Loggerها، Handlerها و Formatterها اشاره دارد تا نحوه و محل ذخیره و نمایش پیام‌ها کنترل شود. این پیکربندی به توسعه‌دهندگان اجازه می‌دهد تا رفتار ثبت گزارش‌ها را بر اساس نیازمندی‌های برنامه و محیط اجرای خود سفارشی‌سازی کنند.

مثال

در مثال زیر، تابع ()getLogger یک Logger نام‌گذاری‌شده را دریافت کرده یا می‌سازد. ثبت‌کننده‌ها بر اساس نامشان به‌صورت سلسله‌مراتبی سازمان‌دهی می‌شوند. سپس، Handlerهایی مانند "StreamHandler" (هندلر کنسول) ایجاد می‌شوند تا مشخص کنند پیام‌ها به کجا بروند. آن‌ها می‌توانند با سطوح و Formatterهای خاص پیکربندی شوند.

فرمت‌کننده‌ها (Formatterها) چیدمان پیام‌های گزارش را مشخص می‌کنند و تعیین می‌کنند پیام‌ها هنگام چاپ یا ذخیره شدن چگونه ظاهر شوند −

import logging

# Create logger
logger = logging.getLogger('my_app')
logger.setLevel(logging.DEBUG)  # Set global log level

# Create console handler and set level to debug
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.DEBUG)

# Create formatter
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
console_handler.setFormatter(formatter)

# Add console handler to logger
logger.addHandler(console_handler)

# Example usage
logger.debug('This is a debug message')
logger.info('This is an info message')
logger.warning('This is a warning message')
logger.error('This is an error message')
logger.critical('This is a critical message')

نتیجه تولید شده به صورت زیر است −

2024-06-19 09:05:20,852 - my_app - DEBUG - This is a debug message
2024-06-19 09:05:20,852 - my_app - INFO - This is an info message
2024-06-19 09:05:20,852 - my_app - WARNING - This is a warning message
2024-06-19 09:05:20,852 - my_app - ERROR - This is an error message
2024-06-19 09:05:20,852 - my_app - CRITICAL - This is a critical message

مدیریت‌کننده‌های ثبت وقایع (Logging Handlers)

مدیریت‌کننده‌های ثبت وقایع (Handlerها) در پایتون مشخص می‌کنند پیام‌های گزارش در کجا و چگونه پردازش و خروجی داده شوند. آن‌ها نقش مهمی در هدایت پیام‌ها به مقاصد خاص مانند کنسول، فایل‌ها، ایمیل، پایگاه‌های داده یا حتی سرورهای از راه دور ایفا می‌کنند.

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

انواع مدیریت‌کننده‌های ثبت وقایع

در ادامه انواع مختلف Handlerها در پایتون آمده است −

• StreamHandler − پیام‌های گزارش را به خروجی‌های استریم مانند sys.stdout یا sys.stderr می‌فرستد. برای نمایش پیام‌ها در کنسول یا محیط خط فرمان مفید است.

• FileHandler − پیام‌های گزارش را در یک فایل مشخص روی حافظه می‌نویسد. برای ثبت دائمی و آرشیو کردن داده‌ها مفید است.

• RotatingFileHandler − مشابه FileHandler است اما فایل‌های گزارش را به‌طور خودکار بر اساس حجم یا فواصل زمانی چرخشی (جایگزین) می‌کند. به مدیریت حجم فایل‌ها و جلوگیری از بزرگ شدن بیش از حد آن‌ها کمک می‌کند.

• SMTPHandler − پیام‌ها را به‌صورت ایمیل از طریق SMTP به دریافت‌کنندگان مشخص‌شده می‌فرستد. برای هشدار دادن به مدیران سیستم یا توسعه‌دهندگان درباره مشکلات بحرانی مفید است.

• SysLogHandler − پیام‌ها را به بخش ثبت وقایع سیستم در سیستم‌عامل‌های شبیه یونیکس (مانند syslog) می‌فرستد. امکان ادغام با امکانات گزارش‌گیری سراسری سیستم را فراهم می‌کند.

• MemoryHandler − پیام‌ها را موقتاً در حافظه بافر می‌کند و پس از رسیدن به حجم بافر مشخص یا زمان معین، آن‌ها را به مقصد اصلی می‌فرستد. برای دسته‌ای کردن و مدیریت حجم بالای ناگهانی پیام‌ها مفید است.

• HTTPHandler − پیام‌های گزارش را از طریق HTTP یا HTTPS به یک وب‌سرور ارسال می‌کند. امکان ثبت پیام‌ها روی یک سرور از راه دور یا سرویس آنلاین را فراهم می‌سازد.