Doc/library/syslog.rst

:mod:`syslog` --- Unix syslog library routines
==============================================

.. module:: syslog
   :platform: Unix
   :synopsis: An interface to the Unix syslog library routines.


This module provides an interface to the Unix ``syslog`` library routines.
Refer to the Unix manual pages for a detailed description of the ``syslog``
facility.

This module wraps the system ``syslog`` module.  A pure Python
library that can speak to a syslog server is available in
the :mod:`logging.handlers` module as :class:`SysLogHandler`.

The module defines the following functions:


.. function:: syslog([priority,] message)

   Send the string *message* to the system logger.  A trailing newline is
   added if necessary.  Each message is tagged with a priority composed
   of a *facility* and a *level*.  The optional *priority* argument, which
   defaults to :const:`LOG_INFO`, determines the message priority.  If the
   facility is not encoded in *priority* using logical-or (``LOG_INFO |
   LOG_USER``), the value given in the :func:`openlog` call is used.

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


.. function:: openlog([ident[, logopt[, facility]]])

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

   The optional *ident* keyword argument is a string which is prepended
   to every message, and defaults to ''sys.argv[0]'' with leading
   path components stripped.  The optional *logopt* keyword argument
   (default=0) is a bit field - see below for possible values to combine.
   The optional *facility* keyword argument (default=:const:`LOG_USER`)
   sets the default facility for messages which do not have a facility
   explicitly encoded.

   .. versionchanged::3.2
      In previous versions, keyword arguments were not allowed, and *ident*
      was required.  The default for *ident* was dependent on the system
      libraries, and often was ''python'' instead of the name of the
      python program file.


.. function:: closelog()

   Reset the syslog module values and call the system library
   ''closelog()''.

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


.. function:: setlogmask(maskpri)

   Set the priority mask to *maskpri* and return the previous mask value.
   Calls to :func:`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*.

The module defines the following constants:

Priority levels (high to low):
   :const:`LOG_EMERG`, :const:`LOG_ALERT`, :const:`LOG_CRIT`, :const:`LOG_ERR`,
   :const:`LOG_WARNING`, :const:`LOG_NOTICE`, :const:`LOG_INFO`,
   :const:`LOG_DEBUG`.

Facilities:
   :const:`LOG_KERN`, :const:`LOG_USER`, :const:`LOG_MAIL`, :const:`LOG_DAEMON`,
   :const:`LOG_AUTH`, :const:`LOG_LPR`, :const:`LOG_NEWS`, :const:`LOG_UUCP`,
   :const:`LOG_CRON` and :const:`LOG_LOCAL0` to :const:`LOG_LOCAL7`.

Log options:
   :const:`LOG_PID`, :const:`LOG_CONS`, :const:`LOG_NDELAY`, :const:`LOG_NOWAIT`
   and :const:`LOG_PERROR` if defined in ``<syslog.h>``.


Examples
--------

Simple example
~~~~~~~~~~~~~~

A simple set of examples::

   import syslog

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

An example of setting some log options, these would include the process ID
in logged messages, and write the messages to the destination facility
used for mail logging::

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