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() استفاده می‌شود.

If openlog() has not been called prior to the call to syslog(), openlog() will be called with no arguments.

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

تغییر یافته در نسخه‌ی 3.2: In previous versions, openlog() would not be called automatically if it wasn't called prior to the call to syslog(), deferring to the syslog implementation to call openlog().

تغییر یافته در نسخه‌ی 3.12: This function is restricted in subinterpreters. (Only code that runs in multiple interpreters is affected and the restriction is not relevant for most users.) openlog() must be called in the main interpreter before syslog() may be used in a subinterpreter. Otherwise it will raise RuntimeError.

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

Logging options of subsequent syslog() calls can be set by calling openlog(). syslog() will call openlog() with no arguments if the log is not currently open.

آرگومان کلیدواژه‌ای اختیاری 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() کتابخانه‌ی سیستم را فراخوانی می‌کند.

This causes the module to behave as it does when initially imported. For example, openlog() will be called on the first syslog() call (if openlog() hasn't already been called), and ident and other openlog() parameters are reset to defaults.

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

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

syslog.setlogmask(maskpri)

Set the priority mask to maskpri and return the previous mask value. Calls to syslog() with a priority level not set in maskpri are ignored. The default is to log all priorities. The function LOG_MASK(pri) calculates the mask for the individual priority pri. The function LOG_UPTO(pri) calculates the mask for all priorities up to and including 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...')