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