syslog --- روال‌های کتابخانه‌ای syslog یونیکس

این ماژول رابطی به روتین‌های کتابخانه syslog در Unix فراهم می‌کند. برای شرحی دقیق از امکانات syslog به صفحات راهنمای Unix مراجعه کنید.

دسترس‌پذیری: Unix, not WASI, not iOS.

این ماژول، خانواده‌ای از روال‌های سیستمی syslog را پوشش می‌دهد. یک کتابخانه‌ی پایتون خالص که می‌تواند با یک سرور syslog ارتباط برقرار کند، در ماژول logging.handlers به‌عنوان SysLogHandler در دسترس است.

این ماژول توابع زیر را تعریف می‌کند:

syslog.syslog(message)
syslog.syslog(priority, message)

رشته‌ی message را به گزارش‌گیر سیستم ارسال کنید. در صورت لزوم، یک خط جدید به انتها اضافه می‌شود. هر پیام با اولویتی متشکل از امکانات (facility) و سطح (level) برچسب‌گذاری می‌شود. آرگومان اختیاری priority، که پیش‌فرض آن LOG_INFO است، اولویت پیام را تعیین می‌کند. اگر امکانات با استفاده از یا منطقی (LOG_INFO | LOG_USER) در priority کدگذاری نشده باشد، از مقدار داده‌شده در فراخوانی openlog() استفاده می‌شود.

اگر openlog() پیش از فراخوانی syslog() فراخوانی نشده باشد، openlog() بدون آرگومان فراخوانی خواهد شد.

یک رویداد حسابرسی syslog.syslog را با آرگومان‌های priority و message پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.2: در نسخه‌های پیشین، اگر openlog() پیش از فراخوانی syslog() فراخوانی نشده بود، به‌صورت خودکار فراخوانی نمی‌شد و فراخوانی openlog() به پیاده‌سازی syslog واگذار می‌شد.

تغییر یافته در نسخه‌ی 3.12: این تابع در زیرمفسرها محدود است. (تنها کدی که در چندین مفسر اجرا می‌شود تحت تأثیر قرار می‌گیرد و این محدودیت برای بیشتر کاربران مرتبط نیست.) openlog() باید در مفسر اصلی فراخوانی شود، پیش از آنکه بتوان از syslog() در یک زیرمفسر استفاده کرد. در غیر این صورت، RuntimeError پرتاب خواهد شد.

syslog.openlog([ident[, logoption[, facility]]])

گزینه‌های گزارش‌گیری برای فراخوانی‌های بعدی syslog() را می‌توان با فراخوانی openlog() تنظیم کرد. اگر گزارش در حال حاضر باز نباشد، syslog()، openlog() را بدون آرگومان فراخوانی می‌کند.

آرگومان کلیدواژه‌ای اختیاری ident رشته‌ای است که به ابتدای هر پیام اضافه می‌شود و مقدار پیش‌فرض آن sys.argv[0] است، با حذف اجزای ابتدایی مسیر. آرگومان کلیدواژه‌ای اختیاری logoption (مقدار پیش‌فرض آن ۰ است) یک فیلد بیتی است — برای مشاهده‌ی مقادیر قابل ترکیب، به بخش زیر مراجعه کنید. آرگومان کلیدواژه‌ای اختیاری facility (مقدار پیش‌فرض آن LOG_USER است) مقدار پیش‌فرض facility را برای پیام‌هایی که facility آن‌ها به‌طور صریح کدگذاری نشده است، تعیین می‌کند.

یک رویداد حسابرسی syslog.openlog را با آرگومان‌های ident، logoption و facility پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.2: در نسخه‌های پیشین، آرگومان‌های کلیدواژه‌ای مجاز نبودند و ident الزامی بود.

تغییر یافته در نسخه‌ی 3.12: این تابع در زیرمفسرها محدود شده است. (فقط کدی که در چندین مفسر اجرا می‌شود، تحت تأثیر قرار می‌گیرد و این محدودیت برای بیشتر کاربران مرتبط نیست.) این تابع فقط می‌تواند در مفسر اصلی فراخوانی شود. اگر در یک زیرمفسر فراخوانی شود، RuntimeError را پرتاب می‌کند.

syslog.closelog()

مقادیر ماژول syslog را بازنشانی می‌کند و closelog() کتابخانه‌ی سیستم را فراخوانی می‌کند.

این باعث می‌شود ماژول همان رفتاری را داشته باشد که هنگام ایمپورت اولیه دارد. برای مثال، openlog() در اولین فراخوانی syslog() فراخوانی خواهد شد (اگر openlog() از قبل فراخوانی نشده باشد)، و ident و سایر پارامترهای openlog() به مقادیر پیش‌فرض بازنشانی می‌شوند.

یک رویداد حسابرسی syslog.closelog را بدون آرگومان پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.12: این تابع در زیرمفسرها محدود شده است. (فقط کدی که در چندین مفسر اجرا می‌شود، تحت تأثیر قرار می‌گیرد و این محدودیت برای بیشتر کاربران مرتبط نیست.) این تابع فقط می‌تواند در مفسر اصلی فراخوانی شود. اگر در یک زیرمفسر فراخوانی شود، RuntimeError را پرتاب می‌کند.

syslog.setlogmask(maskpri)

نقاب اولویت را روی maskpri تنظیم می‌کند و مقدار نقاب پیشین را برمی‌گرداند. فراخوانی‌های syslog() با سطح اولویتی که در maskpri تنظیم نشده باشد نادیده گرفته می‌شوند. پیش‌فرض این است که همه اولویت‌ها ثبت شوند. تابع LOG_MASK(pri) نقاب اولویت منفرد pri را محاسبه می‌کند. تابع LOG_UPTO(pri) نقاب همه اولویت‌ها تا pri و شامل خود آن را محاسبه می‌کند.

یک رویداد حسابرسی syslog.setlogmask را با آرگومان maskpri پرتاب می‌کند.

این ماژول ثابت‌های زیر را تعریف می‌کند:

syslog.LOG_EMERG
syslog.LOG_ALERT
syslog.LOG_CRIT
syslog.LOG_ERR
syslog.LOG_WARNING
syslog.LOG_NOTICE
syslog.LOG_INFO
syslog.LOG_DEBUG

سطوح اولویت (از بالا به پایین).

syslog.LOG_AUTH
syslog.LOG_AUTHPRIV
syslog.LOG_CRON
syslog.LOG_DAEMON
syslog.LOG_FTP
syslog.LOG_INSTALL
syslog.LOG_KERN
syslog.LOG_LAUNCHD
syslog.LOG_LPR
syslog.LOG_MAIL
syslog.LOG_NETINFO
syslog.LOG_NEWS
syslog.LOG_RAS
syslog.LOG_REMOTEAUTH
syslog.LOG_SYSLOG
syslog.LOG_USER
syslog.LOG_UUCP
syslog.LOG_LOCAL0
syslog.LOG_LOCAL1
syslog.LOG_LOCAL2
syslog.LOG_LOCAL3
syslog.LOG_LOCAL4
syslog.LOG_LOCAL5
syslog.LOG_LOCAL6
syslog.LOG_LOCAL7

امکانات، بسته به دسترسی‌پذیری در <syslog.h> برای LOG_AUTHPRIV، LOG_FTP، LOG_NETINFO، LOG_REMOTEAUTH، LOG_INSTALL و LOG_RAS.

تغییر یافته در نسخه‌ی 3.13: LOG_FTP، LOG_NETINFO، LOG_REMOTEAUTH، LOG_INSTALL، LOG_RAS و LOG_LAUNCHD افزوده شدند.

syslog.LOG_PID
syslog.LOG_CONS
syslog.LOG_NDELAY
syslog.LOG_ODELAY
syslog.LOG_NOWAIT
syslog.LOG_PERROR

گزینه‌های گزارش، بسته به دسترسی‌پذیری در <syslog.h> برای LOG_ODELAY، LOG_NOWAIT و LOG_PERROR.

مثال‌ها

مثال ساده

مجموعه‌ای ساده از مثال‌ها:

import syslog

syslog.syslog('Processing started')
if error:
    syslog.syslog(syslog.LOG_ERR, 'Processing started')

نمونه‌ای از تنظیم چند گزینه‌ی گزارش؛ این گزینه‌ها شناسه‌ی فرایند را در پیام‌های گزارش‌شده درج می‌کنند و پیام‌ها را به دسته‌ی گزارش مقصد مورد استفاده برای گزارش ایمیل می‌نویسند:

syslog.openlog(logoption=syslog.LOG_PID, facility=syslog.LOG_MAIL)
syslog.syslog('E-mail processing initiated...')