Debian Codegraph @

Doc/library/logging.handlers.rst

raw
1 :mod:`!logging.handlers` --- Logging handlers
2 =============================================
3
4 .. module:: logging.handlers
5 :synopsis: Handlers for the logging module.
6
7 .. moduleauthor:: Vinay Sajip <[email protected]>
8 .. sectionauthor:: Vinay Sajip <[email protected]>
9
10 **Source code:** :source:`Lib/logging/handlers.py`
11
12 .. sidebar:: Important
13
14 This page contains only reference information. For tutorials,
15 please see
16
17 * :ref:`Basic Tutorial <logging-basic-tutorial>`
18 * :ref:`Advanced Tutorial <logging-advanced-tutorial>`
19 * :ref:`Logging Cookbook <logging-cookbook>`
20
21 --------------
22
23 .. currentmodule:: logging
24
25 The following useful handlers are provided in the package. Note that three of
26 the handlers (:class:`StreamHandler`, :class:`FileHandler` and
27 :class:`NullHandler`) are actually defined in the :mod:`logging` module itself,
28 but have been documented here along with the other handlers.
29
30 .. _stream-handler:
31
32 StreamHandler
33 ^^^^^^^^^^^^^
34
35 The :class:`StreamHandler` class, located in the core :mod:`logging` package,
36 sends logging output to streams such as *sys.stdout*, *sys.stderr* or any
37 file-like object (or, more precisely, any object which supports :meth:`write`
38 and :meth:`flush` methods).
39
40
41 .. class:: StreamHandler(stream=None)
42
43 Returns a new instance of the :class:`StreamHandler` class. If *stream* is
44 specified, the instance will use it for logging output; otherwise, *sys.stderr*
45 will be used.
46
47
48 .. method:: emit(record)
49
50 If a formatter is specified, it is used to format the record. The record
51 is then written to the stream followed by :attr:`terminator`. If exception information
52 is present, it is formatted using :func:`traceback.print_exception` and
53 appended to the stream.
54
55
56 .. method:: flush()
57
58 Flushes the stream by calling its :meth:`flush` method. Note that the
59 :meth:`close` method is inherited from :class:`~logging.Handler` and so
60 does no output, so an explicit :meth:`flush` call may be needed at times.
61
62 .. method:: setStream(stream)
63
64 Sets the instance's stream to the specified value, if it is different.
65 The old stream is flushed before the new stream is set.
66
67 :param stream: The stream that the handler should use.
68
69 :return: the old stream, if the stream was changed, or ``None`` if it wasn't.
70
71 .. versionadded:: 3.7
72
73 .. attribute:: terminator
74
75 String used as the terminator when writing a formatted record to a stream.
76 Default value is ``'\n'``.
77
78 If you don't want a newline termination, you can set the handler instance's
79 ``terminator`` attribute to the empty string.
80
81 In earlier versions, the terminator was hardcoded as ``'\n'``.
82
83 .. versionadded:: 3.2
84
85
86 .. _file-handler:
87
88 FileHandler
89 ^^^^^^^^^^^
90
91 The :class:`FileHandler` class, located in the core :mod:`logging` package,
92 sends logging output to a disk file. It inherits the output functionality from
93 :class:`StreamHandler`.
94
95
96 .. class:: FileHandler(filename, mode='a', encoding=None, delay=False, errors=None)
97
98 Returns a new instance of the :class:`FileHandler` class. The specified file is
99 opened and used as the stream for logging. If *mode* is not specified,
100 ``'a'`` is used. If *encoding* is not ``None``, it is used to open the file
101 with that encoding. If *delay* is true, then file opening is deferred until the
102 first call to :meth:`emit`. By default, the file grows indefinitely. If
103 *errors* is specified, it's used to determine how encoding errors are handled.
104
105 .. versionchanged:: 3.6
106 As well as string values, :class:`~pathlib.Path` objects are also accepted
107 for the *filename* argument.
108
109 .. versionchanged:: 3.9
110 The *errors* parameter was added.
111
112 .. method:: close()
113
114 Closes the file.
115
116 .. method:: emit(record)
117
118 Outputs the record to the file.
119
120 Note that if the file was closed due to logging shutdown at exit and the file
121 mode is 'w', the record will not be emitted (see :issue:`42378`).
122
123
124 .. _null-handler:
125
126 NullHandler
127 ^^^^^^^^^^^
128
129 .. versionadded:: 3.1
130
131 The :class:`NullHandler` class, located in the core :mod:`logging` package,
132 does not do any formatting or output. It is essentially a 'no-op' handler
133 for use by library developers.
134
135 .. class:: NullHandler()
136
137 Returns a new instance of the :class:`NullHandler` class.
138
139 .. method:: emit(record)
140
141 This method does nothing.
142
143 .. method:: handle(record)
144
145 This method does nothing.
146
147 .. method:: createLock()
148
149 This method returns ``None`` for the lock, since there is no
150 underlying I/O to which access needs to be serialized.
151
152
153 See :ref:`library-config` for more information on how to use
154 :class:`NullHandler`.
155
156 .. _watched-file-handler:
157
158 WatchedFileHandler
159 ^^^^^^^^^^^^^^^^^^
160
161 .. currentmodule:: logging.handlers
162
163 The :class:`WatchedFileHandler` class, located in the :mod:`logging.handlers`
164 module, is a :class:`FileHandler` which watches the file it is logging to. If
165 the file changes, it is closed and reopened using the file name.
166
167 A file change can happen because of usage of programs such as *newsyslog* and
168 *logrotate* which perform log file rotation. This handler, intended for use
169 under Unix/Linux, watches the file to see if it has changed since the last emit.
170 (A file is deemed to have changed if its device or inode have changed.) If the
171 file has changed, the old file stream is closed, and the file opened to get a
172 new stream.
173
174 This handler is not appropriate for use under Windows, because under Windows
175 open log files cannot be moved or renamed - logging opens the files with
176 exclusive locks - and so there is no need for such a handler. Furthermore,
177 *ST_INO* is not supported under Windows; :func:`~os.stat` always returns zero
178 for this value.
179
180
181 .. class:: WatchedFileHandler(filename, mode='a', encoding=None, delay=False, errors=None)
182
183 Returns a new instance of the :class:`WatchedFileHandler` class. The specified
184 file is opened and used as the stream for logging. If *mode* is not specified,
185 ``'a'`` is used. If *encoding* is not ``None``, it is used to open the file
186 with that encoding. If *delay* is true, then file opening is deferred until the
187 first call to :meth:`emit`. By default, the file grows indefinitely. If
188 *errors* is provided, it determines how encoding errors are handled.
189
190 .. versionchanged:: 3.6
191 As well as string values, :class:`~pathlib.Path` objects are also accepted
192 for the *filename* argument.
193
194 .. versionchanged:: 3.9
195 The *errors* parameter was added.
196
197 .. method:: reopenIfNeeded()
198
199 Checks to see if the file has changed. If it has, the existing stream is
200 flushed and closed and the file opened again, typically as a precursor to
201 outputting the record to the file.
202
203 .. versionadded:: 3.6
204
205
206 .. method:: emit(record)
207
208 Outputs the record to the file, but first calls :meth:`reopenIfNeeded` to
209 reopen the file if it has changed.
210
211 .. _base-rotating-handler:
212
213 BaseRotatingHandler
214 ^^^^^^^^^^^^^^^^^^^
215
216 The :class:`BaseRotatingHandler` class, located in the :mod:`logging.handlers`
217 module, is the base class for the rotating file handlers,
218 :class:`RotatingFileHandler` and :class:`TimedRotatingFileHandler`. You should
219 not need to instantiate this class, but it has attributes and methods you may
220 need to override.
221
222 .. class:: BaseRotatingHandler(filename, mode, encoding=None, delay=False, errors=None)
223
224 The parameters are as for :class:`FileHandler`. The attributes are:
225
226 .. attribute:: namer
227
228 If this attribute is set to a callable, the :meth:`rotation_filename`
229 method delegates to this callable. The parameters passed to the callable
230 are those passed to :meth:`rotation_filename`.
231
232 .. note:: The namer function is called quite a few times during rollover,
233 so it should be as simple and as fast as possible. It should also
234 return the same output every time for a given input, otherwise the
235 rollover behaviour may not work as expected.
236
237 It's also worth noting that care should be taken when using a namer to
238 preserve certain attributes in the filename which are used during rotation.
239 For example, :class:`RotatingFileHandler` expects to have a set of log files
240 whose names contain successive integers, so that rotation works as expected,
241 and :class:`TimedRotatingFileHandler` deletes old log files (based on the
242 ``backupCount`` parameter passed to the handler's initializer) by determining
243 the oldest files to delete. For this to happen, the filenames should be
244 sortable using the date/time portion of the filename, and a namer needs to
245 respect this. (If a namer is wanted that doesn't respect this scheme, it will
246 need to be used in a subclass of :class:`TimedRotatingFileHandler` which
247 overrides the :meth:`~TimedRotatingFileHandler.getFilesToDelete` method to
248 fit in with the custom naming scheme.)
249
250 .. versionadded:: 3.3
251
252
253 .. attribute:: BaseRotatingHandler.rotator
254
255 If this attribute is set to a callable, the :meth:`rotate` method
256 delegates to this callable. The parameters passed to the callable are
257 those passed to :meth:`rotate`.
258
259 .. versionadded:: 3.3
260
261 .. method:: BaseRotatingHandler.rotation_filename(default_name)
262
263 Modify the filename of a log file when rotating.
264
265 This is provided so that a custom filename can be provided.
266
267 The default implementation calls the 'namer' attribute of the handler,
268 if it's callable, passing the default name to it. If the attribute isn't
269 callable (the default is ``None``), the name is returned unchanged.
270
271 :param default_name: The default name for the log file.
272
273 .. versionadded:: 3.3
274
275
276 .. method:: BaseRotatingHandler.rotate(source, dest)
277
278 When rotating, rotate the current log.
279
280 The default implementation calls the 'rotator' attribute of the handler,
281 if it's callable, passing the source and dest arguments to it. If the
282 attribute isn't callable (the default is ``None``), the source is simply
283 renamed to the destination.
284
285 :param source: The source filename. This is normally the base
286 filename, e.g. 'test.log'.
287 :param dest: The destination filename. This is normally
288 what the source is rotated to, e.g. 'test.log.1'.
289
290 .. versionadded:: 3.3
291
292 The reason the attributes exist is to save you having to subclass - you can use
293 the same callables for instances of :class:`RotatingFileHandler` and
294 :class:`TimedRotatingFileHandler`. If either the namer or rotator callable
295 raises an exception, this will be handled in the same way as any other
296 exception during an :meth:`emit` call, i.e. via the :meth:`handleError` method
297 of the handler.
298
299 If you need to make more significant changes to rotation processing, you can
300 override the methods.
301
302 For an example, see :ref:`cookbook-rotator-namer`.
303
304
305 .. _rotating-file-handler:
306
307 RotatingFileHandler
308 ^^^^^^^^^^^^^^^^^^^
309
310 The :class:`RotatingFileHandler` class, located in the :mod:`logging.handlers`
311 module, supports rotation of disk log files.
312
313
314 .. class:: RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=False, errors=None)
315
316 Returns a new instance of the :class:`RotatingFileHandler` class. The specified
317 file is opened and used as the stream for logging. If *mode* is not specified,
318 ``'a'`` is used. If *encoding* is not ``None``, it is used to open the file
319 with that encoding. If *delay* is true, then file opening is deferred until the
320 first call to :meth:`emit`. By default, the file grows indefinitely. If
321 *errors* is provided, it determines how encoding errors are handled.
322
323 You can use the *maxBytes* and *backupCount* values to allow the file to
324 :dfn:`rollover` at a predetermined size. When the size is about to be exceeded,
325 the file is closed and a new file is silently opened for output. Rollover occurs
326 whenever the current log file is nearly *maxBytes* in length; but if either of
327 *maxBytes* or *backupCount* is zero, rollover never occurs, so you generally want
328 to set *backupCount* to at least 1, and have a non-zero *maxBytes*.
329 When *backupCount* is non-zero, the system will save old log files by appending
330 the extensions '.1', '.2' etc., to the filename. For example, with a *backupCount*
331 of 5 and a base file name of :file:`app.log`, you would get :file:`app.log`,
332 :file:`app.log.1`, :file:`app.log.2`, up to :file:`app.log.5`. The file being
333 written to is always :file:`app.log`. When this file is filled, it is closed
334 and renamed to :file:`app.log.1`, and if files :file:`app.log.1`,
335 :file:`app.log.2`, etc. exist, then they are renamed to :file:`app.log.2`,
336 :file:`app.log.3` etc. respectively.
337
338 .. versionchanged:: 3.6
339 As well as string values, :class:`~pathlib.Path` objects are also accepted
340 for the *filename* argument.
341
342 .. versionchanged:: 3.9
343 The *errors* parameter was added.
344
345 .. method:: doRollover()
346
347 Does a rollover, as described above.
348
349
350 .. method:: emit(record)
351
352 Outputs the record to the file, catering for rollover as described
353 previously.
354
355 .. method:: shouldRollover(record)
356
357 See if the supplied record would cause the file to exceed the configured size limit.
358
359 .. _timed-rotating-file-handler:
360
361 TimedRotatingFileHandler
362 ^^^^^^^^^^^^^^^^^^^^^^^^
363
364 The :class:`TimedRotatingFileHandler` class, located in the
365 :mod:`logging.handlers` module, supports rotation of disk log files at certain
366 timed intervals.
367
368
369 .. class:: TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None, errors=None)
370
371 Returns a new instance of the :class:`TimedRotatingFileHandler` class. The
372 specified file is opened and used as the stream for logging. On rotating it also
373 sets the filename suffix. Rotating happens based on the product of *when* and
374 *interval*.
375
376 You can use the *when* to specify the type of *interval*. The list of possible
377 values is below. Note that they are not case sensitive.
378
379 +----------------+----------------------------+-------------------------+
380 | Value | Type of interval | If/how *atTime* is used |
381 +================+============================+=========================+
382 | ``'S'`` | Seconds | Ignored |
383 +----------------+----------------------------+-------------------------+
384 | ``'M'`` | Minutes | Ignored |
385 +----------------+----------------------------+-------------------------+
386 | ``'H'`` | Hours | Ignored |
387 +----------------+----------------------------+-------------------------+
388 | ``'D'`` | Days | Ignored |
389 +----------------+----------------------------+-------------------------+
390 | ``'W0'-'W6'`` | Weekday (0=Monday) | Used to compute initial |
391 | | | rollover time |
392 +----------------+----------------------------+-------------------------+
393 | ``'midnight'`` | Roll over at midnight, if | Used to compute initial |
394 | | *atTime* not specified, | rollover time |
395 | | else at time *atTime* | |
396 +----------------+----------------------------+-------------------------+
397
398 When using weekday-based rotation, specify 'W0' for Monday, 'W1' for
399 Tuesday, and so on up to 'W6' for Sunday. In this case, the value passed for
400 *interval* isn't used.
401
402 The system will save old log files by appending extensions to the filename.
403 The extensions are date-and-time based, using the strftime format
404 ``%Y-%m-%d_%H-%M-%S`` or a leading portion thereof, depending on the
405 rollover interval.
406
407 When computing the next rollover time for the first time (when the handler
408 is created), the last modification time of an existing log file, or else
409 the current time, is used to compute when the next rotation will occur.
410
411 If the *utc* argument is true, times in UTC will be used; otherwise
412 local time is used.
413
414 If *backupCount* is nonzero, at most *backupCount* files
415 will be kept, and if more would be created when rollover occurs, the oldest
416 one is deleted. The deletion logic uses the interval to determine which
417 files to delete, so changing the interval may leave old files lying around.
418
419 If *delay* is true, then file opening is deferred until the first call to
420 :meth:`emit`.
421
422 If *atTime* is not ``None``, it must be a ``datetime.time`` instance which
423 specifies the time of day when rollover occurs, for the cases where rollover
424 is set to happen "at midnight" or "on a particular weekday". Note that in
425 these cases, the *atTime* value is effectively used to compute the *initial*
426 rollover, and subsequent rollovers would be calculated via the normal
427 interval calculation.
428
429 If *errors* is specified, it's used to determine how encoding errors are
430 handled.
431
432 .. note:: Calculation of the initial rollover time is done when the handler
433 is initialised. Calculation of subsequent rollover times is done only
434 when rollover occurs, and rollover occurs only when emitting output. If
435 this is not kept in mind, it might lead to some confusion. For example,
436 if an interval of "every minute" is set, that does not mean you will
437 always see log files with times (in the filename) separated by a minute;
438 if, during application execution, logging output is generated more
439 frequently than once a minute, *then* you can expect to see log files
440 with times separated by a minute. If, on the other hand, logging messages
441 are only output once every five minutes (say), then there will be gaps in
442 the file times corresponding to the minutes where no output (and hence no
443 rollover) occurred.
444
445 .. versionchanged:: 3.4
446 *atTime* parameter was added.
447
448 .. versionchanged:: 3.6
449 As well as string values, :class:`~pathlib.Path` objects are also accepted
450 for the *filename* argument.
451
452 .. versionchanged:: 3.9
453 The *errors* parameter was added.
454
455 .. method:: doRollover()
456
457 Does a rollover, as described above.
458
459 .. method:: emit(record)
460
461 Outputs the record to the file, catering for rollover as described above.
462
463 .. method:: getFilesToDelete()
464
465 Returns a list of filenames which should be deleted as part of rollover. These
466 are the absolute paths of the oldest backup log files written by the handler.
467
468 .. method:: shouldRollover(record)
469
470 See if enough time has passed for a rollover to occur and if it has, compute
471 the next rollover time.
472
473 .. _socket-handler:
474
475 SocketHandler
476 ^^^^^^^^^^^^^
477
478 The :class:`SocketHandler` class, located in the :mod:`logging.handlers` module,
479 sends logging output to a network socket. The base class uses a TCP socket.
480
481
482 .. class:: SocketHandler(host, port)
483
484 Returns a new instance of the :class:`SocketHandler` class intended to
485 communicate with a remote machine whose address is given by *host* and *port*.
486
487 .. versionchanged:: 3.4
488 If ``port`` is specified as ``None``, a Unix domain socket is created
489 using the value in ``host`` - otherwise, a TCP socket is created.
490
491 .. method:: close()
492
493 Closes the socket.
494
495
496 .. method:: emit()
497
498 Pickles the record's attribute dictionary and writes it to the socket in
499 binary format. If there is an error with the socket, silently drops the
500 packet. If the connection was previously lost, re-establishes the
501 connection. To unpickle the record at the receiving end into a
502 :class:`~logging.LogRecord`, use the :func:`~logging.makeLogRecord`
503 function.
504
505
506 .. method:: handleError()
507
508 Handles an error which has occurred during :meth:`emit`. The most likely
509 cause is a lost connection. Closes the socket so that we can retry on the
510 next event.
511
512
513 .. method:: makeSocket()
514
515 This is a factory method which allows subclasses to define the precise
516 type of socket they want. The default implementation creates a TCP socket
517 (:const:`socket.SOCK_STREAM`).
518
519
520 .. method:: makePickle(record)
521
522 Pickles the record's attribute dictionary in binary format with a length
523 prefix, and returns it ready for transmission across the socket. The
524 details of this operation are equivalent to::
525
526 data = pickle.dumps(record_attr_dict, 1)
527 datalen = struct.pack('>L', len(data))
528 return datalen + data
529
530 Note that pickles aren't completely secure. If you are concerned about
531 security, you may want to override this method to implement a more secure
532 mechanism. For example, you can sign pickles using HMAC and then verify
533 them on the receiving end, or alternatively you can disable unpickling of
534 global objects on the receiving end.
535
536
537 .. method:: send(packet)
538
539 Send a pickled byte-string *packet* to the socket. The format of the sent
540 byte-string is as described in the documentation for
541 :meth:`~SocketHandler.makePickle`.
542
543 This function allows for partial sends, which can happen when the network
544 is busy.
545
546
547 .. method:: createSocket()
548
549 Tries to create a socket; on failure, uses an exponential back-off
550 algorithm. On initial failure, the handler will drop the message it was
551 trying to send. When subsequent messages are handled by the same
552 instance, it will not try connecting until some time has passed. The
553 default parameters are such that the initial delay is one second, and if
554 after that delay the connection still can't be made, the handler will
555 double the delay each time up to a maximum of 30 seconds.
556
557 This behaviour is controlled by the following handler attributes:
558
559 * ``retryStart`` (initial delay, defaulting to 1.0 seconds).
560 * ``retryFactor`` (multiplier, defaulting to 2.0).
561 * ``retryMax`` (maximum delay, defaulting to 30.0 seconds).
562
563 This means that if the remote listener starts up *after* the handler has
564 been used, you could lose messages (since the handler won't even attempt
565 a connection until the delay has elapsed, but just silently drop messages
566 during the delay period).
567
568
569 .. _datagram-handler:
570
571 DatagramHandler
572 ^^^^^^^^^^^^^^^
573
574 The :class:`DatagramHandler` class, located in the :mod:`logging.handlers`
575 module, inherits from :class:`SocketHandler` to support sending logging messages
576 over UDP sockets.
577
578
579 .. class:: DatagramHandler(host, port)
580
581 Returns a new instance of the :class:`DatagramHandler` class intended to
582 communicate with a remote machine whose address is given by *host* and *port*.
583
584 .. note:: As UDP is not a streaming protocol, there is no persistent connection
585 between an instance of this handler and *host*. For this reason, when using a
586 network socket, a DNS lookup might have to be made each time an event is
587 logged, which can introduce some latency into the system. If this affects you,
588 you can do a lookup yourself and initialize this handler using the looked-up IP
589 address rather than the hostname.
590
591 .. versionchanged:: 3.4
592 If ``port`` is specified as ``None``, a Unix domain socket is created
593 using the value in ``host`` - otherwise, a UDP socket is created.
594
595 .. method:: emit()
596
597 Pickles the record's attribute dictionary and writes it to the socket in
598 binary format. If there is an error with the socket, silently drops the
599 packet. To unpickle the record at the receiving end into a
600 :class:`~logging.LogRecord`, use the :func:`~logging.makeLogRecord`
601 function.
602
603
604 .. method:: makeSocket()
605
606 The factory method of :class:`SocketHandler` is here overridden to create
607 a UDP socket (:const:`socket.SOCK_DGRAM`).
608
609
610 .. method:: send(s)
611
612 Send a pickled byte-string to a socket. The format of the sent byte-string
613 is as described in the documentation for :meth:`SocketHandler.makePickle`.
614
615
616 .. _syslog-handler:
617
618 SysLogHandler
619 ^^^^^^^^^^^^^
620
621 The :class:`SysLogHandler` class, located in the :mod:`logging.handlers` module,
622 supports sending logging messages to a remote or local Unix syslog.
623
624
625 .. class:: SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM)
626
627 Returns a new instance of the :class:`SysLogHandler` class intended to
628 communicate with a remote Unix machine whose address is given by *address* in
629 the form of a ``(host, port)`` tuple. If *address* is not specified,
630 ``('localhost', 514)`` is used. The address is used to open a socket. An
631 alternative to providing a ``(host, port)`` tuple is providing an address as a
632 string, for example '/dev/log'. In this case, a Unix domain socket is used to
633 send the message to the syslog. If *facility* is not specified,
634 :const:`LOG_USER` is used. The type of socket opened depends on the
635 *socktype* argument, which defaults to :const:`socket.SOCK_DGRAM` and thus
636 opens a UDP socket. To open a TCP socket (for use with the newer syslog
637 daemons such as rsyslog), specify a value of :const:`socket.SOCK_STREAM`.
638
639 Note that if your server is not listening on UDP port 514,
640 :class:`SysLogHandler` may appear not to work. In that case, check what
641 address you should be using for a domain socket - it's system dependent.
642 For example, on Linux it's usually '/dev/log' but on OS/X it's
643 '/var/run/syslog'. You'll need to check your platform and use the
644 appropriate address (you may need to do this check at runtime if your
645 application needs to run on several platforms). On Windows, you pretty
646 much have to use the UDP option.
647
648 .. note:: On macOS 12.x (Monterey), Apple has changed the behaviour of their
649 syslog daemon - it no longer listens on a domain socket. Therefore, you cannot
650 expect :class:`SysLogHandler` to work on this system.
651
652 See :gh:`91070` for more information.
653
654 .. versionchanged:: 3.2
655 *socktype* was added.
656
657
658 .. method:: close()
659
660 Closes the socket to the remote host.
661
662 .. method:: createSocket()
663
664 Tries to create a socket and, if it's not a datagram socket, connect it
665 to the other end. This method is called during handler initialization,
666 but it's not regarded as an error if the other end isn't listening at
667 this point - the method will be called again when emitting an event, if
668 there is no socket at that point.
669
670 .. versionadded:: 3.11
671
672 .. method:: emit(record)
673
674 The record is formatted, and then sent to the syslog server. If exception
675 information is present, it is *not* sent to the server.
676
677 .. versionchanged:: 3.2.1
678 (See: :issue:`12168`.) In earlier versions, the message sent to the
679 syslog daemons was always terminated with a NUL byte, because early
680 versions of these daemons expected a NUL terminated message - even
681 though it's not in the relevant specification (:rfc:`5424`). More recent
682 versions of these daemons don't expect the NUL byte but strip it off
683 if it's there, and even more recent daemons (which adhere more closely
684 to RFC 5424) pass the NUL byte on as part of the message.
685
686 To enable easier handling of syslog messages in the face of all these
687 differing daemon behaviours, the appending of the NUL byte has been
688 made configurable, through the use of a class-level attribute,
689 ``append_nul``. This defaults to ``True`` (preserving the existing
690 behaviour) but can be set to ``False`` on a ``SysLogHandler`` instance
691 in order for that instance to *not* append the NUL terminator.
692
693 .. versionchanged:: 3.3
694 (See: :issue:`12419`.) In earlier versions, there was no facility for
695 an "ident" or "tag" prefix to identify the source of the message. This
696 can now be specified using a class-level attribute, defaulting to
697 ``""`` to preserve existing behaviour, but which can be overridden on
698 a ``SysLogHandler`` instance in order for that instance to prepend
699 the ident to every message handled. Note that the provided ident must
700 be text, not bytes, and is prepended to the message exactly as is.
701
702 .. method:: encodePriority(facility, priority)
703
704 Encodes the facility and priority into an integer. You can pass in strings
705 or integers - if strings are passed, internal mapping dictionaries are
706 used to convert them to integers.
707
708 The symbolic ``LOG_`` values are defined in :class:`SysLogHandler` and
709 mirror the values defined in the ``sys/syslog.h`` header file.
710
711 **Priorities**
712
713 +--------------------------+---------------+
714 | Name (string) | Symbolic value|
715 +==========================+===============+
716 | ``alert`` | LOG_ALERT |
717 +--------------------------+---------------+
718 | ``crit`` or ``critical`` | LOG_CRIT |
719 +--------------------------+---------------+
720 | ``debug`` | LOG_DEBUG |
721 +--------------------------+---------------+
722 | ``emerg`` or ``panic`` | LOG_EMERG |
723 +--------------------------+---------------+
724 | ``err`` or ``error`` | LOG_ERR |
725 +--------------------------+---------------+
726 | ``info`` | LOG_INFO |
727 +--------------------------+---------------+
728 | ``notice`` | LOG_NOTICE |
729 +--------------------------+---------------+
730 | ``warn`` or ``warning`` | LOG_WARNING |
731 +--------------------------+---------------+
732
733 **Facilities**
734
735 +---------------+---------------+
736 | Name (string) | Symbolic value|
737 +===============+===============+
738 | ``auth`` | LOG_AUTH |
739 +---------------+---------------+
740 | ``authpriv`` | LOG_AUTHPRIV |
741 +---------------+---------------+
742 | ``cron`` | LOG_CRON |
743 +---------------+---------------+
744 | ``daemon`` | LOG_DAEMON |
745 +---------------+---------------+
746 | ``ftp`` | LOG_FTP |
747 +---------------+---------------+
748 | ``kern`` | LOG_KERN |
749 +---------------+---------------+
750 | ``lpr`` | LOG_LPR |
751 +---------------+---------------+
752 | ``mail`` | LOG_MAIL |
753 +---------------+---------------+
754 | ``news`` | LOG_NEWS |
755 +---------------+---------------+
756 | ``syslog`` | LOG_SYSLOG |
757 +---------------+---------------+
758 | ``user`` | LOG_USER |
759 +---------------+---------------+
760 | ``uucp`` | LOG_UUCP |
761 +---------------+---------------+
762 | ``local0`` | LOG_LOCAL0 |
763 +---------------+---------------+
764 | ``local1`` | LOG_LOCAL1 |
765 +---------------+---------------+
766 | ``local2`` | LOG_LOCAL2 |
767 +---------------+---------------+
768 | ``local3`` | LOG_LOCAL3 |
769 +---------------+---------------+
770 | ``local4`` | LOG_LOCAL4 |
771 +---------------+---------------+
772 | ``local5`` | LOG_LOCAL5 |
773 +---------------+---------------+
774 | ``local6`` | LOG_LOCAL6 |
775 +---------------+---------------+
776 | ``local7`` | LOG_LOCAL7 |
777 +---------------+---------------+
778
779 .. method:: mapPriority(levelname)
780
781 Maps a logging level name to a syslog priority name.
782 You may need to override this if you are using custom levels, or
783 if the default algorithm is not suitable for your needs. The
784 default algorithm maps ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR`` and
785 ``CRITICAL`` to the equivalent syslog names, and all other level
786 names to 'warning'.
787
788 .. _nt-eventlog-handler:
789
790 NTEventLogHandler
791 ^^^^^^^^^^^^^^^^^
792
793 The :class:`NTEventLogHandler` class, located in the :mod:`logging.handlers`
794 module, supports sending logging messages to a local Windows NT, Windows 2000 or
795 Windows XP event log. Before you can use it, you need Mark Hammond's Win32
796 extensions for Python installed.
797
798
799 .. class:: NTEventLogHandler(appname, dllname=None, logtype='Application')
800
801 Returns a new instance of the :class:`NTEventLogHandler` class. The *appname* is
802 used to define the application name as it appears in the event log. An
803 appropriate registry entry is created using this name. The *dllname* should give
804 the fully qualified pathname of a .dll or .exe which contains message
805 definitions to hold in the log (if not specified, ``'win32service.pyd'`` is used
806 - this is installed with the Win32 extensions and contains some basic
807 placeholder message definitions. Note that use of these placeholders will make
808 your event logs big, as the entire message source is held in the log. If you
809 want slimmer logs, you have to pass in the name of your own .dll or .exe which
810 contains the message definitions you want to use in the event log). The
811 *logtype* is one of ``'Application'``, ``'System'`` or ``'Security'``, and
812 defaults to ``'Application'``.
813
814
815 .. method:: close()
816
817 At this point, you can remove the application name from the registry as a
818 source of event log entries. However, if you do this, you will not be able
819 to see the events as you intended in the Event Log Viewer - it needs to be
820 able to access the registry to get the .dll name. The current version does
821 not do this.
822
823
824 .. method:: emit(record)
825
826 Determines the message ID, event category and event type, and then logs
827 the message in the NT event log.
828
829
830 .. method:: getEventCategory(record)
831
832 Returns the event category for the record. Override this if you want to
833 specify your own categories. This version returns 0.
834
835
836 .. method:: getEventType(record)
837
838 Returns the event type for the record. Override this if you want to
839 specify your own types. This version does a mapping using the handler's
840 typemap attribute, which is set up in :meth:`__init__` to a dictionary
841 which contains mappings for :const:`DEBUG`, :const:`INFO`,
842 :const:`WARNING`, :const:`ERROR` and :const:`CRITICAL`. If you are using
843 your own levels, you will either need to override this method or place a
844 suitable dictionary in the handler's *typemap* attribute.
845
846
847 .. method:: getMessageID(record)
848
849 Returns the message ID for the record. If you are using your own messages,
850 you could do this by having the *msg* passed to the logger being an ID
851 rather than a format string. Then, in here, you could use a dictionary
852 lookup to get the message ID. This version returns 1, which is the base
853 message ID in :file:`win32service.pyd`.
854
855 .. _smtp-handler:
856
857 SMTPHandler
858 ^^^^^^^^^^^
859
860 The :class:`SMTPHandler` class, located in the :mod:`logging.handlers` module,
861 supports sending logging messages to an email address via SMTP.
862
863
864 .. class:: SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0)
865
866 Returns a new instance of the :class:`SMTPHandler` class. The instance is
867 initialized with the from and to addresses and subject line of the email. The
868 *toaddrs* should be a list of strings. To specify a non-standard SMTP port, use
869 the (host, port) tuple format for the *mailhost* argument. If you use a string,
870 the standard SMTP port is used. If your SMTP server requires authentication, you
871 can specify a (username, password) tuple for the *credentials* argument.
872
873 To specify the use of a secure protocol (TLS), pass in a tuple to the
874 *secure* argument. This will only be used when authentication credentials are
875 supplied. The tuple should be either an empty tuple, or a single-value tuple
876 with the name of a keyfile, or a 2-value tuple with the names of the keyfile
877 and certificate file. (This tuple is passed to the
878 :meth:`smtplib.SMTP.starttls` method.)
879
880 A timeout can be specified for communication with the SMTP server using the
881 *timeout* argument.
882
883 .. versionchanged:: 3.3
884 Added the *timeout* parameter.
885
886 .. method:: emit(record)
887
888 Formats the record and sends it to the specified addressees.
889
890
891 .. method:: getSubject(record)
892
893 If you want to specify a subject line which is record-dependent, override
894 this method.
895
896 .. _memory-handler:
897
898 MemoryHandler
899 ^^^^^^^^^^^^^
900
901 The :class:`MemoryHandler` class, located in the :mod:`logging.handlers` module,
902 supports buffering of logging records in memory, periodically flushing them to a
903 :dfn:`target` handler. Flushing occurs whenever the buffer is full, or when an
904 event of a certain severity or greater is seen.
905
906 :class:`MemoryHandler` is a subclass of the more general
907 :class:`BufferingHandler`, which is an abstract class. This buffers logging
908 records in memory. Whenever each record is added to the buffer, a check is made
909 by calling :meth:`shouldFlush` to see if the buffer should be flushed. If it
910 should, then :meth:`flush` is expected to do the flushing.
911
912
913 .. class:: BufferingHandler(capacity)
914
915 Initializes the handler with a buffer of the specified capacity. Here,
916 *capacity* means the number of logging records buffered.
917
918
919 .. method:: emit(record)
920
921 Append the record to the buffer. If :meth:`shouldFlush` returns true,
922 call :meth:`flush` to process the buffer.
923
924
925 .. method:: flush()
926
927 For a :class:`BufferingHandler` instance, flushing means that it sets the
928 buffer to an empty list. This method can be overwritten to implement more useful
929 flushing behavior.
930
931
932 .. method:: shouldFlush(record)
933
934 Return ``True`` if the buffer is up to capacity. This method can be
935 overridden to implement custom flushing strategies.
936
937
938 .. class:: MemoryHandler(capacity, flushLevel=ERROR, target=None, flushOnClose=True)
939
940 Returns a new instance of the :class:`MemoryHandler` class. The instance is
941 initialized with a buffer size of *capacity* (number of records buffered).
942 If *flushLevel* is not specified, :const:`ERROR` is used. If no *target* is
943 specified, the target will need to be set using :meth:`setTarget` before this
944 handler does anything useful. If *flushOnClose* is specified as ``False``,
945 then the buffer is *not* flushed when the handler is closed. If not specified
946 or specified as ``True``, the previous behaviour of flushing the buffer will
947 occur when the handler is closed.
948
949 .. versionchanged:: 3.6
950 The *flushOnClose* parameter was added.
951
952
953 .. method:: close()
954
955 Calls :meth:`flush`, sets the target to ``None`` and clears the
956 buffer.
957
958
959 .. method:: flush()
960
961 For a :class:`MemoryHandler` instance, flushing means just sending the buffered
962 records to the target, if there is one. The buffer is also cleared when
963 buffered records are sent to the target. Override if you want different behavior.
964
965
966 .. method:: setTarget(target)
967
968 Sets the target handler for this handler.
969
970
971 .. method:: shouldFlush(record)
972
973 Checks for buffer full or a record at the *flushLevel* or higher.
974
975
976 .. _http-handler:
977
978 HTTPHandler
979 ^^^^^^^^^^^
980
981 The :class:`HTTPHandler` class, located in the :mod:`logging.handlers` module,
982 supports sending logging messages to a web server, using either ``GET`` or
983 ``POST`` semantics.
984
985
986 .. class:: HTTPHandler(host, url, method='GET', secure=False, credentials=None, context=None)
987
988 Returns a new instance of the :class:`HTTPHandler` class. The *host* can be
989 of the form ``host:port``, should you need to use a specific port number. If
990 no *method* is specified, ``GET`` is used. If *secure* is true, a HTTPS
991 connection will be used. The *context* parameter may be set to a
992 :class:`ssl.SSLContext` instance to configure the SSL settings used for the
993 HTTPS connection. If *credentials* is specified, it should be a 2-tuple
994 consisting of userid and password, which will be placed in a HTTP
995 'Authorization' header using Basic authentication. If you specify
996 credentials, you should also specify secure=True so that your userid and
997 password are not passed in cleartext across the wire.
998
999 .. versionchanged:: 3.5
1000 The *context* parameter was added.
1001
1002 .. method:: mapLogRecord(record)
1003
1004 Provides a dictionary, based on ``record``, which is to be URL-encoded
1005 and sent to the web server. The default implementation just returns
1006 ``record.__dict__``. This method can be overridden if e.g. only a
1007 subset of :class:`~logging.LogRecord` is to be sent to the web server, or
1008 if more specific customization of what's sent to the server is required.
1009
1010 .. method:: emit(record)
1011
1012 Sends the record to the web server as a URL-encoded dictionary. The
1013 :meth:`mapLogRecord` method is used to convert the record to the
1014 dictionary to be sent.
1015
1016 .. note:: Since preparing a record for sending it to a web server is not
1017 the same as a generic formatting operation, using
1018 :meth:`~logging.Handler.setFormatter` to specify a
1019 :class:`~logging.Formatter` for a :class:`HTTPHandler` has no effect.
1020 Instead of calling :meth:`~logging.Handler.format`, this handler calls
1021 :meth:`mapLogRecord` and then :func:`urllib.parse.urlencode` to encode the
1022 dictionary in a form suitable for sending to a web server.
1023
1024
1025 .. _queue-handler:
1026
1027
1028 QueueHandler
1029 ^^^^^^^^^^^^
1030
1031 .. versionadded:: 3.2
1032
1033 The :class:`QueueHandler` class, located in the :mod:`logging.handlers` module,
1034 supports sending logging messages to a queue, such as those implemented in the
1035 :mod:`queue` or :mod:`multiprocessing` modules.
1036
1037 Along with the :class:`QueueListener` class, :class:`QueueHandler` can be used
1038 to let handlers do their work on a separate thread from the one which does the
1039 logging. This is important in web applications and also other service
1040 applications where threads servicing clients need to respond as quickly as
1041 possible, while any potentially slow operations (such as sending an email via
1042 :class:`SMTPHandler`) are done on a separate thread.
1043
1044 .. class:: QueueHandler(queue)
1045
1046 Returns a new instance of the :class:`QueueHandler` class. The instance is
1047 initialized with the queue to send messages to. The *queue* can be any
1048 queue-like object; it's used as-is by the :meth:`enqueue` method, which
1049 needs to know how to send messages to it. The queue is not *required* to
1050 have the task tracking API, which means that you can use
1051 :class:`~queue.SimpleQueue` instances for *queue*.
1052
1053 .. note:: If you are using :mod:`multiprocessing`, you should avoid using
1054 :class:`~queue.SimpleQueue` and instead use :class:`multiprocessing.Queue`.
1055
1056 .. warning::
1057
1058 The :mod:`multiprocessing` module uses an internal logger created and
1059 accessed via :meth:`~multiprocessing.get_logger`.
1060 :class:`multiprocessing.Queue` will log ``DEBUG`` level messages upon
1061 items being queued. If those log messages are processed by a
1062 :class:`QueueHandler` using the same :class:`multiprocessing.Queue` instance,
1063 it will cause a deadlock or infinite recursion.
1064
1065 .. method:: emit(record)
1066
1067 Enqueues the result of preparing the LogRecord. Should an exception
1068 occur (e.g. because a bounded queue has filled up), the
1069 :meth:`~logging.Handler.handleError` method is called to handle the
1070 error. This can result in the record silently being dropped (if
1071 :data:`logging.raiseExceptions` is ``False``) or a message printed to
1072 ``sys.stderr`` (if :data:`logging.raiseExceptions` is ``True``).
1073
1074 .. method:: prepare(record)
1075
1076 Prepares a record for queuing. The object returned by this
1077 method is enqueued.
1078
1079 The base implementation formats the record to merge the message,
1080 arguments, exception and stack information, if present. It also removes
1081 unpickleable items from the record in-place. Specifically, it overwrites
1082 the record's :attr:`msg` and :attr:`message` attributes with the merged
1083 message (obtained by calling the handler's :meth:`format` method), and
1084 sets the :attr:`args`, :attr:`exc_info` and :attr:`exc_text` attributes
1085 to ``None``.
1086
1087 You might want to override this method if you want to convert
1088 the record to a dict or JSON string, or send a modified copy
1089 of the record while leaving the original intact.
1090
1091 .. note:: The base implementation formats the message with arguments, sets
1092 the ``message`` and ``msg`` attributes to the formatted message and
1093 sets the ``args`` and ``exc_text`` attributes to ``None`` to allow
1094 pickling and to prevent further attempts at formatting. This means
1095 that a handler on the :class:`QueueListener` side won't have the
1096 information to do custom formatting, e.g. of exceptions. You may wish
1097 to subclass ``QueueHandler`` and override this method to e.g. avoid
1098 setting ``exc_text`` to ``None``. Note that the ``message`` / ``msg``
1099 / ``args`` changes are related to ensuring the record is pickleable,
1100 and you might or might not be able to avoid doing that depending on
1101 whether your ``args`` are pickleable. (Note that you may have to
1102 consider not only your own code but also code in any libraries that
1103 you use.)
1104
1105 .. method:: enqueue(record)
1106
1107 Enqueues the record on the queue using ``put_nowait()``; you may
1108 want to override this if you want to use blocking behaviour, or a
1109 timeout, or a customized queue implementation.
1110
1111 .. attribute:: listener
1112
1113 When created via configuration using :func:`~logging.config.dictConfig`, this
1114 attribute will contain a :class:`QueueListener` instance for use with this
1115 handler. Otherwise, it will be ``None``.
1116
1117 .. versionadded:: 3.12
1118
1119 .. _queue-listener:
1120
1121 QueueListener
1122 ^^^^^^^^^^^^^
1123
1124 .. versionadded:: 3.2
1125
1126 The :class:`QueueListener` class, located in the :mod:`logging.handlers`
1127 module, supports receiving logging messages from a queue, such as those
1128 implemented in the :mod:`queue` or :mod:`multiprocessing` modules. The
1129 messages are received from a queue in an internal thread and passed, on
1130 the same thread, to one or more handlers for processing. While
1131 :class:`QueueListener` is not itself a handler, it is documented here
1132 because it works hand-in-hand with :class:`QueueHandler`.
1133
1134 Along with the :class:`QueueHandler` class, :class:`QueueListener` can be used
1135 to let handlers do their work on a separate thread from the one which does the
1136 logging. This is important in web applications and also other service
1137 applications where threads servicing clients need to respond as quickly as
1138 possible, while any potentially slow operations (such as sending an email via
1139 :class:`SMTPHandler`) are done on a separate thread.
1140
1141 .. class:: QueueListener(queue, *handlers, respect_handler_level=False)
1142
1143 Returns a new instance of the :class:`QueueListener` class. The instance is
1144 initialized with the queue to send messages to and a list of handlers which
1145 will handle entries placed on the queue. The queue can be any queue-like
1146 object; it's passed as-is to the :meth:`dequeue` method, which needs
1147 to know how to get messages from it. The queue is not *required* to have the
1148 task tracking API (though it's used if available), which means that you can
1149 use :class:`~queue.SimpleQueue` instances for *queue*.
1150
1151 .. note:: If you are using :mod:`multiprocessing`, you should avoid using
1152 :class:`~queue.SimpleQueue` and instead use :class:`multiprocessing.Queue`.
1153
1154 If ``respect_handler_level`` is ``True``, a handler's level is respected
1155 (compared with the level for the message) when deciding whether to pass
1156 messages to that handler; otherwise, the behaviour is as in previous Python
1157 versions - to always pass each message to each handler.
1158
1159 .. versionchanged:: 3.5
1160 The ``respect_handler_level`` argument was added.
1161
1162 .. method:: dequeue(block)
1163
1164 Dequeues a record and return it, optionally blocking.
1165
1166 The base implementation uses ``get()``. You may want to override this
1167 method if you want to use timeouts or work with custom queue
1168 implementations.
1169
1170 .. method:: prepare(record)
1171
1172 Prepare a record for handling.
1173
1174 This implementation just returns the passed-in record. You may want to
1175 override this method if you need to do any custom marshalling or
1176 manipulation of the record before passing it to the handlers.
1177
1178 .. method:: handle(record)
1179
1180 Handle a record.
1181
1182 This just loops through the handlers offering them the record
1183 to handle. The actual object passed to the handlers is that which
1184 is returned from :meth:`prepare`.
1185
1186 .. method:: start()
1187
1188 Starts the listener.
1189
1190 This starts up a background thread to monitor the queue for
1191 LogRecords to process.
1192
1193 .. versionchanged:: 3.13.4
1194 Raises :exc:`RuntimeError` if called and the listener is already
1195 running.
1196
1197 .. method:: stop()
1198
1199 Stops the listener.
1200
1201 This asks the thread to terminate, and then waits for it to do so.
1202 Note that if you don't call this before your application exits, there
1203 may be some records still left on the queue, which won't be processed.
1204
1205 .. method:: enqueue_sentinel()
1206
1207 Writes a sentinel to the queue to tell the listener to quit. This
1208 implementation uses ``put_nowait()``. You may want to override this
1209 method if you want to use timeouts or work with custom queue
1210 implementations.
1211
1212 .. versionadded:: 3.3
1213
1214
1215 .. seealso::
1216
1217 Module :mod:`logging`
1218 API reference for the logging module.
1219
1220 Module :mod:`logging.config`
1221 Configuration API for the logging module.
1222
1223