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