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, timeout=None)
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 If *timeout* is specified, it sets a timeout (in seconds) for the socket operations.
639 This can help prevent the program from hanging indefinitely if the syslog server is
640 unreachable. By default, *timeout* is ``None``, meaning no timeout is applied.
641
642
643
644 Note that if your server is not listening on UDP port 514,
645 :class:`SysLogHandler` may appear not to work. In that case, check what
646 address you should be using for a domain socket - it's system dependent.
647 For example, on Linux it's usually '/dev/log' but on OS/X it's
648 '/var/run/syslog'. You'll need to check your platform and use the
649 appropriate address (you may need to do this check at runtime if your
650 application needs to run on several platforms). On Windows, you pretty
651 much have to use the UDP option.
652
653 .. note:: On macOS 12.x (Monterey), Apple has changed the behaviour of their
654 syslog daemon - it no longer listens on a domain socket. Therefore, you cannot
655 expect :class:`SysLogHandler` to work on this system.
656
657 See :gh:`91070` for more information.
658
659 .. versionchanged:: 3.2
660 *socktype* was added.
661
662 .. versionchanged:: 3.14
663 *timeout* was added.
664
665 .. method:: close()
666
667 Closes the socket to the remote host.
668
669 .. method:: createSocket()
670
671 Tries to create a socket and, if it's not a datagram socket, connect it
672 to the other end. This method is called during handler initialization,
673 but it's not regarded as an error if the other end isn't listening at
674 this point - the method will be called again when emitting an event, if
675 there is no socket at that point.
676
677 .. versionadded:: 3.11
678
679 .. method:: emit(record)
680
681 The record is formatted, and then sent to the syslog server. If exception
682 information is present, it is *not* sent to the server.
683
684 .. versionchanged:: 3.2.1
685 (See: :issue:`12168`.) In earlier versions, the message sent to the
686 syslog daemons was always terminated with a NUL byte, because early
687 versions of these daemons expected a NUL terminated message - even
688 though it's not in the relevant specification (:rfc:`5424`). More recent
689 versions of these daemons don't expect the NUL byte but strip it off
690 if it's there, and even more recent daemons (which adhere more closely
691 to RFC 5424) pass the NUL byte on as part of the message.
692
693 To enable easier handling of syslog messages in the face of all these
694 differing daemon behaviours, the appending of the NUL byte has been
695 made configurable, through the use of a class-level attribute,
696 ``append_nul``. This defaults to ``True`` (preserving the existing
697 behaviour) but can be set to ``False`` on a ``SysLogHandler`` instance
698 in order for that instance to *not* append the NUL terminator.
699
700 .. versionchanged:: 3.3
701 (See: :issue:`12419`.) In earlier versions, there was no facility for
702 an "ident" or "tag" prefix to identify the source of the message. This
703 can now be specified using a class-level attribute, defaulting to
704 ``""`` to preserve existing behaviour, but which can be overridden on
705 a ``SysLogHandler`` instance in order for that instance to prepend
706 the ident to every message handled. Note that the provided ident must
707 be text, not bytes, and is prepended to the message exactly as is.
708
709 .. method:: encodePriority(facility, priority)
710
711 Encodes the facility and priority into an integer. You can pass in strings
712 or integers - if strings are passed, internal mapping dictionaries are
713 used to convert them to integers.
714
715 The symbolic ``LOG_`` values are defined in :class:`SysLogHandler` and
716 mirror the values defined in the ``sys/syslog.h`` header file.
717
718 **Priorities**
719
720 +--------------------------+---------------+
721 | Name (string) | Symbolic value|
722 +==========================+===============+
723 | ``alert`` | LOG_ALERT |
724 +--------------------------+---------------+
725 | ``crit`` or ``critical`` | LOG_CRIT |
726 +--------------------------+---------------+
727 | ``debug`` | LOG_DEBUG |
728 +--------------------------+---------------+
729 | ``emerg`` or ``panic`` | LOG_EMERG |
730 +--------------------------+---------------+
731 | ``err`` or ``error`` | LOG_ERR |
732 +--------------------------+---------------+
733 | ``info`` | LOG_INFO |
734 +--------------------------+---------------+
735 | ``notice`` | LOG_NOTICE |
736 +--------------------------+---------------+
737 | ``warn`` or ``warning`` | LOG_WARNING |
738 +--------------------------+---------------+
739
740 **Facilities**
741
742 +---------------+---------------+
743 | Name (string) | Symbolic value|
744 +===============+===============+
745 | ``auth`` | LOG_AUTH |
746 +---------------+---------------+
747 | ``authpriv`` | LOG_AUTHPRIV |
748 +---------------+---------------+
749 | ``cron`` | LOG_CRON |
750 +---------------+---------------+
751 | ``daemon`` | LOG_DAEMON |
752 +---------------+---------------+
753 | ``ftp`` | LOG_FTP |
754 +---------------+---------------+
755 | ``kern`` | LOG_KERN |
756 +---------------+---------------+
757 | ``lpr`` | LOG_LPR |
758 +---------------+---------------+
759 | ``mail`` | LOG_MAIL |
760 +---------------+---------------+
761 | ``news`` | LOG_NEWS |
762 +---------------+---------------+
763 | ``syslog`` | LOG_SYSLOG |
764 +---------------+---------------+
765 | ``user`` | LOG_USER |
766 +---------------+---------------+
767 | ``uucp`` | LOG_UUCP |
768 +---------------+---------------+
769 | ``local0`` | LOG_LOCAL0 |
770 +---------------+---------------+
771 | ``local1`` | LOG_LOCAL1 |
772 +---------------+---------------+
773 | ``local2`` | LOG_LOCAL2 |
774 +---------------+---------------+
775 | ``local3`` | LOG_LOCAL3 |
776 +---------------+---------------+
777 | ``local4`` | LOG_LOCAL4 |
778 +---------------+---------------+
779 | ``local5`` | LOG_LOCAL5 |
780 +---------------+---------------+
781 | ``local6`` | LOG_LOCAL6 |
782 +---------------+---------------+
783 | ``local7`` | LOG_LOCAL7 |
784 +---------------+---------------+
785
786 .. method:: mapPriority(levelname)
787
788 Maps a logging level name to a syslog priority name.
789 You may need to override this if you are using custom levels, or
790 if the default algorithm is not suitable for your needs. The
791 default algorithm maps ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR`` and
792 ``CRITICAL`` to the equivalent syslog names, and all other level
793 names to 'warning'.
794
795 .. _nt-eventlog-handler:
796
797 NTEventLogHandler
798 ^^^^^^^^^^^^^^^^^
799
800 The :class:`NTEventLogHandler` class, located in the :mod:`!logging.handlers`
801 module, supports sending logging messages to a local Windows NT, Windows 2000 or
802 Windows XP event log. Before you can use it, you need Mark Hammond's Win32
803 extensions for Python installed.
804
805
806 .. class:: NTEventLogHandler(appname, dllname=None, logtype='Application')
807
808 Returns a new instance of the :class:`NTEventLogHandler` class. The *appname* is
809 used to define the application name as it appears in the event log. An
810 appropriate registry entry is created using this name. The *dllname* should give
811 the fully qualified pathname of a .dll or .exe which contains message
812 definitions to hold in the log (if not specified, ``'win32service.pyd'`` is used
813 - this is installed with the Win32 extensions and contains some basic
814 placeholder message definitions. Note that use of these placeholders will make
815 your event logs big, as the entire message source is held in the log. If you
816 want slimmer logs, you have to pass in the name of your own .dll or .exe which
817 contains the message definitions you want to use in the event log). The
818 *logtype* is one of ``'Application'``, ``'System'`` or ``'Security'``, and
819 defaults to ``'Application'``.
820
821
822 .. method:: close()
823
824 At this point, you can remove the application name from the registry as a
825 source of event log entries. However, if you do this, you will not be able
826 to see the events as you intended in the Event Log Viewer - it needs to be
827 able to access the registry to get the .dll name. The current version does
828 not do this.
829
830
831 .. method:: emit(record)
832
833 Determines the message ID, event category and event type, and then logs
834 the message in the NT event log.
835
836
837 .. method:: getEventCategory(record)
838
839 Returns the event category for the record. Override this if you want to
840 specify your own categories. This version returns 0.
841
842
843 .. method:: getEventType(record)
844
845 Returns the event type for the record. Override this if you want to
846 specify your own types. This version does a mapping using the handler's
847 typemap attribute, which is set up in :meth:`__init__` to a dictionary
848 which contains mappings for :const:`DEBUG`, :const:`INFO`,
849 :const:`WARNING`, :const:`ERROR` and :const:`CRITICAL`. If you are using
850 your own levels, you will either need to override this method or place a
851 suitable dictionary in the handler's *typemap* attribute.
852
853
854 .. method:: getMessageID(record)
855
856 Returns the message ID for the record. If you are using your own messages,
857 you could do this by having the *msg* passed to the logger being an ID
858 rather than a format string. Then, in here, you could use a dictionary
859 lookup to get the message ID. This version returns 1, which is the base
860 message ID in :file:`win32service.pyd`.
861
862 .. _smtp-handler:
863
864 SMTPHandler
865 ^^^^^^^^^^^
866
867 The :class:`SMTPHandler` class, located in the :mod:`!logging.handlers` module,
868 supports sending logging messages to an email address via SMTP.
869
870
871 .. class:: SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0)
872
873 Returns a new instance of the :class:`SMTPHandler` class. The instance is
874 initialized with the from and to addresses and subject line of the email. The
875 *toaddrs* should be a list of strings. To specify a non-standard SMTP port, use
876 the (host, port) tuple format for the *mailhost* argument. If you use a string,
877 the standard SMTP port is used. If your SMTP server requires authentication, you
878 can specify a (username, password) tuple for the *credentials* argument.
879
880 To specify the use of a secure protocol (TLS), pass in a tuple to the
881 *secure* argument. This will only be used when authentication credentials are
882 supplied. The tuple should be either an empty tuple, or a single-value tuple
883 with the name of a keyfile, or a 2-value tuple with the names of the keyfile
884 and certificate file. (This tuple is passed to the
885 :meth:`smtplib.SMTP.starttls` method.)
886
887 A timeout can be specified for communication with the SMTP server using the
888 *timeout* argument.
889
890 .. versionchanged:: 3.3
891 Added the *timeout* parameter.
892
893 .. method:: emit(record)
894
895 Formats the record and sends it to the specified addressees.
896
897
898 .. method:: getSubject(record)
899
900 If you want to specify a subject line which is record-dependent, override
901 this method.
902
903 .. _memory-handler:
904
905 MemoryHandler
906 ^^^^^^^^^^^^^
907
908 The :class:`MemoryHandler` class, located in the :mod:`!logging.handlers` module,
909 supports buffering of logging records in memory, periodically flushing them to a
910 :dfn:`target` handler. Flushing occurs whenever the buffer is full, or when an
911 event of a certain severity or greater is seen.
912
913 :class:`MemoryHandler` is a subclass of the more general
914 :class:`BufferingHandler`, which is an abstract class. This buffers logging
915 records in memory. Whenever each record is added to the buffer, a check is made
916 by calling :meth:`shouldFlush` to see if the buffer should be flushed. If it
917 should, then :meth:`flush` is expected to do the flushing.
918
919
920 .. class:: BufferingHandler(capacity)
921
922 Initializes the handler with a buffer of the specified capacity. Here,
923 *capacity* means the number of logging records buffered.
924
925
926 .. method:: emit(record)
927
928 Append the record to the buffer. If :meth:`shouldFlush` returns true,
929 call :meth:`flush` to process the buffer.
930
931
932 .. method:: flush()
933
934 For a :class:`BufferingHandler` instance, flushing means that it sets the
935 buffer to an empty list. This method can be overwritten to implement more useful
936 flushing behavior.
937
938
939 .. method:: shouldFlush(record)
940
941 Return ``True`` if the buffer is up to capacity. This method can be
942 overridden to implement custom flushing strategies.
943
944
945 .. class:: MemoryHandler(capacity, flushLevel=ERROR, target=None, flushOnClose=True)
946
947 Returns a new instance of the :class:`MemoryHandler` class. The instance is
948 initialized with a buffer size of *capacity* (number of records buffered).
949 If *flushLevel* is not specified, :const:`ERROR` is used. If no *target* is
950 specified, the target will need to be set using :meth:`setTarget` before this
951 handler does anything useful. If *flushOnClose* is specified as ``False``,
952 then the buffer is *not* flushed when the handler is closed. If not specified
953 or specified as ``True``, the previous behaviour of flushing the buffer will
954 occur when the handler is closed.
955
956 .. versionchanged:: 3.6
957 The *flushOnClose* parameter was added.
958
959
960 .. method:: close()
961
962 Calls :meth:`flush`, sets the target to ``None`` and clears the
963 buffer.
964
965
966 .. method:: flush()
967
968 For a :class:`MemoryHandler` instance, flushing means just sending the buffered
969 records to the target, if there is one. The buffer is also cleared when
970 buffered records are sent to the target. Override if you want different behavior.
971
972
973 .. method:: setTarget(target)
974
975 Sets the target handler for this handler.
976
977
978 .. method:: shouldFlush(record)
979
980 Checks for buffer full or a record at the *flushLevel* or higher.
981
982
983 .. _http-handler:
984
985 HTTPHandler
986 ^^^^^^^^^^^
987
988 The :class:`HTTPHandler` class, located in the :mod:`!logging.handlers` module,
989 supports sending logging messages to a web server, using either ``GET`` or
990 ``POST`` semantics.
991
992
993 .. class:: HTTPHandler(host, url, method='GET', secure=False, credentials=None, context=None)
994
995 Returns a new instance of the :class:`HTTPHandler` class. The *host* can be
996 of the form ``host:port``, should you need to use a specific port number. If
997 no *method* is specified, ``GET`` is used. If *secure* is true, a HTTPS
998 connection will be used. The *context* parameter may be set to a
999 :class:`ssl.SSLContext` instance to configure the SSL settings used for the
1000 HTTPS connection. If *credentials* is specified, it should be a 2-tuple
1001 consisting of userid and password, which will be placed in a HTTP
1002 'Authorization' header using Basic authentication. If you specify
1003 credentials, you should also specify secure=True so that your userid and
1004 password are not passed in cleartext across the wire.
1005
1006 .. versionchanged:: 3.5
1007 The *context* parameter was added.
1008
1009 .. method:: mapLogRecord(record)
1010
1011 Provides a dictionary, based on ``record``, which is to be URL-encoded
1012 and sent to the web server. The default implementation just returns
1013 ``record.__dict__``. This method can be overridden if e.g. only a
1014 subset of :class:`~logging.LogRecord` is to be sent to the web server, or
1015 if more specific customization of what's sent to the server is required.
1016
1017 .. method:: emit(record)
1018
1019 Sends the record to the web server as a URL-encoded dictionary. The
1020 :meth:`mapLogRecord` method is used to convert the record to the
1021 dictionary to be sent.
1022
1023 .. note:: Since preparing a record for sending it to a web server is not
1024 the same as a generic formatting operation, using
1025 :meth:`~logging.Handler.setFormatter` to specify a
1026 :class:`~logging.Formatter` for a :class:`HTTPHandler` has no effect.
1027 Instead of calling :meth:`~logging.Handler.format`, this handler calls
1028 :meth:`mapLogRecord` and then :func:`urllib.parse.urlencode` to encode the
1029 dictionary in a form suitable for sending to a web server.
1030
1031
1032 .. _queue-handler:
1033
1034
1035 QueueHandler
1036 ^^^^^^^^^^^^
1037
1038 .. versionadded:: 3.2
1039
1040 The :class:`QueueHandler` class, located in the :mod:`!logging.handlers` module,
1041 supports sending logging messages to a queue, such as those implemented in the
1042 :mod:`queue` or :mod:`multiprocessing` modules.
1043
1044 Along with the :class:`QueueListener` class, :class:`QueueHandler` can be used
1045 to let handlers do their work on a separate thread from the one which does the
1046 logging. This is important in web applications and also other service
1047 applications where threads servicing clients need to respond as quickly as
1048 possible, while any potentially slow operations (such as sending an email via
1049 :class:`SMTPHandler`) are done on a separate thread.
1050
1051 .. class:: QueueHandler(queue)
1052
1053 Returns a new instance of the :class:`QueueHandler` class. The instance is
1054 initialized with the queue to send messages to. The *queue* can be any
1055 queue-like object; it's used as-is by the :meth:`enqueue` method, which
1056 needs to know how to send messages to it. The queue is not *required* to
1057 have the task tracking API, which means that you can use
1058 :class:`~queue.SimpleQueue` instances for *queue*.
1059
1060 .. note:: If you are using :mod:`multiprocessing`, you should avoid using
1061 :class:`~queue.SimpleQueue` and instead use :class:`multiprocessing.Queue`.
1062
1063 .. warning::
1064
1065 The :mod:`multiprocessing` module uses an internal logger created and
1066 accessed via :meth:`~multiprocessing.get_logger`.
1067 :class:`multiprocessing.Queue` will log ``DEBUG`` level messages upon
1068 items being queued. If those log messages are processed by a
1069 :class:`QueueHandler` using the same :class:`multiprocessing.Queue` instance,
1070 it will cause a deadlock or infinite recursion.
1071
1072 .. method:: emit(record)
1073
1074 Enqueues the result of preparing the LogRecord. Should an exception
1075 occur (e.g. because a bounded queue has filled up), the
1076 :meth:`~logging.Handler.handleError` method is called to handle the
1077 error. This can result in the record silently being dropped (if
1078 :data:`logging.raiseExceptions` is ``False``) or a message printed to
1079 ``sys.stderr`` (if :data:`logging.raiseExceptions` is ``True``).
1080
1081 .. method:: prepare(record)
1082
1083 Prepares a record for queuing. The object returned by this
1084 method is enqueued.
1085
1086 The base implementation formats the record to merge the message,
1087 arguments, exception and stack information, if present. It also removes
1088 unpickleable items from the record in-place. Specifically, it overwrites
1089 the record's :attr:`msg` and :attr:`message` attributes with the merged
1090 message (obtained by calling the handler's :meth:`format` method), and
1091 sets the :attr:`args`, :attr:`exc_info` and :attr:`exc_text` attributes
1092 to ``None``.
1093
1094 You might want to override this method if you want to convert
1095 the record to a dict or JSON string, or send a modified copy
1096 of the record while leaving the original intact.
1097
1098 .. note:: The base implementation formats the message with arguments, sets
1099 the ``message`` and ``msg`` attributes to the formatted message and
1100 sets the ``args`` and ``exc_text`` attributes to ``None`` to allow
1101 pickling and to prevent further attempts at formatting. This means
1102 that a handler on the :class:`QueueListener` side won't have the
1103 information to do custom formatting, e.g. of exceptions. You may wish
1104 to subclass ``QueueHandler`` and override this method to e.g. avoid
1105 setting ``exc_text`` to ``None``. Note that the ``message`` / ``msg``
1106 / ``args`` changes are related to ensuring the record is pickleable,
1107 and you might or might not be able to avoid doing that depending on
1108 whether your ``args`` are pickleable. (Note that you may have to
1109 consider not only your own code but also code in any libraries that
1110 you use.)
1111
1112 .. method:: enqueue(record)
1113
1114 Enqueues the record on the queue using ``put_nowait()``; you may
1115 want to override this if you want to use blocking behaviour, or a
1116 timeout, or a customized queue implementation.
1117
1118 .. attribute:: listener
1119
1120 When created via configuration using :func:`~logging.config.dictConfig`, this
1121 attribute will contain a :class:`QueueListener` instance for use with this
1122 handler. Otherwise, it will be ``None``.
1123
1124 .. versionadded:: 3.12
1125
1126 .. _queue-listener:
1127
1128 QueueListener
1129 ^^^^^^^^^^^^^
1130
1131 .. versionadded:: 3.2
1132
1133 The :class:`QueueListener` class, located in the :mod:`!logging.handlers`
1134 module, supports receiving logging messages from a queue, such as those
1135 implemented in the :mod:`queue` or :mod:`multiprocessing` modules. The
1136 messages are received from a queue in an internal thread and passed, on
1137 the same thread, to one or more handlers for processing. While
1138 :class:`QueueListener` is not itself a handler, it is documented here
1139 because it works hand-in-hand with :class:`QueueHandler`.
1140
1141 Along with the :class:`QueueHandler` class, :class:`QueueListener` can be used
1142 to let handlers do their work on a separate thread from the one which does the
1143 logging. This is important in web applications and also other service
1144 applications where threads servicing clients need to respond as quickly as
1145 possible, while any potentially slow operations (such as sending an email via
1146 :class:`SMTPHandler`) are done on a separate thread.
1147
1148 .. class:: QueueListener(queue, *handlers, respect_handler_level=False)
1149
1150 Returns a new instance of the :class:`QueueListener` class. The instance is
1151 initialized with the queue to send messages to and a list of handlers which
1152 will handle entries placed on the queue. The queue can be any queue-like
1153 object; it's passed as-is to the :meth:`dequeue` method, which needs
1154 to know how to get messages from it. The queue is not *required* to have the
1155 task tracking API (though it's used if available), which means that you can
1156 use :class:`~queue.SimpleQueue` instances for *queue*.
1157
1158 .. note:: If you are using :mod:`multiprocessing`, you should avoid using
1159 :class:`~queue.SimpleQueue` and instead use :class:`multiprocessing.Queue`.
1160
1161 If ``respect_handler_level`` is ``True``, a handler's level is respected
1162 (compared with the level for the message) when deciding whether to pass
1163 messages to that handler; otherwise, the behaviour is as in previous Python
1164 versions - to always pass each message to each handler.
1165
1166 .. versionchanged:: 3.5
1167 The ``respect_handler_level`` argument was added.
1168
1169 .. versionchanged:: 3.14
1170 :class:`QueueListener` can now be used as a context manager via
1171 :keyword:`with`. When entering the context, the listener is started. When
1172 exiting the context, the listener is stopped.
1173 :meth:`~contextmanager.__enter__` returns the
1174 :class:`QueueListener` object.
1175
1176 .. method:: dequeue(block)
1177
1178 Dequeues a record and return it, optionally blocking.
1179
1180 The base implementation uses ``get()``. You may want to override this
1181 method if you want to use timeouts or work with custom queue
1182 implementations.
1183
1184 .. method:: prepare(record)
1185
1186 Prepare a record for handling.
1187
1188 This implementation just returns the passed-in record. You may want to
1189 override this method if you need to do any custom marshalling or
1190 manipulation of the record before passing it to the handlers.
1191
1192 .. method:: handle(record)
1193
1194 Handle a record.
1195
1196 This just loops through the handlers offering them the record
1197 to handle. The actual object passed to the handlers is that which
1198 is returned from :meth:`prepare`.
1199
1200 .. method:: start()
1201
1202 Starts the listener.
1203
1204 This starts up a background thread to monitor the queue for
1205 LogRecords to process.
1206
1207 .. versionchanged:: 3.14
1208 Raises :exc:`RuntimeError` if called and the listener is already
1209 running.
1210
1211 .. method:: stop()
1212
1213 Stops the listener.
1214
1215 This asks the thread to terminate, and then waits for it to do so.
1216 Note that if you don't call this before your application exits, there
1217 may be some records still left on the queue, which won't be processed.
1218
1219 .. method:: enqueue_sentinel()
1220
1221 Writes a sentinel to the queue to tell the listener to quit. This
1222 implementation uses ``put_nowait()``. You may want to override this
1223 method if you want to use timeouts or work with custom queue
1224 implementations.
1225
1226 .. versionadded:: 3.3
1227
1228
1229 .. seealso::
1230
1231 Module :mod:`logging`
1232 API reference for the logging module.
1233
1234 Module :mod:`logging.config`
1235 Configuration API for the logging module.
1236
1237