Debian Codegraph @

Doc/library/syslog.rst

raw
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...')