1 :mod:`syslog` --- Unix syslog library routines 2 ============================================== 3 4 .. module:: syslog 5 :platform: Unix 6 :synopsis: An interface to the Unix syslog library routines. 7 8 -------------- 9 10 This module provides an interface to the Unix ``syslog`` library routines. 11 Refer to the Unix manual pages for a detailed description of the ``syslog`` 12 facility. 13 14 This module wraps the system ``syslog`` family of routines. A pure Python 15 library that can speak to a syslog server is available in the 16 :mod:`logging.handlers` module as :class:`SysLogHandler`. 17 18 The module defines the following functions: 19 20 21 .. function:: syslog(message) 22 syslog(priority, message) 23 24 Send the string *message* to the system logger. A trailing newline is added 25 if necessary. Each message is tagged with a priority composed of a 26 *facility* and a *level*. The optional *priority* argument, which defaults 27 to :const:`LOG_INFO`, determines the message priority. If the facility is 28 not encoded in *priority* using logical-or (``LOG_INFO | LOG_USER``), the 29 value given in the :func:`openlog` call is used. 30 31 If :func:`openlog` has not been called prior to the call to :func:`syslog`, 32 ``openlog()`` will be called with no arguments. 33 34 35 .. function:: openlog([ident[, logoption[, facility]]]) 36 37 Logging options of subsequent :func:`syslog` calls can be set by calling 38 :func:`openlog`. :func:`syslog` will call :func:`openlog` with no arguments 39 if the log is not currently open. 40 41 The optional *ident* keyword argument is a string which is prepended to every 42 message, and defaults to ``sys.argv[0]`` with leading path components 43 stripped. The optional *logoption* keyword argument (default is 0) is a bit 44 field -- see below for possible values to combine. The optional *facility* 45 keyword argument (default is :const:`LOG_USER`) sets the default facility for 46 messages which do not have a facility explicitly encoded. 47 48 .. versionchanged:: 3.2 49 In previous versions, keyword arguments were not allowed, and *ident* was 50 required. The default for *ident* was dependent on the system libraries, 51 and often was ``python`` instead of the name of the Python program file. 52 53 54 .. function:: closelog() 55 56 Reset the syslog module values and call the system library ``closelog()``. 57 58 This causes the module to behave as it does when initially imported. For 59 example, :func:`openlog` will be called on the first :func:`syslog` call (if 60 :func:`openlog` hasn't already been called), and *ident* and other 61 :func:`openlog` parameters are reset to defaults. 62 63 64 .. function:: setlogmask(maskpri) 65 66 Set the priority mask to *maskpri* and return the previous mask value. Calls 67 to :func:`syslog` with a priority level not set in *maskpri* are ignored. 68 The default is to log all priorities. The function ``LOG_MASK(pri)`` 69 calculates the mask for the individual priority *pri*. The function 70 ``LOG_UPTO(pri)`` calculates the mask for all priorities up to and including 71 *pri*. 72 73 The module defines the following constants: 74 75 Priority levels (high to low): 76 :const:`LOG_EMERG`, :const:`LOG_ALERT`, :const:`LOG_CRIT`, :const:`LOG_ERR`, 77 :const:`LOG_WARNING`, :const:`LOG_NOTICE`, :const:`LOG_INFO`, 78 :const:`LOG_DEBUG`. 79 80 Facilities: 81 :const:`LOG_KERN`, :const:`LOG_USER`, :const:`LOG_MAIL`, :const:`LOG_DAEMON`, 82 :const:`LOG_AUTH`, :const:`LOG_LPR`, :const:`LOG_NEWS`, :const:`LOG_UUCP`, 83 :const:`LOG_CRON`, :const:`LOG_SYSLOG`, :const:`LOG_LOCAL0` to 84 :const:`LOG_LOCAL7`, and, if defined in ``<syslog.h>``, 85 :const:`LOG_AUTHPRIV`. 86 87 Log options: 88 :const:`LOG_PID`, :const:`LOG_CONS`, :const:`LOG_NDELAY`, and, if defined 89 in ``<syslog.h>``, :const:`LOG_ODELAY`, :const:`LOG_NOWAIT`, and 90 :const:`LOG_PERROR`. 91 92 93 Examples 94 -------- 95 96 Simple example 97 ~~~~~~~~~~~~~~ 98 99 A simple set of examples:: 100 101 import syslog 102 103 syslog.syslog('Processing started') 104 if error: 105 syslog.syslog(syslog.LOG_ERR, 'Processing started') 106 107 An example of setting some log options, these would include the process ID in 108 logged messages, and write the messages to the destination facility used for 109 mail logging:: 110 111 syslog.openlog(logoption=syslog.LOG_PID, facility=syslog.LOG_MAIL) 112 syslog.syslog('E-mail processing initiated...') 113
