blob: 82e396903e21b61fcc68a4770648a705eca746c8 [file] [log] [blame]
Vinay Sajipc63619b2010-12-19 12:56:57 +00001:mod:`logging.handlers` --- Logging handlers
2============================================
3
4.. module:: logging.handlers
5 :synopsis: Handlers for the logging module.
6
7
8.. moduleauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
9.. sectionauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
10
Vinay Sajip01094e12010-12-19 13:41:26 +000011.. sidebar:: Important
12
13 This page contains only reference information. For tutorials,
14 please see
15
16 * :ref:`Basic Tutorial <logging-basic-tutorial>`
17 * :ref:`Advanced Tutorial <logging-advanced-tutorial>`
18 * :ref:`Logging Cookbook <logging-cookbook>`
Vinay Sajipc63619b2010-12-19 12:56:57 +000019
20.. currentmodule:: logging
21
Vinay Sajip01094e12010-12-19 13:41:26 +000022The following useful handlers are provided in the package. Note that three of
23the handlers (:class:`StreamHandler`, :class:`FileHandler` and
24:class:`NullHandler`) are actually defined in the :mod:`logging` module itself,
25but have been documented here along with the other handlers.
26
Vinay Sajipc63619b2010-12-19 12:56:57 +000027.. _stream-handler:
28
29StreamHandler
30^^^^^^^^^^^^^
31
32The :class:`StreamHandler` class, located in the core :mod:`logging` package,
33sends logging output to streams such as *sys.stdout*, *sys.stderr* or any
34file-like object (or, more precisely, any object which supports :meth:`write`
35and :meth:`flush` methods).
36
37
38.. class:: StreamHandler(stream=None)
39
40 Returns a new instance of the :class:`StreamHandler` class. If *stream* is
41 specified, the instance will use it for logging output; otherwise, *sys.stderr*
42 will be used.
43
44
45 .. method:: emit(record)
46
47 If a formatter is specified, it is used to format the record. The record
Vinay Sajip689b68a2010-12-22 15:04:15 +000048 is then written to the stream with a terminator. If exception information
49 is present, it is formatted using :func:`traceback.print_exception` and
50 appended to the stream.
Vinay Sajipc63619b2010-12-19 12:56:57 +000051
52
53 .. method:: flush()
54
55 Flushes the stream by calling its :meth:`flush` method. Note that the
56 :meth:`close` method is inherited from :class:`Handler` and so does
57 no output, so an explicit :meth:`flush` call may be needed at times.
58
59.. versionchanged:: 3.2
60 The ``StreamHandler`` class now has a ``terminator`` attribute, default
61 value ``'\n'``, which is used as the terminator when writing a formatted
62 record to a stream. If you don't want this newline termination, you can
63 set the handler instance's ``terminator`` attribute to the empty string.
Vinay Sajip689b68a2010-12-22 15:04:15 +000064 In earlier versions, the terminator was hardcoded as ``'\n'``.
Vinay Sajipc63619b2010-12-19 12:56:57 +000065
66.. _file-handler:
67
68FileHandler
69^^^^^^^^^^^
70
71The :class:`FileHandler` class, located in the core :mod:`logging` package,
72sends logging output to a disk file. It inherits the output functionality from
73:class:`StreamHandler`.
74
75
76.. class:: FileHandler(filename, mode='a', encoding=None, delay=False)
77
78 Returns a new instance of the :class:`FileHandler` class. The specified file is
79 opened and used as the stream for logging. If *mode* is not specified,
80 :const:`'a'` is used. If *encoding* is not *None*, it is used to open the file
81 with that encoding. If *delay* is true, then file opening is deferred until the
82 first call to :meth:`emit`. By default, the file grows indefinitely.
83
84
85 .. method:: close()
86
87 Closes the file.
88
89
90 .. method:: emit(record)
91
92 Outputs the record to the file.
93
94
95.. _null-handler:
96
97NullHandler
98^^^^^^^^^^^
99
100.. versionadded:: 3.1
101
102The :class:`NullHandler` class, located in the core :mod:`logging` package,
103does not do any formatting or output. It is essentially a 'no-op' handler
104for use by library developers.
105
106.. class:: NullHandler()
107
108 Returns a new instance of the :class:`NullHandler` class.
109
110 .. method:: emit(record)
111
112 This method does nothing.
113
114 .. method:: handle(record)
115
116 This method does nothing.
117
118 .. method:: createLock()
119
120 This method returns ``None`` for the lock, since there is no
121 underlying I/O to which access needs to be serialized.
122
123
124See :ref:`library-config` for more information on how to use
125:class:`NullHandler`.
126
127.. _watched-file-handler:
128
129WatchedFileHandler
130^^^^^^^^^^^^^^^^^^
131
132.. currentmodule:: logging.handlers
133
134The :class:`WatchedFileHandler` class, located in the :mod:`logging.handlers`
135module, is a :class:`FileHandler` which watches the file it is logging to. If
136the file changes, it is closed and reopened using the file name.
137
138A file change can happen because of usage of programs such as *newsyslog* and
139*logrotate* which perform log file rotation. This handler, intended for use
140under Unix/Linux, watches the file to see if it has changed since the last emit.
141(A file is deemed to have changed if its device or inode have changed.) If the
142file has changed, the old file stream is closed, and the file opened to get a
143new stream.
144
145This handler is not appropriate for use under Windows, because under Windows
146open log files cannot be moved or renamed - logging opens the files with
147exclusive locks - and so there is no need for such a handler. Furthermore,
148*ST_INO* is not supported under Windows; :func:`stat` always returns zero for
149this value.
150
151
152.. class:: WatchedFileHandler(filename[,mode[, encoding[, delay]]])
153
154 Returns a new instance of the :class:`WatchedFileHandler` class. The specified
155 file is opened and used as the stream for logging. If *mode* is not specified,
156 :const:`'a'` is used. If *encoding* is not *None*, it is used to open the file
157 with that encoding. If *delay* is true, then file opening is deferred until the
158 first call to :meth:`emit`. By default, the file grows indefinitely.
159
160
161 .. method:: emit(record)
162
163 Outputs the record to the file, but first checks to see if the file has
164 changed. If it has, the existing stream is flushed and closed and the
165 file opened again, before outputting the record to the file.
166
167.. _rotating-file-handler:
168
169RotatingFileHandler
170^^^^^^^^^^^^^^^^^^^
171
172The :class:`RotatingFileHandler` class, located in the :mod:`logging.handlers`
173module, supports rotation of disk log files.
174
175
176.. class:: RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=0)
177
178 Returns a new instance of the :class:`RotatingFileHandler` class. The specified
179 file is opened and used as the stream for logging. If *mode* is not specified,
180 ``'a'`` is used. If *encoding* is not *None*, it is used to open the file
181 with that encoding. If *delay* is true, then file opening is deferred until the
182 first call to :meth:`emit`. By default, the file grows indefinitely.
183
184 You can use the *maxBytes* and *backupCount* values to allow the file to
185 :dfn:`rollover` at a predetermined size. When the size is about to be exceeded,
186 the file is closed and a new file is silently opened for output. Rollover occurs
187 whenever the current log file is nearly *maxBytes* in length; if *maxBytes* is
188 zero, rollover never occurs. If *backupCount* is non-zero, the system will save
189 old log files by appending the extensions '.1', '.2' etc., to the filename. For
190 example, with a *backupCount* of 5 and a base file name of :file:`app.log`, you
191 would get :file:`app.log`, :file:`app.log.1`, :file:`app.log.2`, up to
192 :file:`app.log.5`. The file being written to is always :file:`app.log`. When
193 this file is filled, it is closed and renamed to :file:`app.log.1`, and if files
194 :file:`app.log.1`, :file:`app.log.2`, etc. exist, then they are renamed to
195 :file:`app.log.2`, :file:`app.log.3` etc. respectively.
196
197
198 .. method:: doRollover()
199
200 Does a rollover, as described above.
201
202
203 .. method:: emit(record)
204
205 Outputs the record to the file, catering for rollover as described
206 previously.
207
208.. _timed-rotating-file-handler:
209
210TimedRotatingFileHandler
211^^^^^^^^^^^^^^^^^^^^^^^^
212
213The :class:`TimedRotatingFileHandler` class, located in the
214:mod:`logging.handlers` module, supports rotation of disk log files at certain
215timed intervals.
216
217
218.. class:: TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False)
219
220 Returns a new instance of the :class:`TimedRotatingFileHandler` class. The
221 specified file is opened and used as the stream for logging. On rotating it also
222 sets the filename suffix. Rotating happens based on the product of *when* and
223 *interval*.
224
225 You can use the *when* to specify the type of *interval*. The list of possible
226 values is below. Note that they are not case sensitive.
227
228 +----------------+-----------------------+
229 | Value | Type of interval |
230 +================+=======================+
231 | ``'S'`` | Seconds |
232 +----------------+-----------------------+
233 | ``'M'`` | Minutes |
234 +----------------+-----------------------+
235 | ``'H'`` | Hours |
236 +----------------+-----------------------+
237 | ``'D'`` | Days |
238 +----------------+-----------------------+
239 | ``'W'`` | Week day (0=Monday) |
240 +----------------+-----------------------+
241 | ``'midnight'`` | Roll over at midnight |
242 +----------------+-----------------------+
243
244 The system will save old log files by appending extensions to the filename.
245 The extensions are date-and-time based, using the strftime format
246 ``%Y-%m-%d_%H-%M-%S`` or a leading portion thereof, depending on the
247 rollover interval.
248
249 When computing the next rollover time for the first time (when the handler
250 is created), the last modification time of an existing log file, or else
251 the current time, is used to compute when the next rotation will occur.
252
253 If the *utc* argument is true, times in UTC will be used; otherwise
254 local time is used.
255
256 If *backupCount* is nonzero, at most *backupCount* files
257 will be kept, and if more would be created when rollover occurs, the oldest
258 one is deleted. The deletion logic uses the interval to determine which
259 files to delete, so changing the interval may leave old files lying around.
260
261 If *delay* is true, then file opening is deferred until the first call to
262 :meth:`emit`.
263
264
265 .. method:: doRollover()
266
267 Does a rollover, as described above.
268
269
270 .. method:: emit(record)
271
272 Outputs the record to the file, catering for rollover as described above.
273
274
275.. _socket-handler:
276
277SocketHandler
278^^^^^^^^^^^^^
279
280The :class:`SocketHandler` class, located in the :mod:`logging.handlers` module,
281sends logging output to a network socket. The base class uses a TCP socket.
282
283
284.. class:: SocketHandler(host, port)
285
286 Returns a new instance of the :class:`SocketHandler` class intended to
287 communicate with a remote machine whose address is given by *host* and *port*.
288
289
290 .. method:: close()
291
292 Closes the socket.
293
294
295 .. method:: emit()
296
297 Pickles the record's attribute dictionary and writes it to the socket in
298 binary format. If there is an error with the socket, silently drops the
299 packet. If the connection was previously lost, re-establishes the
300 connection. To unpickle the record at the receiving end into a
301 :class:`LogRecord`, use the :func:`makeLogRecord` function.
302
303
304 .. method:: handleError()
305
306 Handles an error which has occurred during :meth:`emit`. The most likely
307 cause is a lost connection. Closes the socket so that we can retry on the
308 next event.
309
310
311 .. method:: makeSocket()
312
313 This is a factory method which allows subclasses to define the precise
314 type of socket they want. The default implementation creates a TCP socket
315 (:const:`socket.SOCK_STREAM`).
316
317
318 .. method:: makePickle(record)
319
320 Pickles the record's attribute dictionary in binary format with a length
321 prefix, and returns it ready for transmission across the socket.
322
323 Note that pickles aren't completely secure. If you are concerned about
324 security, you may want to override this method to implement a more secure
325 mechanism. For example, you can sign pickles using HMAC and then verify
326 them on the receiving end, or alternatively you can disable unpickling of
327 global objects on the receiving end.
328
Georg Brandl08e278a2011-02-15 12:44:43 +0000329
Vinay Sajipc63619b2010-12-19 12:56:57 +0000330 .. method:: send(packet)
331
332 Send a pickled string *packet* to the socket. This function allows for
333 partial sends which can happen when the network is busy.
334
Georg Brandl08e278a2011-02-15 12:44:43 +0000335
Georg Brandldbb95852011-02-15 12:41:17 +0000336 .. method:: createSocket()
337
338 Tries to create a socket; on failure, uses an exponential back-off
339 algorithm. On intial failure, the handler will drop the message it was
340 trying to send. When subsequent messages are handled by the same
341 instance, it will not try connecting until some time has passed. The
342 default parameters are such that the initial delay is one second, and if
343 after that delay the connection still can't be made, the handler will
344 double the delay each time up to a maximum of 30 seconds.
345
346 This behaviour is controlled by the following handler attributes:
347
348 * ``retryStart`` (initial delay, defaulting to 1.0 seconds).
349 * ``retryFactor`` (multiplier, defaulting to 2.0).
350 * ``retryMax`` (maximum delay, defaulting to 30.0 seconds).
351
352 This means that if the remote listener starts up *after* the handler has
353 been used, you could lose messages (since the handler won't even attempt
354 a connection until the delay has elapsed, but just silently drop messages
355 during the delay period).
Georg Brandl08e278a2011-02-15 12:44:43 +0000356
Vinay Sajipc63619b2010-12-19 12:56:57 +0000357
358.. _datagram-handler:
359
360DatagramHandler
361^^^^^^^^^^^^^^^
362
363The :class:`DatagramHandler` class, located in the :mod:`logging.handlers`
364module, inherits from :class:`SocketHandler` to support sending logging messages
365over UDP sockets.
366
367
368.. class:: DatagramHandler(host, port)
369
370 Returns a new instance of the :class:`DatagramHandler` class intended to
371 communicate with a remote machine whose address is given by *host* and *port*.
372
373
374 .. method:: emit()
375
376 Pickles the record's attribute dictionary and writes it to the socket in
377 binary format. If there is an error with the socket, silently drops the
378 packet. To unpickle the record at the receiving end into a
379 :class:`LogRecord`, use the :func:`makeLogRecord` function.
380
381
382 .. method:: makeSocket()
383
384 The factory method of :class:`SocketHandler` is here overridden to create
385 a UDP socket (:const:`socket.SOCK_DGRAM`).
386
387
388 .. method:: send(s)
389
390 Send a pickled string to a socket.
391
392
393.. _syslog-handler:
394
395SysLogHandler
396^^^^^^^^^^^^^
397
398The :class:`SysLogHandler` class, located in the :mod:`logging.handlers` module,
399supports sending logging messages to a remote or local Unix syslog.
400
401
402.. class:: SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM)
403
404 Returns a new instance of the :class:`SysLogHandler` class intended to
405 communicate with a remote Unix machine whose address is given by *address* in
406 the form of a ``(host, port)`` tuple. If *address* is not specified,
407 ``('localhost', 514)`` is used. The address is used to open a socket. An
408 alternative to providing a ``(host, port)`` tuple is providing an address as a
409 string, for example '/dev/log'. In this case, a Unix domain socket is used to
410 send the message to the syslog. If *facility* is not specified,
411 :const:`LOG_USER` is used. The type of socket opened depends on the
412 *socktype* argument, which defaults to :const:`socket.SOCK_DGRAM` and thus
413 opens a UDP socket. To open a TCP socket (for use with the newer syslog
414 daemons such as rsyslog), specify a value of :const:`socket.SOCK_STREAM`.
415
416 Note that if your server is not listening on UDP port 514,
417 :class:`SysLogHandler` may appear not to work. In that case, check what
418 address you should be using for a domain socket - it's system dependent.
419 For example, on Linux it's usually '/dev/log' but on OS/X it's
420 '/var/run/syslog'. You'll need to check your platform and use the
421 appropriate address (you may need to do this check at runtime if your
422 application needs to run on several platforms). On Windows, you pretty
423 much have to use the UDP option.
424
425 .. versionchanged:: 3.2
426 *socktype* was added.
427
428
429 .. method:: close()
430
431 Closes the socket to the remote host.
432
433
434 .. method:: emit(record)
435
436 The record is formatted, and then sent to the syslog server. If exception
437 information is present, it is *not* sent to the server.
438
Vinay Sajip645e4582011-06-10 18:52:50 +0100439 .. versionchanged:: 3.2.1
440 (See: :issue:`12168`.) In earlier versions, the message sent to the
441 syslog daemons was always terminated with a NUL byte, because early
442 versions of these daemons expected a NUL terminated message - even
443 though it's not in the relevant specification (RF 5424). More recent
444 versions of these daemons don't expect the NUL byte but strip it off
445 if it's there, and even more recent daemons (which adhere more closely
446 to RFC 5424) pass the NUL byte on as part of the message.
447
448 To enable easier handling of syslog messages in the face of all these
449 differing daemon behaviours, the appending of the NUL byte has been
450 made configurable, through the use of a class-level attribute,
451 ``append_nul``. This defaults to ``True`` (preserving the existing
452 behaviour) but can be set to ``False`` on a ``SysLogHandler`` instance
453 in order for that instance to *not* append the NUL terminator.
Vinay Sajipc63619b2010-12-19 12:56:57 +0000454
Vinay Sajip2353e352011-06-27 15:40:06 +0100455 .. versionchanged:: 3.3
456 (See: :issue:`12419`.) In earlier versions, there was no facility for
457 an "ident" or "tag" prefix to identify the source of the message. This
458 can now be specified using a class-level attribute, defaulting to
459 ``""`` to preserve existing behaviour, but which can be overridden on
460 a ``SysLogHandler`` instance in order for that instance to prepend
461 the ident to every message handled. Note that the provided ident must
462 be text, not bytes, and is prepended to the message exactly as is.
463
Vinay Sajipc63619b2010-12-19 12:56:57 +0000464 .. method:: encodePriority(facility, priority)
465
466 Encodes the facility and priority into an integer. You can pass in strings
467 or integers - if strings are passed, internal mapping dictionaries are
468 used to convert them to integers.
469
470 The symbolic ``LOG_`` values are defined in :class:`SysLogHandler` and
471 mirror the values defined in the ``sys/syslog.h`` header file.
472
473 **Priorities**
474
475 +--------------------------+---------------+
476 | Name (string) | Symbolic value|
477 +==========================+===============+
478 | ``alert`` | LOG_ALERT |
479 +--------------------------+---------------+
480 | ``crit`` or ``critical`` | LOG_CRIT |
481 +--------------------------+---------------+
482 | ``debug`` | LOG_DEBUG |
483 +--------------------------+---------------+
484 | ``emerg`` or ``panic`` | LOG_EMERG |
485 +--------------------------+---------------+
486 | ``err`` or ``error`` | LOG_ERR |
487 +--------------------------+---------------+
488 | ``info`` | LOG_INFO |
489 +--------------------------+---------------+
490 | ``notice`` | LOG_NOTICE |
491 +--------------------------+---------------+
492 | ``warn`` or ``warning`` | LOG_WARNING |
493 +--------------------------+---------------+
494
495 **Facilities**
496
497 +---------------+---------------+
498 | Name (string) | Symbolic value|
499 +===============+===============+
500 | ``auth`` | LOG_AUTH |
501 +---------------+---------------+
502 | ``authpriv`` | LOG_AUTHPRIV |
503 +---------------+---------------+
504 | ``cron`` | LOG_CRON |
505 +---------------+---------------+
506 | ``daemon`` | LOG_DAEMON |
507 +---------------+---------------+
508 | ``ftp`` | LOG_FTP |
509 +---------------+---------------+
510 | ``kern`` | LOG_KERN |
511 +---------------+---------------+
512 | ``lpr`` | LOG_LPR |
513 +---------------+---------------+
514 | ``mail`` | LOG_MAIL |
515 +---------------+---------------+
516 | ``news`` | LOG_NEWS |
517 +---------------+---------------+
518 | ``syslog`` | LOG_SYSLOG |
519 +---------------+---------------+
520 | ``user`` | LOG_USER |
521 +---------------+---------------+
522 | ``uucp`` | LOG_UUCP |
523 +---------------+---------------+
524 | ``local0`` | LOG_LOCAL0 |
525 +---------------+---------------+
526 | ``local1`` | LOG_LOCAL1 |
527 +---------------+---------------+
528 | ``local2`` | LOG_LOCAL2 |
529 +---------------+---------------+
530 | ``local3`` | LOG_LOCAL3 |
531 +---------------+---------------+
532 | ``local4`` | LOG_LOCAL4 |
533 +---------------+---------------+
534 | ``local5`` | LOG_LOCAL5 |
535 +---------------+---------------+
536 | ``local6`` | LOG_LOCAL6 |
537 +---------------+---------------+
538 | ``local7`` | LOG_LOCAL7 |
539 +---------------+---------------+
540
541 .. method:: mapPriority(levelname)
542
543 Maps a logging level name to a syslog priority name.
544 You may need to override this if you are using custom levels, or
545 if the default algorithm is not suitable for your needs. The
546 default algorithm maps ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR`` and
547 ``CRITICAL`` to the equivalent syslog names, and all other level
548 names to 'warning'.
549
550.. _nt-eventlog-handler:
551
552NTEventLogHandler
553^^^^^^^^^^^^^^^^^
554
555The :class:`NTEventLogHandler` class, located in the :mod:`logging.handlers`
556module, supports sending logging messages to a local Windows NT, Windows 2000 or
557Windows XP event log. Before you can use it, you need Mark Hammond's Win32
558extensions for Python installed.
559
560
561.. class:: NTEventLogHandler(appname, dllname=None, logtype='Application')
562
563 Returns a new instance of the :class:`NTEventLogHandler` class. The *appname* is
564 used to define the application name as it appears in the event log. An
565 appropriate registry entry is created using this name. The *dllname* should give
566 the fully qualified pathname of a .dll or .exe which contains message
567 definitions to hold in the log (if not specified, ``'win32service.pyd'`` is used
568 - this is installed with the Win32 extensions and contains some basic
569 placeholder message definitions. Note that use of these placeholders will make
570 your event logs big, as the entire message source is held in the log. If you
571 want slimmer logs, you have to pass in the name of your own .dll or .exe which
572 contains the message definitions you want to use in the event log). The
573 *logtype* is one of ``'Application'``, ``'System'`` or ``'Security'``, and
574 defaults to ``'Application'``.
575
576
577 .. method:: close()
578
579 At this point, you can remove the application name from the registry as a
580 source of event log entries. However, if you do this, you will not be able
581 to see the events as you intended in the Event Log Viewer - it needs to be
582 able to access the registry to get the .dll name. The current version does
583 not do this.
584
585
586 .. method:: emit(record)
587
588 Determines the message ID, event category and event type, and then logs
589 the message in the NT event log.
590
591
592 .. method:: getEventCategory(record)
593
594 Returns the event category for the record. Override this if you want to
595 specify your own categories. This version returns 0.
596
597
598 .. method:: getEventType(record)
599
600 Returns the event type for the record. Override this if you want to
601 specify your own types. This version does a mapping using the handler's
602 typemap attribute, which is set up in :meth:`__init__` to a dictionary
603 which contains mappings for :const:`DEBUG`, :const:`INFO`,
604 :const:`WARNING`, :const:`ERROR` and :const:`CRITICAL`. If you are using
605 your own levels, you will either need to override this method or place a
606 suitable dictionary in the handler's *typemap* attribute.
607
608
609 .. method:: getMessageID(record)
610
611 Returns the message ID for the record. If you are using your own messages,
612 you could do this by having the *msg* passed to the logger being an ID
613 rather than a format string. Then, in here, you could use a dictionary
614 lookup to get the message ID. This version returns 1, which is the base
615 message ID in :file:`win32service.pyd`.
616
617.. _smtp-handler:
618
619SMTPHandler
620^^^^^^^^^^^
621
622The :class:`SMTPHandler` class, located in the :mod:`logging.handlers` module,
623supports sending logging messages to an email address via SMTP.
624
625
626.. class:: SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None)
627
628 Returns a new instance of the :class:`SMTPHandler` class. The instance is
629 initialized with the from and to addresses and subject line of the email. The
630 *toaddrs* should be a list of strings. To specify a non-standard SMTP port, use
631 the (host, port) tuple format for the *mailhost* argument. If you use a string,
632 the standard SMTP port is used. If your SMTP server requires authentication, you
633 can specify a (username, password) tuple for the *credentials* argument.
634
635
636 .. method:: emit(record)
637
638 Formats the record and sends it to the specified addressees.
639
640
641 .. method:: getSubject(record)
642
643 If you want to specify a subject line which is record-dependent, override
644 this method.
645
646.. _memory-handler:
647
648MemoryHandler
649^^^^^^^^^^^^^
650
651The :class:`MemoryHandler` class, located in the :mod:`logging.handlers` module,
652supports buffering of logging records in memory, periodically flushing them to a
653:dfn:`target` handler. Flushing occurs whenever the buffer is full, or when an
654event of a certain severity or greater is seen.
655
656:class:`MemoryHandler` is a subclass of the more general
657:class:`BufferingHandler`, which is an abstract class. This buffers logging
658records in memory. Whenever each record is added to the buffer, a check is made
659by calling :meth:`shouldFlush` to see if the buffer should be flushed. If it
660should, then :meth:`flush` is expected to do the needful.
661
662
663.. class:: BufferingHandler(capacity)
664
665 Initializes the handler with a buffer of the specified capacity.
666
667
668 .. method:: emit(record)
669
670 Appends the record to the buffer. If :meth:`shouldFlush` returns true,
671 calls :meth:`flush` to process the buffer.
672
673
674 .. method:: flush()
675
676 You can override this to implement custom flushing behavior. This version
677 just zaps the buffer to empty.
678
679
680 .. method:: shouldFlush(record)
681
682 Returns true if the buffer is up to capacity. This method can be
683 overridden to implement custom flushing strategies.
684
685
686.. class:: MemoryHandler(capacity, flushLevel=ERROR, target=None)
687
688 Returns a new instance of the :class:`MemoryHandler` class. The instance is
689 initialized with a buffer size of *capacity*. If *flushLevel* is not specified,
690 :const:`ERROR` is used. If no *target* is specified, the target will need to be
691 set using :meth:`setTarget` before this handler does anything useful.
692
693
694 .. method:: close()
695
696 Calls :meth:`flush`, sets the target to :const:`None` and clears the
697 buffer.
698
699
700 .. method:: flush()
701
702 For a :class:`MemoryHandler`, flushing means just sending the buffered
703 records to the target, if there is one. The buffer is also cleared when
704 this happens. Override if you want different behavior.
705
706
707 .. method:: setTarget(target)
708
709 Sets the target handler for this handler.
710
711
712 .. method:: shouldFlush(record)
713
714 Checks for buffer full or a record at the *flushLevel* or higher.
715
716
717.. _http-handler:
718
719HTTPHandler
720^^^^^^^^^^^
721
722The :class:`HTTPHandler` class, located in the :mod:`logging.handlers` module,
723supports sending logging messages to a Web server, using either ``GET`` or
724``POST`` semantics.
725
726
727.. class:: HTTPHandler(host, url, method='GET', secure=False, credentials=None)
728
729 Returns a new instance of the :class:`HTTPHandler` class. The *host* can be
730 of the form ``host:port``, should you need to use a specific port number.
731 If no *method* is specified, ``GET`` is used. If *secure* is True, an HTTPS
732 connection will be used. If *credentials* is specified, it should be a
733 2-tuple consisting of userid and password, which will be placed in an HTTP
734 'Authorization' header using Basic authentication. If you specify
735 credentials, you should also specify secure=True so that your userid and
736 password are not passed in cleartext across the wire.
737
738
739 .. method:: emit(record)
740
741 Sends the record to the Web server as a percent-encoded dictionary.
742
743
744.. _queue-handler:
745
746
747QueueHandler
748^^^^^^^^^^^^
749
750.. versionadded:: 3.2
751
752The :class:`QueueHandler` class, located in the :mod:`logging.handlers` module,
753supports sending logging messages to a queue, such as those implemented in the
754:mod:`queue` or :mod:`multiprocessing` modules.
755
756Along with the :class:`QueueListener` class, :class:`QueueHandler` can be used
757to let handlers do their work on a separate thread from the one which does the
758logging. This is important in Web applications and also other service
759applications where threads servicing clients need to respond as quickly as
760possible, while any potentially slow operations (such as sending an email via
761:class:`SMTPHandler`) are done on a separate thread.
762
763.. class:: QueueHandler(queue)
764
765 Returns a new instance of the :class:`QueueHandler` class. The instance is
766 initialized with the queue to send messages to. The queue can be any queue-
767 like object; it's used as-is by the :meth:`enqueue` method, which needs
768 to know how to send messages to it.
769
770
771 .. method:: emit(record)
772
773 Enqueues the result of preparing the LogRecord.
774
775 .. method:: prepare(record)
776
777 Prepares a record for queuing. The object returned by this
778 method is enqueued.
779
780 The base implementation formats the record to merge the message
781 and arguments, and removes unpickleable items from the record
782 in-place.
783
784 You might want to override this method if you want to convert
785 the record to a dict or JSON string, or send a modified copy
786 of the record while leaving the original intact.
787
788 .. method:: enqueue(record)
789
790 Enqueues the record on the queue using ``put_nowait()``; you may
791 want to override this if you want to use blocking behaviour, or a
792 timeout, or a customised queue implementation.
793
794
795
796.. queue-listener:
797
798QueueListener
799^^^^^^^^^^^^^
800
801.. versionadded:: 3.2
802
803The :class:`QueueListener` class, located in the :mod:`logging.handlers`
804module, supports receiving logging messages from a queue, such as those
805implemented in the :mod:`queue` or :mod:`multiprocessing` modules. The
806messages are received from a queue in an internal thread and passed, on
807the same thread, to one or more handlers for processing. While
808:class:`QueueListener` is not itself a handler, it is documented here
809because it works hand-in-hand with :class:`QueueHandler`.
810
811Along with the :class:`QueueHandler` class, :class:`QueueListener` can be used
812to let handlers do their work on a separate thread from the one which does the
813logging. This is important in Web applications and also other service
814applications where threads servicing clients need to respond as quickly as
815possible, while any potentially slow operations (such as sending an email via
816:class:`SMTPHandler`) are done on a separate thread.
817
818.. class:: QueueListener(queue, *handlers)
819
820 Returns a new instance of the :class:`QueueListener` class. The instance is
821 initialized with the queue to send messages to and a list of handlers which
822 will handle entries placed on the queue. The queue can be any queue-
823 like object; it's passed as-is to the :meth:`dequeue` method, which needs
824 to know how to get messages from it.
825
826 .. method:: dequeue(block)
827
828 Dequeues a record and return it, optionally blocking.
829
830 The base implementation uses ``get()``. You may want to override this
831 method if you want to use timeouts or work with custom queue
832 implementations.
833
834 .. method:: prepare(record)
835
836 Prepare a record for handling.
837
838 This implementation just returns the passed-in record. You may want to
839 override this method if you need to do any custom marshalling or
840 manipulation of the record before passing it to the handlers.
841
842 .. method:: handle(record)
843
844 Handle a record.
845
846 This just loops through the handlers offering them the record
847 to handle. The actual object passed to the handlers is that which
848 is returned from :meth:`prepare`.
849
850 .. method:: start()
851
852 Starts the listener.
853
854 This starts up a background thread to monitor the queue for
855 LogRecords to process.
856
857 .. method:: stop()
858
859 Stops the listener.
860
861 This asks the thread to terminate, and then waits for it to do so.
862 Note that if you don't call this before your application exits, there
863 may be some records still left on the queue, which won't be processed.
864
Vinay Sajipa29a9dd2011-02-25 16:05:26 +0000865 .. method:: enqueue_sentinel()
866
867 Writes a sentinel to the queue to tell the listener to quit. This
868 implementation uses ``put_nowait()``. You may want to override this
869 method if you want to use timeouts or work with custom queue
870 implementations.
871
872 .. versionadded:: 3.3
873
Vinay Sajipc63619b2010-12-19 12:56:57 +0000874
875.. seealso::
876
877 Module :mod:`logging`
878 API reference for the logging module.
879
880 Module :mod:`logging.config`
881 Configuration API for the logging module.
882
883