Debian Codegraph @

Lib/logging/handlers.py

raw
1 # Copyright 2001-2021 by Vinay Sajip. All Rights Reserved.
2 #
3 # Permission to use, copy, modify, and distribute this software and its
4 # documentation for any purpose and without fee is hereby granted,
5 # provided that the above copyright notice appear in all copies and that
6 # both that copyright notice and this permission notice appear in
7 # supporting documentation, and that the name of Vinay Sajip
8 # not be used in advertising or publicity pertaining to distribution
9 # of the software without specific, written prior permission.
10 # VINAY SAJIP DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
11 # ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
12 # VINAY SAJIP BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
13 # ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
14 # IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
15 # OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16
17 """
18 Additional handlers for the logging package for Python. The core package is
19 based on PEP 282 and comments thereto in comp.lang.python.
20
21 Copyright (C) 2001-2021 Vinay Sajip. All Rights Reserved.
22
23 To use, simply 'import logging.handlers' and log away!
24 """
25
26 import copy
27 import io
28 import logging
29 import os
30 import pickle
31 import queue
32 import re
33 import socket
34 import struct
35 import threading
36 import time
37
38 #
39 # Some constants...
40 #
41
42 DEFAULT_TCP_LOGGING_PORT = 9020
43 DEFAULT_UDP_LOGGING_PORT = 9021
44 DEFAULT_HTTP_LOGGING_PORT = 9022
45 DEFAULT_SOAP_LOGGING_PORT = 9023
46 SYSLOG_UDP_PORT = 514
47 SYSLOG_TCP_PORT = 514
48
49 _MIDNIGHT = 24 * 60 * 60 # number of seconds in a day
50
51 class BaseRotatingHandler(logging.FileHandler):
52 """
53 Base class for handlers that rotate log files at a certain point.
54 Not meant to be instantiated directly. Instead, use RotatingFileHandler
55 or TimedRotatingFileHandler.
56 """
57 namer = None
58 rotator = None
59
60 def __init__(self, filename, mode, encoding=None, delay=False, errors=None):
61 """
62 Use the specified filename for streamed logging
63 """
64 logging.FileHandler.__init__(self, filename, mode=mode,
65 encoding=encoding, delay=delay,
66 errors=errors)
67 self.mode = mode
68 self.encoding = encoding
69 self.errors = errors
70
71 def emit(self, record):
72 """
73 Emit a record.
74
75 Output the record to the file, catering for rollover as described
76 in doRollover().
77 """
78 try:
79 if self.shouldRollover(record):
80 self.doRollover()
81 logging.FileHandler.emit(self, record)
82 except Exception:
83 self.handleError(record)
84
85 def rotation_filename(self, default_name):
86 """
87 Modify the filename of a log file when rotating.
88
89 This is provided so that a custom filename can be provided.
90
91 The default implementation calls the 'namer' attribute of the
92 handler, if it's callable, passing the default name to
93 it. If the attribute isn't callable (the default is None), the name
94 is returned unchanged.
95
96 :param default_name: The default name for the log file.
97 """
98 if not callable(self.namer):
99 result = default_name
100 else:
101 result = self.namer(default_name)
102 return result
103
104 def rotate(self, source, dest):
105 """
106 When rotating, rotate the current log.
107
108 The default implementation calls the 'rotator' attribute of the
109 handler, if it's callable, passing the source and dest arguments to
110 it. If the attribute isn't callable (the default is None), the source
111 is simply renamed to the destination.
112
113 :param source: The source filename. This is normally the base
114 filename, e.g. 'test.log'
115 :param dest: The destination filename. This is normally
116 what the source is rotated to, e.g. 'test.log.1'.
117 """
118 if not callable(self.rotator):
119 # Issue 18940: A file may not have been created if delay is True.
120 if os.path.exists(source):
121 os.rename(source, dest)
122 else:
123 self.rotator(source, dest)
124
125 class RotatingFileHandler(BaseRotatingHandler):
126 """
127 Handler for logging to a set of files, which switches from one file
128 to the next when the current file reaches a certain size.
129 """
130 def __init__(self, filename, mode='a', maxBytes=0, backupCount=0,
131 encoding=None, delay=False, errors=None):
132 """
133 Open the specified file and use it as the stream for logging.
134
135 By default, the file grows indefinitely. You can specify particular
136 values of maxBytes and backupCount to allow the file to rollover at
137 a predetermined size.
138
139 Rollover occurs whenever the current log file is nearly maxBytes in
140 length. If backupCount is >= 1, the system will successively create
141 new files with the same pathname as the base file, but with extensions
142 ".1", ".2" etc. appended to it. For example, with a backupCount of 5
143 and a base file name of "app.log", you would get "app.log",
144 "app.log.1", "app.log.2", ... through to "app.log.5". The file being
145 written to is always "app.log" - when it gets filled up, it is closed
146 and renamed to "app.log.1", and if files "app.log.1", "app.log.2" etc.
147 exist, then they are renamed to "app.log.2", "app.log.3" etc.
148 respectively.
149
150 If maxBytes is zero, rollover never occurs.
151 """
152 # If rotation/rollover is wanted, it doesn't make sense to use another
153 # mode. If for example 'w' were specified, then if there were multiple
154 # runs of the calling application, the logs from previous runs would be
155 # lost if the 'w' is respected, because the log file would be truncated
156 # on each run.
157 if maxBytes > 0:
158 mode = 'a'
159 if "b" not in mode:
160 encoding = io.text_encoding(encoding)
161 BaseRotatingHandler.__init__(self, filename, mode, encoding=encoding,
162 delay=delay, errors=errors)
163 self.maxBytes = maxBytes
164 self.backupCount = backupCount
165
166 def doRollover(self):
167 """
168 Do a rollover, as described in __init__().
169 """
170 if self.stream:
171 self.stream.close()
172 self.stream = None
173 if self.backupCount > 0:
174 for i in range(self.backupCount - 1, 0, -1):
175 sfn = self.rotation_filename("%s.%d" % (self.baseFilename, i))
176 dfn = self.rotation_filename("%s.%d" % (self.baseFilename,
177 i + 1))
178 if os.path.exists(sfn):
179 if os.path.exists(dfn):
180 os.remove(dfn)
181 os.rename(sfn, dfn)
182 dfn = self.rotation_filename(self.baseFilename + ".1")
183 if os.path.exists(dfn):
184 os.remove(dfn)
185 self.rotate(self.baseFilename, dfn)
186 if not self.delay:
187 self.stream = self._open()
188
189 def shouldRollover(self, record):
190 """
191 Determine if rollover should occur.
192
193 Basically, see if the supplied record would cause the file to exceed
194 the size limit we have.
195 """
196 if self.stream is None: # delay was set...
197 self.stream = self._open()
198 if self.maxBytes > 0: # are we rolling over?
199 try:
200 pos = self.stream.tell()
201 except io.UnsupportedOperation:
202 # gh-143237: Never rollover a named pipe.
203 return False
204 if not pos:
205 # gh-116263: Never rollover an empty file
206 return False
207 msg = "%s\n" % self.format(record)
208 if pos + len(msg) >= self.maxBytes:
209 # See bpo-45401: Never rollover anything other than regular files
210 if os.path.exists(self.baseFilename) and not os.path.isfile(self.baseFilename):
211 return False
212 return True
213 return False
214
215 class TimedRotatingFileHandler(BaseRotatingHandler):
216 """
217 Handler for logging to a file, rotating the log file at certain timed
218 intervals.
219
220 If backupCount is > 0, when rollover is done, no more than backupCount
221 files are kept - the oldest ones are deleted.
222 """
223 def __init__(self, filename, when='h', interval=1, backupCount=0,
224 encoding=None, delay=False, utc=False, atTime=None,
225 errors=None):
226 encoding = io.text_encoding(encoding)
227 BaseRotatingHandler.__init__(self, filename, 'a', encoding=encoding,
228 delay=delay, errors=errors)
229 self.when = when.upper()
230 self.backupCount = backupCount
231 self.utc = utc
232 self.atTime = atTime
233 # Calculate the real rollover interval, which is just the number of
234 # seconds between rollovers. Also set the filename suffix used when
235 # a rollover occurs. Current 'when' events supported:
236 # S - Seconds
237 # M - Minutes
238 # H - Hours
239 # D - Days
240 # midnight - roll over at midnight
241 # W{0-6} - roll over on a certain day; 0 - Monday
242 #
243 # Case of the 'when' specifier is not important; lower or upper case
244 # will work.
245 if self.when == 'S':
246 self.interval = 1 # one second
247 self.suffix = "%Y-%m-%d_%H-%M-%S"
248 extMatch = r"(?<!\d)\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}(?!\d)"
249 elif self.when == 'M':
250 self.interval = 60 # one minute
251 self.suffix = "%Y-%m-%d_%H-%M"
252 extMatch = r"(?<!\d)\d{4}-\d{2}-\d{2}_\d{2}-\d{2}(?!\d)"
253 elif self.when == 'H':
254 self.interval = 60 * 60 # one hour
255 self.suffix = "%Y-%m-%d_%H"
256 extMatch = r"(?<!\d)\d{4}-\d{2}-\d{2}_\d{2}(?!\d)"
257 elif self.when == 'D' or self.when == 'MIDNIGHT':
258 self.interval = 60 * 60 * 24 # one day
259 self.suffix = "%Y-%m-%d"
260 extMatch = r"(?<!\d)\d{4}-\d{2}-\d{2}(?!\d)"
261 elif self.when.startswith('W'):
262 self.interval = 60 * 60 * 24 * 7 # one week
263 if len(self.when) != 2:
264 raise ValueError("You must specify a day for weekly rollover from 0 to 6 (0 is Monday): %s" % self.when)
265 if self.when[1] < '0' or self.when[1] > '6':
266 raise ValueError("Invalid day specified for weekly rollover: %s" % self.when)
267 self.dayOfWeek = int(self.when[1])
268 self.suffix = "%Y-%m-%d"
269 extMatch = r"(?<!\d)\d{4}-\d{2}-\d{2}(?!\d)"
270 else:
271 raise ValueError("Invalid rollover interval specified: %s" % self.when)
272
273 # extMatch is a pattern for matching a datetime suffix in a file name.
274 # After custom naming, it is no longer guaranteed to be separated by
275 # periods from other parts of the filename. The lookup statements
276 # (?<!\d) and (?!\d) ensure that the datetime suffix (which itself
277 # starts and ends with digits) is not preceded or followed by digits.
278 # This reduces the number of false matches and improves performance.
279 self.extMatch = re.compile(extMatch, re.ASCII)
280 self.interval = self.interval * interval # multiply by units requested
281 # The following line added because the filename passed in could be a
282 # path object (see Issue #27493), but self.baseFilename will be a string
283 filename = self.baseFilename
284 if os.path.exists(filename):
285 t = int(os.stat(filename).st_mtime)
286 else:
287 t = int(time.time())
288 self.rolloverAt = self.computeRollover(t)
289
290 def computeRollover(self, currentTime):
291 """
292 Work out the rollover time based on the specified time.
293 """
294 result = currentTime + self.interval
295 # If we are rolling over at midnight or weekly, then the interval is already known.
296 # What we need to figure out is WHEN the next interval is. In other words,
297 # if you are rolling over at midnight, then your base interval is 1 day,
298 # but you want to start that one day clock at midnight, not now. So, we
299 # have to fudge the rolloverAt value in order to trigger the first rollover
300 # at the right time. After that, the regular interval will take care of
301 # the rest. Note that this code doesn't care about leap seconds. :)
302 if self.when == 'MIDNIGHT' or self.when.startswith('W'):
303 # This could be done with less code, but I wanted it to be clear
304 if self.utc:
305 t = time.gmtime(currentTime)
306 else:
307 t = time.localtime(currentTime)
308 currentHour = t[3]
309 currentMinute = t[4]
310 currentSecond = t[5]
311 currentDay = t[6]
312 # r is the number of seconds left between now and the next rotation
313 if self.atTime is None:
314 rotate_ts = _MIDNIGHT
315 else:
316 rotate_ts = ((self.atTime.hour * 60 + self.atTime.minute)*60 +
317 self.atTime.second)
318
319 r = rotate_ts - ((currentHour * 60 + currentMinute) * 60 +
320 currentSecond)
321 if r <= 0:
322 # Rotate time is before the current time (for example when
323 # self.rotateAt is 13:45 and it now 14:15), rotation is
324 # tomorrow.
325 r += _MIDNIGHT
326 currentDay = (currentDay + 1) % 7
327 result = currentTime + r
328 # If we are rolling over on a certain day, add in the number of days until
329 # the next rollover, but offset by 1 since we just calculated the time
330 # until the next day starts. There are three cases:
331 # Case 1) The day to rollover is today; in this case, do nothing
332 # Case 2) The day to rollover is further in the interval (i.e., today is
333 # day 2 (Wednesday) and rollover is on day 6 (Sunday). Days to
334 # next rollover is simply 6 - 2 - 1, or 3.
335 # Case 3) The day to rollover is behind us in the interval (i.e., today
336 # is day 5 (Saturday) and rollover is on day 3 (Thursday).
337 # Days to rollover is 6 - 5 + 3, or 4. In this case, it's the
338 # number of days left in the current week (1) plus the number
339 # of days in the next week until the rollover day (3).
340 # The calculations described in 2) and 3) above need to have a day added.
341 # This is because the above time calculation takes us to midnight on this
342 # day, i.e. the start of the next day.
343 if self.when.startswith('W'):
344 day = currentDay # 0 is Monday
345 if day != self.dayOfWeek:
346 if day < self.dayOfWeek:
347 daysToWait = self.dayOfWeek - day
348 else:
349 daysToWait = 6 - day + self.dayOfWeek + 1
350 result += daysToWait * _MIDNIGHT
351 result += self.interval - _MIDNIGHT * 7
352 else:
353 result += self.interval - _MIDNIGHT
354 if not self.utc:
355 dstNow = t[-1]
356 dstAtRollover = time.localtime(result)[-1]
357 if dstNow != dstAtRollover:
358 if not dstNow: # DST kicks in before next rollover, so we need to deduct an hour
359 addend = -3600
360 if not time.localtime(result-3600)[-1]:
361 addend = 0
362 else: # DST bows out before next rollover, so we need to add an hour
363 addend = 3600
364 result += addend
365 return result
366
367 def shouldRollover(self, record):
368 """
369 Determine if rollover should occur.
370
371 record is not used, as we are just comparing times, but it is needed so
372 the method signatures are the same
373 """
374 t = int(time.time())
375 if t >= self.rolloverAt:
376 # See #89564: Never rollover anything other than regular files
377 if os.path.exists(self.baseFilename) and not os.path.isfile(self.baseFilename):
378 # The file is not a regular file, so do not rollover, but do
379 # set the next rollover time to avoid repeated checks.
380 self.rolloverAt = self.computeRollover(t)
381 return False
382
383 return True
384 return False
385
386 def getFilesToDelete(self):
387 """
388 Determine the files to delete when rolling over.
389
390 More specific than the earlier method, which just used glob.glob().
391 """
392 dirName, baseName = os.path.split(self.baseFilename)
393 fileNames = os.listdir(dirName)
394 result = []
395 if self.namer is None:
396 prefix = baseName + '.'
397 plen = len(prefix)
398 for fileName in fileNames:
399 if fileName[:plen] == prefix:
400 suffix = fileName[plen:]
401 if self.extMatch.fullmatch(suffix):
402 result.append(os.path.join(dirName, fileName))
403 else:
404 for fileName in fileNames:
405 # Our files could be just about anything after custom naming,
406 # but they should contain the datetime suffix.
407 # Try to find the datetime suffix in the file name and verify
408 # that the file name can be generated by this handler.
409 m = self.extMatch.search(fileName)
410 while m:
411 dfn = self.namer(self.baseFilename + "." + m[0])
412 if os.path.basename(dfn) == fileName:
413 result.append(os.path.join(dirName, fileName))
414 break
415 m = self.extMatch.search(fileName, m.start() + 1)
416
417 if len(result) < self.backupCount:
418 result = []
419 else:
420 result.sort()
421 result = result[:len(result) - self.backupCount]
422 return result
423
424 def doRollover(self):
425 """
426 do a rollover; in this case, a date/time stamp is appended to the filename
427 when the rollover happens. However, you want the file to be named for the
428 start of the interval, not the current time. If there is a backup count,
429 then we have to get a list of matching filenames, sort them and remove
430 the one with the oldest suffix.
431 """
432 # get the time that this sequence started at and make it a TimeTuple
433 currentTime = int(time.time())
434 t = self.rolloverAt - self.interval
435 if self.utc:
436 timeTuple = time.gmtime(t)
437 else:
438 timeTuple = time.localtime(t)
439 dstNow = time.localtime(currentTime)[-1]
440 dstThen = timeTuple[-1]
441 if dstNow != dstThen:
442 if dstNow:
443 addend = 3600
444 else:
445 addend = -3600
446 timeTuple = time.localtime(t + addend)
447 dfn = self.rotation_filename(self.baseFilename + "." +
448 time.strftime(self.suffix, timeTuple))
449 if os.path.exists(dfn):
450 # Already rolled over.
451 return
452
453 if self.stream:
454 self.stream.close()
455 self.stream = None
456 self.rotate(self.baseFilename, dfn)
457 if self.backupCount > 0:
458 for s in self.getFilesToDelete():
459 os.remove(s)
460 if not self.delay:
461 self.stream = self._open()
462 self.rolloverAt = self.computeRollover(currentTime)
463
464 class WatchedFileHandler(logging.FileHandler):
465 """
466 A handler for logging to a file, which watches the file
467 to see if it has changed while in use. This can happen because of
468 usage of programs such as newsyslog and logrotate which perform
469 log file rotation. This handler, intended for use under Unix,
470 watches the file to see if it has changed since the last emit.
471 (A file has changed if its device or inode have changed.)
472 If it has changed, the old file stream is closed, and the file
473 opened to get a new stream.
474
475 This handler is not appropriate for use under Windows, because
476 under Windows open files cannot be moved or renamed - logging
477 opens the files with exclusive locks - and so there is no need
478 for such a handler.
479
480 This handler is based on a suggestion and patch by Chad J.
481 Schroeder.
482 """
483 def __init__(self, filename, mode='a', encoding=None, delay=False,
484 errors=None):
485 if "b" not in mode:
486 encoding = io.text_encoding(encoding)
487 logging.FileHandler.__init__(self, filename, mode=mode,
488 encoding=encoding, delay=delay,
489 errors=errors)
490 self.dev, self.ino = -1, -1
491 self._statstream()
492
493 def _statstream(self):
494 if self.stream is None:
495 return
496 sres = os.fstat(self.stream.fileno())
497 self.dev = sres.st_dev
498 self.ino = sres.st_ino
499
500 def reopenIfNeeded(self):
501 """
502 Reopen log file if needed.
503
504 Checks if the underlying file has changed, and if it
505 has, close the old stream and reopen the file to get the
506 current stream.
507 """
508 if self.stream is None:
509 return
510
511 # Reduce the chance of race conditions by stat'ing by path only
512 # once and then fstat'ing our new fd if we opened a new log stream.
513 # See issue #14632: Thanks to John Mulligan for the problem report
514 # and patch.
515 try:
516 # stat the file by path, checking for existence
517 sres = os.stat(self.baseFilename)
518
519 # compare file system stat with that of our stream file handle
520 reopen = (sres.st_dev != self.dev or sres.st_ino != self.ino)
521 except FileNotFoundError:
522 reopen = True
523
524 if not reopen:
525 return
526
527 # we have an open file handle, clean it up
528 self.stream.flush()
529 self.stream.close()
530 self.stream = None # See Issue #21742: _open () might fail.
531
532 # open a new file handle and get new stat info from that fd
533 self.stream = self._open()
534 self._statstream()
535
536 def emit(self, record):
537 """
538 Emit a record.
539
540 If underlying file has changed, reopen the file before emitting the
541 record to it.
542 """
543 self.reopenIfNeeded()
544 logging.FileHandler.emit(self, record)
545
546
547 class SocketHandler(logging.Handler):
548 """
549 A handler class which writes logging records, in pickle format, to
550 a streaming socket. The socket is kept open across logging calls.
551 If the peer resets it, an attempt is made to reconnect on the next call.
552 The pickle which is sent is that of the LogRecord's attribute dictionary
553 (__dict__), so that the receiver does not need to have the logging module
554 installed in order to process the logging event.
555
556 To unpickle the record at the receiving end into a LogRecord, use the
557 makeLogRecord function.
558 """
559
560 def __init__(self, host, port):
561 """
562 Initializes the handler with a specific host address and port.
563
564 When the attribute *closeOnError* is set to True - if a socket error
565 occurs, the socket is silently closed and then reopened on the next
566 logging call.
567 """
568 logging.Handler.__init__(self)
569 self.host = host
570 self.port = port
571 if port is None:
572 self.address = host
573 else:
574 self.address = (host, port)
575 self.sock = None
576 self.closeOnError = False
577 self.retryTime = None
578 #
579 # Exponential backoff parameters.
580 #
581 self.retryStart = 1.0
582 self.retryMax = 30.0
583 self.retryFactor = 2.0
584
585 def makeSocket(self, timeout=1):
586 """
587 A factory method which allows subclasses to define the precise
588 type of socket they want.
589 """
590 if self.port is not None:
591 result = socket.create_connection(self.address, timeout=timeout)
592 else:
593 result = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
594 result.settimeout(timeout)
595 try:
596 result.connect(self.address)
597 except OSError:
598 result.close() # Issue 19182
599 raise
600 return result
601
602 def createSocket(self):
603 """
604 Try to create a socket, using an exponential backoff with
605 a max retry time. Thanks to Robert Olson for the original patch
606 (SF #815911) which has been slightly refactored.
607 """
608 now = time.time()
609 # Either retryTime is None, in which case this
610 # is the first time back after a disconnect, or
611 # we've waited long enough.
612 if self.retryTime is None:
613 attempt = True
614 else:
615 attempt = (now >= self.retryTime)
616 if attempt:
617 try:
618 self.sock = self.makeSocket()
619 self.retryTime = None # next time, no delay before trying
620 except OSError:
621 #Creation failed, so set the retry time and return.
622 if self.retryTime is None:
623 self.retryPeriod = self.retryStart
624 else:
625 self.retryPeriod = self.retryPeriod * self.retryFactor
626 if self.retryPeriod > self.retryMax:
627 self.retryPeriod = self.retryMax
628 self.retryTime = now + self.retryPeriod
629
630 def send(self, s):
631 """
632 Send a pickled string to the socket.
633
634 This function allows for partial sends which can happen when the
635 network is busy.
636 """
637 if self.sock is None:
638 self.createSocket()
639 #self.sock can be None either because we haven't reached the retry
640 #time yet, or because we have reached the retry time and retried,
641 #but are still unable to connect.
642 if self.sock:
643 try:
644 self.sock.sendall(s)
645 except OSError: #pragma: no cover
646 self.sock.close()
647 self.sock = None # so we can call createSocket next time
648
649 def makePickle(self, record):
650 """
651 Pickles the record in binary format with a length prefix, and
652 returns it ready for transmission across the socket.
653 """
654 ei = record.exc_info
655 if ei:
656 # just to get traceback text into record.exc_text ...
657 dummy = self.format(record)
658 # See issue #14436: If msg or args are objects, they may not be
659 # available on the receiving end. So we convert the msg % args
660 # to a string, save it as msg and zap the args.
661 d = dict(record.__dict__)
662 d['msg'] = record.getMessage()
663 d['args'] = None
664 d['exc_info'] = None
665 # Issue #25685: delete 'message' if present: redundant with 'msg'
666 d.pop('message', None)
667 s = pickle.dumps(d, 1)
668 slen = struct.pack(">L", len(s))
669 return slen + s
670
671 def handleError(self, record):
672 """
673 Handle an error during logging.
674
675 An error has occurred during logging. Most likely cause -
676 connection lost. Close the socket so that we can retry on the
677 next event.
678 """
679 if self.closeOnError and self.sock:
680 self.sock.close()
681 self.sock = None #try to reconnect next time
682 else:
683 logging.Handler.handleError(self, record)
684
685 def emit(self, record):
686 """
687 Emit a record.
688
689 Pickles the record and writes it to the socket in binary format.
690 If there is an error with the socket, silently drop the packet.
691 If there was a problem with the socket, re-establishes the
692 socket.
693 """
694 try:
695 s = self.makePickle(record)
696 self.send(s)
697 except Exception:
698 self.handleError(record)
699
700 def close(self):
701 """
702 Closes the socket.
703 """
704 with self.lock:
705 sock = self.sock
706 if sock:
707 self.sock = None
708 sock.close()
709 logging.Handler.close(self)
710
711 class DatagramHandler(SocketHandler):
712 """
713 A handler class which writes logging records, in pickle format, to
714 a datagram socket. The pickle which is sent is that of the LogRecord's
715 attribute dictionary (__dict__), so that the receiver does not need to
716 have the logging module installed in order to process the logging event.
717
718 To unpickle the record at the receiving end into a LogRecord, use the
719 makeLogRecord function.
720
721 """
722 def __init__(self, host, port):
723 """
724 Initializes the handler with a specific host address and port.
725 """
726 SocketHandler.__init__(self, host, port)
727 self.closeOnError = False
728
729 def makeSocket(self):
730 """
731 The factory method of SocketHandler is here overridden to create
732 a UDP socket (SOCK_DGRAM).
733 """
734 if self.port is None:
735 family = socket.AF_UNIX
736 else:
737 family = socket.AF_INET
738 s = socket.socket(family, socket.SOCK_DGRAM)
739 return s
740
741 def send(self, s):
742 """
743 Send a pickled string to a socket.
744
745 This function no longer allows for partial sends which can happen
746 when the network is busy - UDP does not guarantee delivery and
747 can deliver packets out of sequence.
748 """
749 if self.sock is None:
750 self.createSocket()
751 self.sock.sendto(s, self.address)
752
753 class SysLogHandler(logging.Handler):
754 """
755 A handler class which sends formatted logging records to a syslog
756 server. Based on Sam Rushing's syslog module:
757 http://www.nightmare.com/squirl/python-ext/misc/syslog.py
758 Contributed by Nicolas Untz (after which minor refactoring changes
759 have been made).
760 """
761
762 # from <linux/sys/syslog.h>:
763 # ======================================================================
764 # priorities/facilities are encoded into a single 32-bit quantity, where
765 # the bottom 3 bits are the priority (0-7) and the top 28 bits are the
766 # facility (0-big number). Both the priorities and the facilities map
767 # roughly one-to-one to strings in the syslogd(8) source code. This
768 # mapping is included in this file.
769 #
770 # priorities (these are ordered)
771
772 LOG_EMERG = 0 # system is unusable
773 LOG_ALERT = 1 # action must be taken immediately
774 LOG_CRIT = 2 # critical conditions
775 LOG_ERR = 3 # error conditions
776 LOG_WARNING = 4 # warning conditions
777 LOG_NOTICE = 5 # normal but significant condition
778 LOG_INFO = 6 # informational
779 LOG_DEBUG = 7 # debug-level messages
780
781 # facility codes
782 LOG_KERN = 0 # kernel messages
783 LOG_USER = 1 # random user-level messages
784 LOG_MAIL = 2 # mail system
785 LOG_DAEMON = 3 # system daemons
786 LOG_AUTH = 4 # security/authorization messages
787 LOG_SYSLOG = 5 # messages generated internally by syslogd
788 LOG_LPR = 6 # line printer subsystem
789 LOG_NEWS = 7 # network news subsystem
790 LOG_UUCP = 8 # UUCP subsystem
791 LOG_CRON = 9 # clock daemon
792 LOG_AUTHPRIV = 10 # security/authorization messages (private)
793 LOG_FTP = 11 # FTP daemon
794 LOG_NTP = 12 # NTP subsystem
795 LOG_SECURITY = 13 # Log audit
796 LOG_CONSOLE = 14 # Log alert
797 LOG_SOLCRON = 15 # Scheduling daemon (Solaris)
798
799 # other codes through 15 reserved for system use
800 LOG_LOCAL0 = 16 # reserved for local use
801 LOG_LOCAL1 = 17 # reserved for local use
802 LOG_LOCAL2 = 18 # reserved for local use
803 LOG_LOCAL3 = 19 # reserved for local use
804 LOG_LOCAL4 = 20 # reserved for local use
805 LOG_LOCAL5 = 21 # reserved for local use
806 LOG_LOCAL6 = 22 # reserved for local use
807 LOG_LOCAL7 = 23 # reserved for local use
808
809 priority_names = {
810 "alert": LOG_ALERT,
811 "crit": LOG_CRIT,
812 "critical": LOG_CRIT,
813 "debug": LOG_DEBUG,
814 "emerg": LOG_EMERG,
815 "err": LOG_ERR,
816 "error": LOG_ERR, # DEPRECATED
817 "info": LOG_INFO,
818 "notice": LOG_NOTICE,
819 "panic": LOG_EMERG, # DEPRECATED
820 "warn": LOG_WARNING, # DEPRECATED
821 "warning": LOG_WARNING,
822 }
823
824 facility_names = {
825 "auth": LOG_AUTH,
826 "authpriv": LOG_AUTHPRIV,
827 "console": LOG_CONSOLE,
828 "cron": LOG_CRON,
829 "daemon": LOG_DAEMON,
830 "ftp": LOG_FTP,
831 "kern": LOG_KERN,
832 "lpr": LOG_LPR,
833 "mail": LOG_MAIL,
834 "news": LOG_NEWS,
835 "ntp": LOG_NTP,
836 "security": LOG_SECURITY,
837 "solaris-cron": LOG_SOLCRON,
838 "syslog": LOG_SYSLOG,
839 "user": LOG_USER,
840 "uucp": LOG_UUCP,
841 "local0": LOG_LOCAL0,
842 "local1": LOG_LOCAL1,
843 "local2": LOG_LOCAL2,
844 "local3": LOG_LOCAL3,
845 "local4": LOG_LOCAL4,
846 "local5": LOG_LOCAL5,
847 "local6": LOG_LOCAL6,
848 "local7": LOG_LOCAL7,
849 }
850
851 # Originally added to work around GH-43683. Unnecessary since GH-50043 but kept
852 # for backwards compatibility.
853 priority_map = {
854 "DEBUG" : "debug",
855 "INFO" : "info",
856 "WARNING" : "warning",
857 "ERROR" : "error",
858 "CRITICAL" : "critical"
859 }
860
861 def __init__(self, address=('localhost', SYSLOG_UDP_PORT),
862 facility=LOG_USER, socktype=None, timeout=None):
863 """
864 Initialize a handler.
865
866 If address is specified as a string, a UNIX socket is used. To log to a
867 local syslogd, "SysLogHandler(address="/dev/log")" can be used.
868 If facility is not specified, LOG_USER is used. If socktype is
869 specified as socket.SOCK_DGRAM or socket.SOCK_STREAM, that specific
870 socket type will be used. For Unix sockets, you can also specify a
871 socktype of None, in which case socket.SOCK_DGRAM will be used, falling
872 back to socket.SOCK_STREAM.
873 """
874 logging.Handler.__init__(self)
875
876 self.address = address
877 self.facility = facility
878 self.socktype = socktype
879 self.timeout = timeout
880 self.socket = None
881 self.createSocket()
882
883 def _connect_unixsocket(self, address):
884 use_socktype = self.socktype
885 if use_socktype is None:
886 use_socktype = socket.SOCK_DGRAM
887 self.socket = socket.socket(socket.AF_UNIX, use_socktype)
888 try:
889 self.socket.connect(address)
890 # it worked, so set self.socktype to the used type
891 self.socktype = use_socktype
892 except OSError:
893 self.socket.close()
894 if self.socktype is not None:
895 # user didn't specify falling back, so fail
896 raise
897 use_socktype = socket.SOCK_STREAM
898 self.socket = socket.socket(socket.AF_UNIX, use_socktype)
899 try:
900 self.socket.connect(address)
901 # it worked, so set self.socktype to the used type
902 self.socktype = use_socktype
903 except OSError:
904 self.socket.close()
905 raise
906
907 def createSocket(self):
908 """
909 Try to create a socket and, if it's not a datagram socket, connect it
910 to the other end. This method is called during handler initialization,
911 but it's not regarded as an error if the other end isn't listening yet
912 --- the method will be called again when emitting an event,
913 if there is no socket at that point.
914 """
915 address = self.address
916 socktype = self.socktype
917
918 if isinstance(address, str):
919 self.unixsocket = True
920 # Syslog server may be unavailable during handler initialisation.
921 # C's openlog() function also ignores connection errors.
922 # Moreover, we ignore these errors while logging, so it's not worse
923 # to ignore it also here.
924 try:
925 self._connect_unixsocket(address)
926 except OSError:
927 pass
928 else:
929 self.unixsocket = False
930 if socktype is None:
931 socktype = socket.SOCK_DGRAM
932 host, port = address
933 ress = socket.getaddrinfo(host, port, 0, socktype)
934 if not ress:
935 raise OSError("getaddrinfo returns an empty list")
936 for res in ress:
937 af, socktype, proto, _, sa = res
938 err = sock = None
939 try:
940 sock = socket.socket(af, socktype, proto)
941 if self.timeout:
942 sock.settimeout(self.timeout)
943 if socktype == socket.SOCK_STREAM:
944 sock.connect(sa)
945 break
946 except OSError as exc:
947 err = exc
948 if sock is not None:
949 sock.close()
950 if err is not None:
951 raise err
952 self.socket = sock
953 self.socktype = socktype
954
955 def encodePriority(self, facility, priority):
956 """
957 Encode the facility and priority. You can pass in strings or
958 integers - if strings are passed, the facility_names and
959 priority_names mapping dictionaries are used to convert them to
960 integers.
961 """
962 if isinstance(facility, str):
963 facility = self.facility_names[facility]
964 if isinstance(priority, str):
965 priority = self.priority_names[priority]
966 return (facility << 3) | priority
967
968 def close(self):
969 """
970 Closes the socket.
971 """
972 with self.lock:
973 sock = self.socket
974 if sock:
975 self.socket = None
976 sock.close()
977 logging.Handler.close(self)
978
979 def mapPriority(self, levelName):
980 """
981 Map a logging level name to a key in the priority_names map.
982 This is useful in two scenarios: when custom levels are being
983 used, and in the case where you can't do a straightforward
984 mapping by lowercasing the logging level name because of locale-
985 specific issues (see SF #1524081).
986 """
987 return self.priority_map.get(levelName, "warning")
988
989 ident = '' # prepended to all messages
990 append_nul = True # some old syslog daemons expect a NUL terminator
991
992 def emit(self, record):
993 """
994 Emit a record.
995
996 The record is formatted, and then sent to the syslog server. If
997 exception information is present, it is NOT sent to the server.
998 """
999 try:
1000 msg = self.format(record)
1001 if self.ident:
1002 msg = self.ident + msg
1003 if self.append_nul:
1004 msg += '\000'
1005
1006 # We need to convert record level to lowercase, maybe this will
1007 # change in the future.
1008 prio = '<%d>' % self.encodePriority(self.facility,
1009 self.mapPriority(record.levelname))
1010 prio = prio.encode('utf-8')
1011 # Message is a string. Convert to bytes as required by RFC 5424
1012 msg = msg.encode('utf-8')
1013 msg = prio + msg
1014
1015 if not self.socket:
1016 self.createSocket()
1017
1018 if self.unixsocket:
1019 try:
1020 self.socket.send(msg)
1021 except OSError:
1022 self.socket.close()
1023 self._connect_unixsocket(self.address)
1024 self.socket.send(msg)
1025 elif self.socktype == socket.SOCK_DGRAM:
1026 self.socket.sendto(msg, self.address)
1027 else:
1028 self.socket.sendall(msg)
1029 except Exception:
1030 self.handleError(record)
1031
1032 class SMTPHandler(logging.Handler):
1033 """
1034 A handler class which sends an SMTP email for each logging event.
1035 """
1036 def __init__(self, mailhost, fromaddr, toaddrs, subject,
1037 credentials=None, secure=None, timeout=5.0):
1038 """
1039 Initialize the handler.
1040
1041 Initialize the instance with the from and to addresses and subject
1042 line of the email. To specify a non-standard SMTP port, use the
1043 (host, port) tuple format for the mailhost argument. To specify
1044 authentication credentials, supply a (username, password) tuple
1045 for the credentials argument. To specify the use of a secure
1046 protocol (TLS), pass in a tuple for the secure argument. This will
1047 only be used when authentication credentials are supplied. The tuple
1048 will be either an empty tuple, or a single-value tuple with the name
1049 of a keyfile, or a 2-value tuple with the names of the keyfile and
1050 certificate file. (This tuple is passed to the
1051 `ssl.SSLContext.load_cert_chain` method).
1052 A timeout in seconds can be specified for the SMTP connection (the
1053 default is one second).
1054 """
1055 logging.Handler.__init__(self)
1056 if isinstance(mailhost, (list, tuple)):
1057 self.mailhost, self.mailport = mailhost
1058 else:
1059 self.mailhost, self.mailport = mailhost, None
1060 if isinstance(credentials, (list, tuple)):
1061 self.username, self.password = credentials
1062 else:
1063 self.username = None
1064 self.fromaddr = fromaddr
1065 if isinstance(toaddrs, str):
1066 toaddrs = [toaddrs]
1067 self.toaddrs = toaddrs
1068 self.subject = subject
1069 self.secure = secure
1070 self.timeout = timeout
1071
1072 def getSubject(self, record):
1073 """
1074 Determine the subject for the email.
1075
1076 If you want to specify a subject line which is record-dependent,
1077 override this method.
1078 """
1079 return self.subject
1080
1081 def emit(self, record):
1082 """
1083 Emit a record.
1084
1085 Format the record and send it to the specified addressees.
1086 """
1087 try:
1088 import smtplib
1089 from email.message import EmailMessage
1090 import email.utils
1091
1092 port = self.mailport
1093 if not port:
1094 port = smtplib.SMTP_PORT
1095 smtp = smtplib.SMTP(self.mailhost, port, timeout=self.timeout)
1096 msg = EmailMessage()
1097 msg['From'] = self.fromaddr
1098 msg['To'] = ','.join(self.toaddrs)
1099 msg['Subject'] = self.getSubject(record)
1100 msg['Date'] = email.utils.localtime()
1101 msg.set_content(self.format(record))
1102 if self.username:
1103 if self.secure is not None:
1104 import ssl
1105
1106 try:
1107 keyfile = self.secure[0]
1108 except IndexError:
1109 keyfile = None
1110
1111 try:
1112 certfile = self.secure[1]
1113 except IndexError:
1114 certfile = None
1115
1116 context = ssl._create_stdlib_context(
1117 certfile=certfile, keyfile=keyfile
1118 )
1119 smtp.ehlo()
1120 smtp.starttls(context=context)
1121 smtp.ehlo()
1122 smtp.login(self.username, self.password)
1123 smtp.send_message(msg)
1124 smtp.quit()
1125 except Exception:
1126 self.handleError(record)
1127
1128 class NTEventLogHandler(logging.Handler):
1129 """
1130 A handler class which sends events to the NT Event Log. Adds a
1131 registry entry for the specified application name. If no dllname is
1132 provided, win32service.pyd (which contains some basic message
1133 placeholders) is used. Note that use of these placeholders will make
1134 your event logs big, as the entire message source is held in the log.
1135 If you want slimmer logs, you have to pass in the name of your own DLL
1136 which contains the message definitions you want to use in the event log.
1137 """
1138 def __init__(self, appname, dllname=None, logtype="Application"):
1139 logging.Handler.__init__(self)
1140 try:
1141 import win32evtlogutil, win32evtlog
1142 self.appname = appname
1143 self._welu = win32evtlogutil
1144 if not dllname:
1145 dllname = os.path.split(self._welu.__file__)
1146 dllname = os.path.split(dllname[0])
1147 dllname = os.path.join(dllname[0], r'win32service.pyd')
1148 self.dllname = dllname
1149 self.logtype = logtype
1150 # Administrative privileges are required to add a source to the registry.
1151 # This may not be available for a user that just wants to add to an
1152 # existing source - handle this specific case.
1153 try:
1154 self._welu.AddSourceToRegistry(appname, dllname, logtype)
1155 except Exception as e:
1156 # This will probably be a pywintypes.error. Only raise if it's not
1157 # an "access denied" error, else let it pass
1158 if getattr(e, 'winerror', None) != 5: # not access denied
1159 raise
1160 self.deftype = win32evtlog.EVENTLOG_ERROR_TYPE
1161 self.typemap = {
1162 logging.DEBUG : win32evtlog.EVENTLOG_INFORMATION_TYPE,
1163 logging.INFO : win32evtlog.EVENTLOG_INFORMATION_TYPE,
1164 logging.WARNING : win32evtlog.EVENTLOG_WARNING_TYPE,
1165 logging.ERROR : win32evtlog.EVENTLOG_ERROR_TYPE,
1166 logging.CRITICAL: win32evtlog.EVENTLOG_ERROR_TYPE,
1167 }
1168 except ImportError:
1169 print("The Python Win32 extensions for NT (service, event "\
1170 "logging) appear not to be available.")
1171 self._welu = None
1172
1173 def getMessageID(self, record):
1174 """
1175 Return the message ID for the event record. If you are using your
1176 own messages, you could do this by having the msg passed to the
1177 logger being an ID rather than a formatting string. Then, in here,
1178 you could use a dictionary lookup to get the message ID. This
1179 version returns 1, which is the base message ID in win32service.pyd.
1180 """
1181 return 1
1182
1183 def getEventCategory(self, record):
1184 """
1185 Return the event category for the record.
1186
1187 Override this if you want to specify your own categories. This version
1188 returns 0.
1189 """
1190 return 0
1191
1192 def getEventType(self, record):
1193 """
1194 Return the event type for the record.
1195
1196 Override this if you want to specify your own types. This version does
1197 a mapping using the handler's typemap attribute, which is set up in
1198 __init__() to a dictionary which contains mappings for DEBUG, INFO,
1199 WARNING, ERROR and CRITICAL. If you are using your own levels you will
1200 either need to override this method or place a suitable dictionary in
1201 the handler's typemap attribute.
1202 """
1203 return self.typemap.get(record.levelno, self.deftype)
1204
1205 def emit(self, record):
1206 """
1207 Emit a record.
1208
1209 Determine the message ID, event category and event type. Then
1210 log the message in the NT event log.
1211 """
1212 if self._welu:
1213 try:
1214 id = self.getMessageID(record)
1215 cat = self.getEventCategory(record)
1216 type = self.getEventType(record)
1217 msg = self.format(record)
1218 self._welu.ReportEvent(self.appname, id, cat, type, [msg])
1219 except Exception:
1220 self.handleError(record)
1221
1222 def close(self):
1223 """
1224 Clean up this handler.
1225
1226 You can remove the application name from the registry as a
1227 source of event log entries. However, if you do this, you will
1228 not be able to see the events as you intended in the Event Log
1229 Viewer - it needs to be able to access the registry to get the
1230 DLL name.
1231 """
1232 #self._welu.RemoveSourceFromRegistry(self.appname, self.logtype)
1233 logging.Handler.close(self)
1234
1235 class HTTPHandler(logging.Handler):
1236 """
1237 A class which sends records to a web server, using either GET or
1238 POST semantics.
1239 """
1240 def __init__(self, host, url, method="GET", secure=False, credentials=None,
1241 context=None):
1242 """
1243 Initialize the instance with the host, the request URL, and the method
1244 ("GET" or "POST")
1245 """
1246 logging.Handler.__init__(self)
1247 method = method.upper()
1248 if method not in ["GET", "POST"]:
1249 raise ValueError("method must be GET or POST")
1250 if not secure and context is not None:
1251 raise ValueError("context parameter only makes sense "
1252 "with secure=True")
1253 self.host = host
1254 self.url = url
1255 self.method = method
1256 self.secure = secure
1257 self.credentials = credentials
1258 self.context = context
1259
1260 def mapLogRecord(self, record):
1261 """
1262 Default implementation of mapping the log record into a dict
1263 that is sent as the CGI data. Overwrite in your class.
1264 Contributed by Franz Glasner.
1265 """
1266 return record.__dict__
1267
1268 def getConnection(self, host, secure):
1269 """
1270 get a HTTP[S]Connection.
1271
1272 Override when a custom connection is required, for example if
1273 there is a proxy.
1274 """
1275 import http.client
1276 if secure:
1277 connection = http.client.HTTPSConnection(host, context=self.context)
1278 else:
1279 connection = http.client.HTTPConnection(host)
1280 return connection
1281
1282 def emit(self, record):
1283 """
1284 Emit a record.
1285
1286 Send the record to the web server as a percent-encoded dictionary
1287 """
1288 try:
1289 import urllib.parse
1290 host = self.host
1291 h = self.getConnection(host, self.secure)
1292 url = self.url
1293 data = urllib.parse.urlencode(self.mapLogRecord(record))
1294 if self.method == "GET":
1295 if (url.find('?') >= 0):
1296 sep = '&'
1297 else:
1298 sep = '?'
1299 url = url + "%c%s" % (sep, data)
1300 h.putrequest(self.method, url)
1301 # support multiple hosts on one IP address...
1302 # need to strip optional :port from host, if present
1303 i = host.find(":")
1304 if i >= 0:
1305 host = host[:i]
1306 # See issue #30904: putrequest call above already adds this header
1307 # on Python 3.x.
1308 # h.putheader("Host", host)
1309 if self.method == "POST":
1310 h.putheader("Content-type",
1311 "application/x-www-form-urlencoded")
1312 h.putheader("Content-length", str(len(data)))
1313 if self.credentials:
1314 import base64
1315 s = ('%s:%s' % self.credentials).encode('utf-8')
1316 s = 'Basic ' + base64.b64encode(s).strip().decode('ascii')
1317 h.putheader('Authorization', s)
1318 h.endheaders()
1319 if self.method == "POST":
1320 h.send(data.encode('utf-8'))
1321 h.getresponse() #can't do anything with the result
1322 except Exception:
1323 self.handleError(record)
1324
1325 class BufferingHandler(logging.Handler):
1326 """
1327 A handler class which buffers logging records in memory. Whenever each
1328 record is added to the buffer, a check is made to see if the buffer should
1329 be flushed. If it should, then flush() is expected to do what's needed.
1330 """
1331 def __init__(self, capacity):
1332 """
1333 Initialize the handler with the buffer size.
1334 """
1335 logging.Handler.__init__(self)
1336 self.capacity = capacity
1337 self.buffer = []
1338
1339 def shouldFlush(self, record):
1340 """
1341 Should the handler flush its buffer?
1342
1343 Returns true if the buffer is up to capacity. This method can be
1344 overridden to implement custom flushing strategies.
1345 """
1346 return (len(self.buffer) >= self.capacity)
1347
1348 def emit(self, record):
1349 """
1350 Emit a record.
1351
1352 Append the record. If shouldFlush() tells us to, call flush() to process
1353 the buffer.
1354 """
1355 self.buffer.append(record)
1356 if self.shouldFlush(record):
1357 self.flush()
1358
1359 def flush(self):
1360 """
1361 Override to implement custom flushing behaviour.
1362
1363 This version just zaps the buffer to empty.
1364 """
1365 with self.lock:
1366 self.buffer.clear()
1367
1368 def close(self):
1369 """
1370 Close the handler.
1371
1372 This version just flushes and chains to the parent class' close().
1373 """
1374 try:
1375 self.flush()
1376 finally:
1377 logging.Handler.close(self)
1378
1379 class MemoryHandler(BufferingHandler):
1380 """
1381 A handler class which buffers logging records in memory, periodically
1382 flushing them to a target handler. Flushing occurs whenever the buffer
1383 is full, or when an event of a certain severity or greater is seen.
1384 """
1385 def __init__(self, capacity, flushLevel=logging.ERROR, target=None,
1386 flushOnClose=True):
1387 """
1388 Initialize the handler with the buffer size, the level at which
1389 flushing should occur and an optional target.
1390
1391 Note that without a target being set either here or via setTarget(),
1392 a MemoryHandler is no use to anyone!
1393
1394 The ``flushOnClose`` argument is ``True`` for backward compatibility
1395 reasons - the old behaviour is that when the handler is closed, the
1396 buffer is flushed, even if the flush level hasn't been exceeded nor the
1397 capacity exceeded. To prevent this, set ``flushOnClose`` to ``False``.
1398 """
1399 BufferingHandler.__init__(self, capacity)
1400 self.flushLevel = flushLevel
1401 self.target = target
1402 # See Issue #26559 for why this has been added
1403 self.flushOnClose = flushOnClose
1404
1405 def shouldFlush(self, record):
1406 """
1407 Check for buffer full or a record at the flushLevel or higher.
1408 """
1409 return (len(self.buffer) >= self.capacity) or \
1410 (record.levelno >= self.flushLevel)
1411
1412 def setTarget(self, target):
1413 """
1414 Set the target handler for this handler.
1415 """
1416 with self.lock:
1417 self.target = target
1418
1419 def flush(self):
1420 """
1421 For a MemoryHandler, flushing means just sending the buffered
1422 records to the target, if there is one. Override if you want
1423 different behaviour.
1424
1425 The record buffer is only cleared if a target has been set.
1426 """
1427 with self.lock:
1428 if self.target:
1429 for record in self.buffer:
1430 self.target.handle(record)
1431 self.buffer.clear()
1432
1433 def close(self):
1434 """
1435 Flush, if appropriately configured, set the target to None and lose the
1436 buffer.
1437 """
1438 try:
1439 if self.flushOnClose:
1440 self.flush()
1441 finally:
1442 with self.lock:
1443 self.target = None
1444 BufferingHandler.close(self)
1445
1446
1447 class QueueHandler(logging.Handler):
1448 """
1449 This handler sends events to a queue. Typically, it would be used together
1450 with a multiprocessing Queue to centralise logging to file in one process
1451 (in a multi-process application), so as to avoid file write contention
1452 between processes.
1453
1454 This code is new in Python 3.2, but this class can be copy pasted into
1455 user code for use with earlier Python versions.
1456 """
1457
1458 def __init__(self, queue):
1459 """
1460 Initialise an instance, using the passed queue.
1461 """
1462 logging.Handler.__init__(self)
1463 self.queue = queue
1464 self.listener = None # will be set to listener if configured via dictConfig()
1465
1466 def enqueue(self, record):
1467 """
1468 Enqueue a record.
1469
1470 The base implementation uses put_nowait. You may want to override
1471 this method if you want to use blocking, timeouts or custom queue
1472 implementations.
1473 """
1474 self.queue.put_nowait(record)
1475
1476 def prepare(self, record):
1477 """
1478 Prepare a record for queuing. The object returned by this method is
1479 enqueued.
1480
1481 The base implementation formats the record to merge the message and
1482 arguments, and removes unpickleable items from the record in-place.
1483 Specifically, it overwrites the record's `msg` and
1484 `message` attributes with the merged message (obtained by
1485 calling the handler's `format` method), and sets the `args`,
1486 `exc_info` and `exc_text` attributes to None.
1487
1488 You might want to override this method if you want to convert
1489 the record to a dict or JSON string, or send a modified copy
1490 of the record while leaving the original intact.
1491 """
1492 # The format operation gets traceback text into record.exc_text
1493 # (if there's exception data), and also returns the formatted
1494 # message. We can then use this to replace the original
1495 # msg + args, as these might be unpickleable. We also zap the
1496 # exc_info, exc_text and stack_info attributes, as they are no longer
1497 # needed and, if not None, will typically not be pickleable.
1498 msg = self.format(record)
1499 # bpo-35726: make copy of record to avoid affecting other handlers in the chain.
1500 record = copy.copy(record)
1501 record.message = msg
1502 record.msg = msg
1503 record.args = None
1504 record.exc_info = None
1505 record.exc_text = None
1506 record.stack_info = None
1507 return record
1508
1509 def emit(self, record):
1510 """
1511 Emit a record.
1512
1513 Writes the LogRecord to the queue, preparing it for pickling first.
1514 """
1515 try:
1516 self.enqueue(self.prepare(record))
1517 except Exception:
1518 self.handleError(record)
1519
1520
1521 class QueueListener(object):
1522 """
1523 This class implements an internal threaded listener which watches for
1524 LogRecords being added to a queue, removes them and passes them to a
1525 list of handlers for processing.
1526 """
1527 _sentinel = None
1528
1529 def __init__(self, queue, *handlers, respect_handler_level=False):
1530 """
1531 Initialise an instance with the specified queue and
1532 handlers.
1533 """
1534 self.queue = queue
1535 self.handlers = handlers
1536 self._thread = None
1537 self.respect_handler_level = respect_handler_level
1538
1539 def __enter__(self):
1540 """
1541 For use as a context manager. Starts the listener.
1542 """
1543 self.start()
1544 return self
1545
1546 def __exit__(self, *args):
1547 """
1548 For use as a context manager. Stops the listener.
1549 """
1550 self.stop()
1551
1552 def dequeue(self, block):
1553 """
1554 Dequeue a record and return it, optionally blocking.
1555
1556 The base implementation uses get. You may want to override this method
1557 if you want to use timeouts or work with custom queue implementations.
1558 """
1559 return self.queue.get(block)
1560
1561 def start(self):
1562 """
1563 Start the listener.
1564
1565 This starts up a background thread to monitor the queue for
1566 LogRecords to process.
1567 """
1568 if self._thread is not None:
1569 raise RuntimeError("Listener already started")
1570
1571 self._thread = t = threading.Thread(target=self._monitor)
1572 t.daemon = True
1573 t.start()
1574
1575 def prepare(self, record):
1576 """
1577 Prepare a record for handling.
1578
1579 This method just returns the passed-in record. You may want to
1580 override this method if you need to do any custom marshalling or
1581 manipulation of the record before passing it to the handlers.
1582 """
1583 return record
1584
1585 def handle(self, record):
1586 """
1587 Handle a record.
1588
1589 This just loops through the handlers offering them the record
1590 to handle.
1591 """
1592 record = self.prepare(record)
1593 for handler in self.handlers:
1594 if not self.respect_handler_level:
1595 process = True
1596 else:
1597 process = record.levelno >= handler.level
1598 if process:
1599 handler.handle(record)
1600
1601 def _monitor(self):
1602 """
1603 Monitor the queue for records, and ask the handler
1604 to deal with them.
1605
1606 This method runs on a separate, internal thread.
1607 The thread will terminate if it sees a sentinel object in the queue.
1608 """
1609 q = self.queue
1610 has_task_done = hasattr(q, 'task_done')
1611 while True:
1612 try:
1613 record = self.dequeue(True)
1614 if record is self._sentinel:
1615 if has_task_done:
1616 q.task_done()
1617 break
1618 self.handle(record)
1619 if has_task_done:
1620 q.task_done()
1621 except queue.Empty:
1622 break
1623
1624 def enqueue_sentinel(self):
1625 """
1626 This is used to enqueue the sentinel record.
1627
1628 The base implementation uses put_nowait. You may want to override this
1629 method if you want to use timeouts or work with custom queue
1630 implementations.
1631 """
1632 self.queue.put_nowait(self._sentinel)
1633
1634 def stop(self):
1635 """
1636 Stop the listener.
1637
1638 This asks the thread to terminate, and then waits for it to do so.
1639 Note that if you don't call this before your application exits, there
1640 may be some records still left on the queue, which won't be processed.
1641 """
1642 if self._thread: # see gh-114706 - allow calling this more than once
1643 self.enqueue_sentinel()
1644 self._thread.join()
1645 self._thread = None