| 1 |
:mod:`!syslog` --- Unix syslog library routines |
| 2 |
=============================================== |
| 3 |
|
| 4 |
.. module:: syslog |
| 5 |
:synopsis: An interface to the Unix syslog library routines. |
| 6 |
|
| 7 |
-------------- |
| 8 |
|
| 9 |
This module provides an interface to the Unix ``syslog`` library routines. |
| 10 |
Refer to the Unix manual pages for a detailed description of the ``syslog`` |
| 11 |
facility. |
| 12 |
|
| 13 |
.. availability:: Unix, not WASI, not iOS. |
| 14 |
|
| 15 |
This module wraps the system ``syslog`` family of routines. A pure Python |
| 16 |
library that can speak to a syslog server is available in the |
| 17 |
:mod:`logging.handlers` module as :class:`~logging.handlers.SysLogHandler`. |
| 18 |
|
| 19 |
The module defines the following functions: |
| 20 |
|
| 21 |
|
| 22 |
.. function:: syslog(message) |
| 23 |
syslog(priority, message) |
| 24 |
|
| 25 |
Send the string *message* to the system logger. A trailing newline is added |
| 26 |
if necessary. Each message is tagged with a priority composed of a |
| 27 |
*facility* and a *level*. The optional *priority* argument, which defaults |
| 28 |
to :const:`LOG_INFO`, determines the message priority. If the facility is |
| 29 |
not encoded in *priority* using logical-or (``LOG_INFO | LOG_USER``), the |
| 30 |
value given in the :func:`openlog` call is used. |
| 31 |
|
| 32 |
If :func:`openlog` has not been called prior to the call to :func:`syslog`, |
| 33 |
:func:`openlog` will be called with no arguments. |
| 34 |
|
| 35 |
.. audit-event:: syslog.syslog priority,message syslog.syslog |
| 36 |
|
| 37 |
.. versionchanged:: 3.2 |
| 38 |
In previous versions, :func:`openlog` would not be called automatically if |
| 39 |
it wasn't called prior to the call to :func:`syslog`, deferring to the syslog |
| 40 |
implementation to call ``openlog()``. |
| 41 |
|
| 42 |
.. versionchanged:: 3.12 |
| 43 |
This function is restricted in subinterpreters. |
| 44 |
(Only code that runs in multiple interpreters is affected and |
| 45 |
the restriction is not relevant for most users.) |
| 46 |
:func:`openlog` must be called in the main interpreter before :func:`syslog` may be used |
| 47 |
in a subinterpreter. Otherwise it will raise :exc:`RuntimeError`. |
| 48 |
|
| 49 |
|
| 50 |
.. function:: openlog([ident[, logoption[, facility]]]) |
| 51 |
|
| 52 |
Logging options of subsequent :func:`syslog` calls can be set by calling |
| 53 |
:func:`openlog`. :func:`syslog` will call :func:`openlog` with no arguments |
| 54 |
if the log is not currently open. |
| 55 |
|
| 56 |
The optional *ident* keyword argument is a string which is prepended to every |
| 57 |
message, and defaults to ``sys.argv[0]`` with leading path components |
| 58 |
stripped. The optional *logoption* keyword argument (default is 0) is a bit |
| 59 |
field -- see below for possible values to combine. The optional *facility* |
| 60 |
keyword argument (default is :const:`LOG_USER`) sets the default facility for |
| 61 |
messages which do not have a facility explicitly encoded. |
| 62 |
|
| 63 |
.. audit-event:: syslog.openlog ident,logoption,facility syslog.openlog |
| 64 |
|
| 65 |
.. versionchanged:: 3.2 |
| 66 |
In previous versions, keyword arguments were not allowed, and *ident* was |
| 67 |
required. |
| 68 |
|
| 69 |
.. versionchanged:: 3.12 |
| 70 |
This function is restricted in subinterpreters. |
| 71 |
(Only code that runs in multiple interpreters is affected and |
| 72 |
the restriction is not relevant for most users.) |
| 73 |
This may only be called in the main interpreter. |
| 74 |
It will raise :exc:`RuntimeError` if called in a subinterpreter. |
| 75 |
|
| 76 |
|
| 77 |
.. function:: closelog() |
| 78 |
|
| 79 |
Reset the syslog module values and call the system library ``closelog()``. |
| 80 |
|
| 81 |
This causes the module to behave as it does when initially imported. For |
| 82 |
example, :func:`openlog` will be called on the first :func:`syslog` call (if |
| 83 |
:func:`openlog` hasn't already been called), and *ident* and other |
| 84 |
:func:`openlog` parameters are reset to defaults. |
| 85 |
|
| 86 |
.. audit-event:: syslog.closelog "" syslog.closelog |
| 87 |
|
| 88 |
.. versionchanged:: 3.12 |
| 89 |
This function is restricted in subinterpreters. |
| 90 |
(Only code that runs in multiple interpreters is affected and |
| 91 |
the restriction is not relevant for most users.) |
| 92 |
This may only be called in the main interpreter. |
| 93 |
It will raise :exc:`RuntimeError` if called in a subinterpreter. |
| 94 |
|
| 95 |
|
| 96 |
.. function:: setlogmask(maskpri) |
| 97 |
|
| 98 |
Set the priority mask to *maskpri* and return the previous mask value. Calls |
| 99 |
to :func:`syslog` with a priority level not set in *maskpri* are ignored. |
| 100 |
The default is to log all priorities. The function ``LOG_MASK(pri)`` |
| 101 |
calculates the mask for the individual priority *pri*. The function |
| 102 |
``LOG_UPTO(pri)`` calculates the mask for all priorities up to and including |
| 103 |
*pri*. |
| 104 |
|
| 105 |
.. audit-event:: syslog.setlogmask maskpri syslog.setlogmask |
| 106 |
|
| 107 |
The module defines the following constants: |
| 108 |
|
| 109 |
|
| 110 |
.. data:: LOG_EMERG |
| 111 |
LOG_ALERT |
| 112 |
LOG_CRIT |
| 113 |
LOG_ERR |
| 114 |
LOG_WARNING |
| 115 |
LOG_NOTICE |
| 116 |
LOG_INFO |
| 117 |
LOG_DEBUG |
| 118 |
|
| 119 |
Priority levels (high to low). |
| 120 |
|
| 121 |
|
| 122 |
.. data:: LOG_AUTH |
| 123 |
LOG_AUTHPRIV |
| 124 |
LOG_CRON |
| 125 |
LOG_DAEMON |
| 126 |
LOG_FTP |
| 127 |
LOG_INSTALL |
| 128 |
LOG_KERN |
| 129 |
LOG_LAUNCHD |
| 130 |
LOG_LPR |
| 131 |
LOG_MAIL |
| 132 |
LOG_NETINFO |
| 133 |
LOG_NEWS |
| 134 |
LOG_RAS |
| 135 |
LOG_REMOTEAUTH |
| 136 |
LOG_SYSLOG |
| 137 |
LOG_USER |
| 138 |
LOG_UUCP |
| 139 |
LOG_LOCAL0 |
| 140 |
LOG_LOCAL1 |
| 141 |
LOG_LOCAL2 |
| 142 |
LOG_LOCAL3 |
| 143 |
LOG_LOCAL4 |
| 144 |
LOG_LOCAL5 |
| 145 |
LOG_LOCAL6 |
| 146 |
LOG_LOCAL7 |
| 147 |
|
| 148 |
Facilities, depending on availability in ``<syslog.h>`` for :const:`LOG_AUTHPRIV`, |
| 149 |
:const:`LOG_FTP`, :const:`LOG_NETINFO`, :const:`LOG_REMOTEAUTH`, |
| 150 |
:const:`LOG_INSTALL` and :const:`LOG_RAS`. |
| 151 |
|
| 152 |
.. versionchanged:: 3.13 |
| 153 |
Added :const:`LOG_FTP`, :const:`LOG_NETINFO`, :const:`LOG_REMOTEAUTH`, |
| 154 |
:const:`LOG_INSTALL`, :const:`LOG_RAS`, and :const:`LOG_LAUNCHD`. |
| 155 |
|
| 156 |
.. data:: LOG_PID |
| 157 |
LOG_CONS |
| 158 |
LOG_NDELAY |
| 159 |
LOG_ODELAY |
| 160 |
LOG_NOWAIT |
| 161 |
LOG_PERROR |
| 162 |
|
| 163 |
Log options, depending on availability in ``<syslog.h>`` for |
| 164 |
:const:`LOG_ODELAY`, :const:`LOG_NOWAIT` and :const:`LOG_PERROR`. |
| 165 |
|
| 166 |
|
| 167 |
Examples |
| 168 |
-------- |
| 169 |
|
| 170 |
Simple example |
| 171 |
~~~~~~~~~~~~~~ |
| 172 |
|
| 173 |
A simple set of examples:: |
| 174 |
|
| 175 |
import syslog |
| 176 |
|
| 177 |
syslog.syslog('Processing started') |
| 178 |
if error: |
| 179 |
syslog.syslog(syslog.LOG_ERR, 'Processing started') |
| 180 |
|
| 181 |
An example of setting some log options, these would include the process ID in |
| 182 |
logged messages, and write the messages to the destination facility used for |
| 183 |
mail logging:: |
| 184 |
|
| 185 |
syslog.openlog(logoption=syslog.LOG_PID, facility=syslog.LOG_MAIL) |
| 186 |
syslog.syslog('E-mail processing initiated...') |