blob: e8353ea5afe9eed41d0363588961ecbcf6d6ef34 [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
455 .. method:: encodePriority(facility, priority)
456
457 Encodes the facility and priority into an integer. You can pass in strings
458 or integers - if strings are passed, internal mapping dictionaries are
459 used to convert them to integers.
460
461 The symbolic ``LOG_`` values are defined in :class:`SysLogHandler` and
462 mirror the values defined in the ``sys/syslog.h`` header file.
463
464 **Priorities**
465
466 +--------------------------+---------------+
467 | Name (string) | Symbolic value|
468 +==========================+===============+
469 | ``alert`` | LOG_ALERT |
470 +--------------------------+---------------+
471 | ``crit`` or ``critical`` | LOG_CRIT |
472 +--------------------------+---------------+
473 | ``debug`` | LOG_DEBUG |
474 +--------------------------+---------------+
475 | ``emerg`` or ``panic`` | LOG_EMERG |
476 +--------------------------+---------------+
477 | ``err`` or ``error`` | LOG_ERR |
478 +--------------------------+---------------+
479 | ``info`` | LOG_INFO |
480 +--------------------------+---------------+
481 | ``notice`` | LOG_NOTICE |
482 +--------------------------+---------------+
483 | ``warn`` or ``warning`` | LOG_WARNING |
484 +--------------------------+---------------+
485
486 **Facilities**
487
488 +---------------+---------------+
489 | Name (string) | Symbolic value|
490 +===============+===============+
491 | ``auth`` | LOG_AUTH |
492 +---------------+---------------+
493 | ``authpriv`` | LOG_AUTHPRIV |
494 +---------------+---------------+
495 | ``cron`` | LOG_CRON |
496 +---------------+---------------+
497 | ``daemon`` | LOG_DAEMON |
498 +---------------+---------------+
499 | ``ftp`` | LOG_FTP |
500 +---------------+---------------+
501 | ``kern`` | LOG_KERN |
502 +---------------+---------------+
503 | ``lpr`` | LOG_LPR |
504 +---------------+---------------+
505 | ``mail`` | LOG_MAIL |
506 +---------------+---------------+
507 | ``news`` | LOG_NEWS |
508 +---------------+---------------+
509 | ``syslog`` | LOG_SYSLOG |
510 +---------------+---------------+
511 | ``user`` | LOG_USER |
512 +---------------+---------------+
513 | ``uucp`` | LOG_UUCP |
514 +---------------+---------------+
515 | ``local0`` | LOG_LOCAL0 |
516 +---------------+---------------+
517 | ``local1`` | LOG_LOCAL1 |
518 +---------------+---------------+
519 | ``local2`` | LOG_LOCAL2 |
520 +---------------+---------------+
521 | ``local3`` | LOG_LOCAL3 |
522 +---------------+---------------+
523 | ``local4`` | LOG_LOCAL4 |
524 +---------------+---------------+
525 | ``local5`` | LOG_LOCAL5 |
526 +---------------+---------------+
527 | ``local6`` | LOG_LOCAL6 |
528 +---------------+---------------+
529 | ``local7`` | LOG_LOCAL7 |
530 +---------------+---------------+
531
532 .. method:: mapPriority(levelname)
533
534 Maps a logging level name to a syslog priority name.
535 You may need to override this if you are using custom levels, or
536 if the default algorithm is not suitable for your needs. The
537 default algorithm maps ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR`` and
538 ``CRITICAL`` to the equivalent syslog names, and all other level
539 names to 'warning'.
540
541.. _nt-eventlog-handler:
542
543NTEventLogHandler
544^^^^^^^^^^^^^^^^^
545
546The :class:`NTEventLogHandler` class, located in the :mod:`logging.handlers`
547module, supports sending logging messages to a local Windows NT, Windows 2000 or
548Windows XP event log. Before you can use it, you need Mark Hammond's Win32
549extensions for Python installed.
550
551
552.. class:: NTEventLogHandler(appname, dllname=None, logtype='Application')
553
554 Returns a new instance of the :class:`NTEventLogHandler` class. The *appname* is
555 used to define the application name as it appears in the event log. An
556 appropriate registry entry is created using this name. The *dllname* should give
557 the fully qualified pathname of a .dll or .exe which contains message
558 definitions to hold in the log (if not specified, ``'win32service.pyd'`` is used
559 - this is installed with the Win32 extensions and contains some basic
560 placeholder message definitions. Note that use of these placeholders will make
561 your event logs big, as the entire message source is held in the log. If you
562 want slimmer logs, you have to pass in the name of your own .dll or .exe which
563 contains the message definitions you want to use in the event log). The
564 *logtype* is one of ``'Application'``, ``'System'`` or ``'Security'``, and
565 defaults to ``'Application'``.
566
567
568 .. method:: close()
569
570 At this point, you can remove the application name from the registry as a
571 source of event log entries. However, if you do this, you will not be able
572 to see the events as you intended in the Event Log Viewer - it needs to be
573 able to access the registry to get the .dll name. The current version does
574 not do this.
575
576
577 .. method:: emit(record)
578
579 Determines the message ID, event category and event type, and then logs
580 the message in the NT event log.
581
582
583 .. method:: getEventCategory(record)
584
585 Returns the event category for the record. Override this if you want to
586 specify your own categories. This version returns 0.
587
588
589 .. method:: getEventType(record)
590
591 Returns the event type for the record. Override this if you want to
592 specify your own types. This version does a mapping using the handler's
593 typemap attribute, which is set up in :meth:`__init__` to a dictionary
594 which contains mappings for :const:`DEBUG`, :const:`INFO`,
595 :const:`WARNING`, :const:`ERROR` and :const:`CRITICAL`. If you are using
596 your own levels, you will either need to override this method or place a
597 suitable dictionary in the handler's *typemap* attribute.
598
599
600 .. method:: getMessageID(record)
601
602 Returns the message ID for the record. If you are using your own messages,
603 you could do this by having the *msg* passed to the logger being an ID
604 rather than a format string. Then, in here, you could use a dictionary
605 lookup to get the message ID. This version returns 1, which is the base
606 message ID in :file:`win32service.pyd`.
607
608.. _smtp-handler:
609
610SMTPHandler
611^^^^^^^^^^^
612
613The :class:`SMTPHandler` class, located in the :mod:`logging.handlers` module,
614supports sending logging messages to an email address via SMTP.
615
616
617.. class:: SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None)
618
619 Returns a new instance of the :class:`SMTPHandler` class. The instance is
620 initialized with the from and to addresses and subject line of the email. The
621 *toaddrs* should be a list of strings. To specify a non-standard SMTP port, use
622 the (host, port) tuple format for the *mailhost* argument. If you use a string,
623 the standard SMTP port is used. If your SMTP server requires authentication, you
624 can specify a (username, password) tuple for the *credentials* argument.
625
626
627 .. method:: emit(record)
628
629 Formats the record and sends it to the specified addressees.
630
631
632 .. method:: getSubject(record)
633
634 If you want to specify a subject line which is record-dependent, override
635 this method.
636
637.. _memory-handler:
638
639MemoryHandler
640^^^^^^^^^^^^^
641
642The :class:`MemoryHandler` class, located in the :mod:`logging.handlers` module,
643supports buffering of logging records in memory, periodically flushing them to a
644:dfn:`target` handler. Flushing occurs whenever the buffer is full, or when an
645event of a certain severity or greater is seen.
646
647:class:`MemoryHandler` is a subclass of the more general
648:class:`BufferingHandler`, which is an abstract class. This buffers logging
649records in memory. Whenever each record is added to the buffer, a check is made
650by calling :meth:`shouldFlush` to see if the buffer should be flushed. If it
651should, then :meth:`flush` is expected to do the needful.
652
653
654.. class:: BufferingHandler(capacity)
655
656 Initializes the handler with a buffer of the specified capacity.
657
658
659 .. method:: emit(record)
660
661 Appends the record to the buffer. If :meth:`shouldFlush` returns true,
662 calls :meth:`flush` to process the buffer.
663
664
665 .. method:: flush()
666
667 You can override this to implement custom flushing behavior. This version
668 just zaps the buffer to empty.
669
670
671 .. method:: shouldFlush(record)
672
673 Returns true if the buffer is up to capacity. This method can be
674 overridden to implement custom flushing strategies.
675
676
677.. class:: MemoryHandler(capacity, flushLevel=ERROR, target=None)
678
679 Returns a new instance of the :class:`MemoryHandler` class. The instance is
680 initialized with a buffer size of *capacity*. If *flushLevel* is not specified,
681 :const:`ERROR` is used. If no *target* is specified, the target will need to be
682 set using :meth:`setTarget` before this handler does anything useful.
683
684
685 .. method:: close()
686
687 Calls :meth:`flush`, sets the target to :const:`None` and clears the
688 buffer.
689
690
691 .. method:: flush()
692
693 For a :class:`MemoryHandler`, flushing means just sending the buffered
694 records to the target, if there is one. The buffer is also cleared when
695 this happens. Override if you want different behavior.
696
697
698 .. method:: setTarget(target)
699
700 Sets the target handler for this handler.
701
702
703 .. method:: shouldFlush(record)
704
705 Checks for buffer full or a record at the *flushLevel* or higher.
706
707
708.. _http-handler:
709
710HTTPHandler
711^^^^^^^^^^^
712
713The :class:`HTTPHandler` class, located in the :mod:`logging.handlers` module,
714supports sending logging messages to a Web server, using either ``GET`` or
715``POST`` semantics.
716
717
718.. class:: HTTPHandler(host, url, method='GET', secure=False, credentials=None)
719
720 Returns a new instance of the :class:`HTTPHandler` class. The *host* can be
721 of the form ``host:port``, should you need to use a specific port number.
722 If no *method* is specified, ``GET`` is used. If *secure* is True, an HTTPS
723 connection will be used. If *credentials* is specified, it should be a
724 2-tuple consisting of userid and password, which will be placed in an HTTP
725 'Authorization' header using Basic authentication. If you specify
726 credentials, you should also specify secure=True so that your userid and
727 password are not passed in cleartext across the wire.
728
729
730 .. method:: emit(record)
731
732 Sends the record to the Web server as a percent-encoded dictionary.
733
734
735.. _queue-handler:
736
737
738QueueHandler
739^^^^^^^^^^^^
740
741.. versionadded:: 3.2
742
743The :class:`QueueHandler` class, located in the :mod:`logging.handlers` module,
744supports sending logging messages to a queue, such as those implemented in the
745:mod:`queue` or :mod:`multiprocessing` modules.
746
747Along with the :class:`QueueListener` class, :class:`QueueHandler` can be used
748to let handlers do their work on a separate thread from the one which does the
749logging. This is important in Web applications and also other service
750applications where threads servicing clients need to respond as quickly as
751possible, while any potentially slow operations (such as sending an email via
752:class:`SMTPHandler`) are done on a separate thread.
753
754.. class:: QueueHandler(queue)
755
756 Returns a new instance of the :class:`QueueHandler` class. The instance is
757 initialized with the queue to send messages to. The queue can be any queue-
758 like object; it's used as-is by the :meth:`enqueue` method, which needs
759 to know how to send messages to it.
760
761
762 .. method:: emit(record)
763
764 Enqueues the result of preparing the LogRecord.
765
766 .. method:: prepare(record)
767
768 Prepares a record for queuing. The object returned by this
769 method is enqueued.
770
771 The base implementation formats the record to merge the message
772 and arguments, and removes unpickleable items from the record
773 in-place.
774
775 You might want to override this method if you want to convert
776 the record to a dict or JSON string, or send a modified copy
777 of the record while leaving the original intact.
778
779 .. method:: enqueue(record)
780
781 Enqueues the record on the queue using ``put_nowait()``; you may
782 want to override this if you want to use blocking behaviour, or a
783 timeout, or a customised queue implementation.
784
785
786
787.. queue-listener:
788
789QueueListener
790^^^^^^^^^^^^^
791
792.. versionadded:: 3.2
793
794The :class:`QueueListener` class, located in the :mod:`logging.handlers`
795module, supports receiving logging messages from a queue, such as those
796implemented in the :mod:`queue` or :mod:`multiprocessing` modules. The
797messages are received from a queue in an internal thread and passed, on
798the same thread, to one or more handlers for processing. While
799:class:`QueueListener` is not itself a handler, it is documented here
800because it works hand-in-hand with :class:`QueueHandler`.
801
802Along with the :class:`QueueHandler` class, :class:`QueueListener` can be used
803to let handlers do their work on a separate thread from the one which does the
804logging. This is important in Web applications and also other service
805applications where threads servicing clients need to respond as quickly as
806possible, while any potentially slow operations (such as sending an email via
807:class:`SMTPHandler`) are done on a separate thread.
808
809.. class:: QueueListener(queue, *handlers)
810
811 Returns a new instance of the :class:`QueueListener` class. The instance is
812 initialized with the queue to send messages to and a list of handlers which
813 will handle entries placed on the queue. The queue can be any queue-
814 like object; it's passed as-is to the :meth:`dequeue` method, which needs
815 to know how to get messages from it.
816
817 .. method:: dequeue(block)
818
819 Dequeues a record and return it, optionally blocking.
820
821 The base implementation uses ``get()``. You may want to override this
822 method if you want to use timeouts or work with custom queue
823 implementations.
824
825 .. method:: prepare(record)
826
827 Prepare a record for handling.
828
829 This implementation just returns the passed-in record. You may want to
830 override this method if you need to do any custom marshalling or
831 manipulation of the record before passing it to the handlers.
832
833 .. method:: handle(record)
834
835 Handle a record.
836
837 This just loops through the handlers offering them the record
838 to handle. The actual object passed to the handlers is that which
839 is returned from :meth:`prepare`.
840
841 .. method:: start()
842
843 Starts the listener.
844
845 This starts up a background thread to monitor the queue for
846 LogRecords to process.
847
848 .. method:: stop()
849
850 Stops the listener.
851
852 This asks the thread to terminate, and then waits for it to do so.
853 Note that if you don't call this before your application exits, there
854 may be some records still left on the queue, which won't be processed.
855
Vinay Sajipa29a9dd2011-02-25 16:05:26 +0000856 .. method:: enqueue_sentinel()
857
858 Writes a sentinel to the queue to tell the listener to quit. This
859 implementation uses ``put_nowait()``. You may want to override this
860 method if you want to use timeouts or work with custom queue
861 implementations.
862
863 .. versionadded:: 3.3
864
Vinay Sajipc63619b2010-12-19 12:56:57 +0000865
866.. seealso::
867
868 Module :mod:`logging`
869 API reference for the logging module.
870
871 Module :mod:`logging.config`
872 Configuration API for the logging module.
873
874