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