logging.handlers — Обработчики логгирования

Исходный код: Lib/logging/handlers.py

В пакете предоставлены следующие полезные обработчики. Обратите внимание, что три из обработчиков (StreamHandler, FileHandler и NullHandler) фактически определены в модуле logging, но документированы здесь вместе с другими обработчиками.

16.8.1. Обработчик потока

Класс StreamHandler, расположенный в базовом пакете logging, отправляет данные логгирования в потоки, такие как sys.stdout, sys.stderr или любой объект, подобный файлу (или, точнее, любой объект, который поддерживает методы write() и flush()).

class logging.StreamHandler(stream=None)

Возвращает новый экземпляр класса StreamHandler. Если задан параметр stream, экземпляр будет использовать его для вывода логов; в противном случае будет использован sys.stderr.

emit(record)

Если указан форматер, он используется для форматирования записи. Затем запись записывается в поток с разделителем. Если присутствует информация об исключении, она форматируется с помощью traceback.print_exception() и добавляется в поток.

flush()

Очищает поток, вызывая его метод flush(). Обратите внимание, что метод close() унаследован от Handler и не выполняет вывод, поэтому иногда может потребоваться явное вызов flush().

16.8.2. Обработчик файла

Класс FileHandler, расположенный в базовом пакете logging, отправляет данные логгирования в файл на диске. Он наследует функциональность вывода от StreamHandler.

class logging.FileHandler(filename, mode='a', encoding=None, delay=False)

Возвращает новый экземпляр класса FileHandler. Указанный файл открывается и используется как поток для логгирования. Если mode не указан, используется 'a'. Если encoding не None, используется для открытия файла с этим кодированием. Если delay равно true, открытие файла откладывается до первого вызова emit(). По умолчанию файл растёт неограниченно.

Изменено в версии 3.6: Вместо строковых значений, также принимаются объекты Path для аргумента filename.

close()

Закрывает файл.

emit(record)

Выводит запись в файл.

16.8.3. Обработчик Null

Класс NullHandler, расположенный в базовом пакете logging, не выполняет форматирование или вывод. Это по существу обработчик «без операции» для использования разработчиками библиотек.

class logging.NullHandler

Возвращает новый экземпляр класса NullHandler.

emit(record)

Этот метод ничего не делает.

handle(record)

Этот метод ничего не делает.

createLock()

Этот метод возвращает None для блокировки, так как нет базового ввода/вывода, для которого необходимо сериализовать доступ.

См. Настройка логгирования для библиотеки для получения дополнительной информации о том, как использовать NullHandler.

16.8.4. Обработчик слежения за файлом

Класс WatchedFileHandler, расположенный в модуле logging.handlers, представляет собой FileHandler, который отслеживает файл, в который он записывает логи. Если файл изменяется, он закрывается и переоткрывается с использованием имени файла.

Изменение файла может произойти из-за использования таких программ, как newsyslog и logrotate, которые выполняют ротацию файла логов. Этот обработчик, предназначенный для использования в Unix/Linux, следит за тем, изменился ли файл с момента последнего вызова emit. (Файл считается изменённым, если изменились его устройство или индексный дескриптор.) Если файл изменился, старый поток файла закрывается, и файл открывается для получения нового потока.

Этот обработчик не подходит для использования в Windows, поскольку в Windows открытые файлы логов нельзя перемещать или переименовывать — логгирование открывает файлы с эксклюзивными блокировками — и поэтому такого обработчика не нужно. Кроме того, ST_INO не поддерживается в Windows; stat() всегда возвращает ноль для этого значения.

class logging.handlers.WatchedFileHandler(filename, mode='a', encoding=None, delay=False)

Возвращает новый экземпляр класса WatchedFileHandler. Указанный файл открывается и используется как поток для логгирования. Если mode не указан, используется 'a'. Если encoding не None, используется для открытия файла с этим кодированием. Если delay равно true, открытие файла откладывается до первого вызова emit(). По умолчанию файл растёт неограниченно.

Изменено в версии 3.6: Вместо строковых значений, также принимаются объекты Path для аргумента filename.

reopenIfNeeded()

Проверяет, изменился ли файл. Если изменился, существующий поток очищается и закрывается, а файл открывается заново, как правило, перед выводом записи в файл.

Новое в версии 3.6.

emit(record)

Выводит запись в файл, но сначала вызывает reopenIfNeeded() для повторного открытия файла, если он изменился.

16.8.5. Базовый обработчик вращения

Класс BaseRotatingHandler, расположенный в модуле logging.handlers, является базовым классом для обработчиков вращающихся файлов, RotatingFileHandler и TimedRotatingFileHandler. Вам, скорее всего, не нужно создавать экземпляры этого класса, но у него есть атрибуты и методы, которые вам может потребоваться переопределить.

class logging.handlers.BaseRotatingHandler(filename, mode, encoding=None, delay=False)

Параметры такие же, как у FileHandler. Атрибуты:

namer

Если этот атрибут установлен в вызываемую функцию, метод rotation_filename() делегирует вызов этой функции. Параметры, передаваемые вызываемой функции, — это параметры, передаваемые методу rotation_filename().

Примечание

Функция namer вызывается довольно много раз во время переключения, поэтому она должна быть максимально простой и быстрой. Она также должна каждый раз возвращать один и тот же результат для заданного входного значения, иначе поведение переключения может работать не так, как ожидается.

Добавлена в версии 3.3.

rotator

Если этот атрибут установлен в вызываемую функцию, метод rotate() делегирует вызов этой функции. Параметры, передаваемые вызываемой функции, — это параметры, передаваемые методу rotate().

Добавлена в версии 3.3.

rotation_filename(default_name)

Изменяет имя файла журнала при вращении.

Это предоставлено для того, чтобы можно было указать пользовательское имя файла.

В реализации по умолчанию вызывается атрибут «namer» обработчика, если он является вызываемой функцией, передавая ему имя по умолчанию. Если атрибут не является вызываемой функцией (по умолчанию None), имя возвращается без изменений.

Параметры

default_name – Имя файла журнала по умолчанию.

Добавлена в версии 3.3.

rotate(source, dest)

При вращении выполняет вращение текущего журнала.

В реализации по умолчанию вызывается атрибут «rotator» обработчика, если он является вызываемой функцией, передавая ей аргументы source и dest. Если атрибут не является вызываемой функцией (по умолчанию None), исходное имя просто переименовывается в целевое.

Параметры

• source – Имя исходного файла. Обычно это базовое имя файла, например, «test.log».
• dest – Имя целевого файла. Обычно это то, во что исходный файл вращается, например, «test.log.1».

Добавлена в версии 3.3.

Причина существования атрибутов заключается в том, чтобы не пришлось создавать подклассы — вы можете использовать одни и те же вызываемые функции для экземпляров RotatingFileHandler и TimedRotatingFileHandler. Если вызываемая функция namer или rotator вызывает исключение, оно будет обработано так же, как и любое другое исключение во время вызова emit(), то есть через метод handleError() обработчика.

Если вам необходимо внести более существенные изменения в обработку вращения, вы можете переопределить методы.

Пример см. в Использование rotator и namer для настройки обработки вращения логов.

16.8.6. RotatingFileHandler

Класс RotatingFileHandler, расположенный в модуле logging.handlers, поддерживает вращение файлов журналов на диске.

class logging.handlers.RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=False)

Возвращает новый экземпляр класса RotatingFileHandler. Указанный файл открывается и используется в качестве потока для ведения журнала. Если mode не указан, используется 'a'. Если encoding не None, он используется для открытия файла с этим кодированием. Если delay имеет значение true, открытие файла откладывается до первого вызова emit(). По умолчанию размер файла неограничен.

Вы можете использовать значения maxBytes и backupCount, чтобы позволить файлу переключаться на определенный размер. При приближении к превышению размера файл закрывается, и для вывода бесшумно открывается новый файл. Переключение происходит всякий раз, когда текущий файл журнала приближается к длине maxBytes; но если maxBytes или backupCount равны нулю, переключение никогда не происходит, поэтому вы обычно хотите установить backupCount хотя бы на 1 и maxBytes — на ненулевое значение. Когда backupCount ненулевое, система сохранит старые файлы журналов, добавив расширения «.1», «.2» и т. д. к имени файла. Например, при backupCount = 5 и базовом имени файла app.log, вы получите app.log, app.log.1, app.log.2, вплоть до app.log.5. Файл, в который записывается, всегда app.log. Когда этот файл заполнен, он закрывается и переименовывается в app.log.1, и если файлы app.log.1, app.log.2, и т. д. существуют, они переименовываются в app.log.2, app.log.3 соответственно.

Изменено в версии 3.6: В качестве значения аргумента filename помимо строковых значений принимаются и объекты Path.

doRollover()

Выполняет переключение, как описано выше.

emit(record)

Выводит запись в файл, учитывая переключение, как описано ранее.

16.8.7. TimedRotatingFileHandler

Класс TimedRotatingFileHandler, расположенный в модуле logging.handlers, поддерживает вращение файлов журналов на диске через определенные интервалы времени.

class logging.handlers.TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None)

Возвращает новый экземпляр класса TimedRotatingFileHandler. Указанный файл открывается и используется в качестве потока для ведения журнала. При вращении также устанавливается суффикс имени файла. Вращение происходит на основе произведения when и interval.

Вы можете использовать when для указания типа interval. Список возможных значений приведен ниже. Обратите внимание, что они не чувствительны к регистру.

Значение	Тип интервала	Если/как используется atTime
'S'	Секунды	Игнорируется
'M'	Минуты	Игнорируется
'H'	Часы	Игнорируется
'D'	Дни	Игнорируется
'W0'-'W6'	День недели (0=Понедельник)	Используется для вычисления начального времени переключения
'midnight'	Переключение в полночь, если atTime не указано, иначе в atTime	Используется для вычисления начального времени переключения

При использовании вращения, основанного на дне недели, укажите ‘W0’ для понедельника, ‘W1’ для вторника и так далее до ‘W6’ для воскресенья. В этом случае переданное значение для interval не используется.

Система сохранит старые файлы логов, добавив расширения к имени файла. Расширения основаны на дате и времени, используя формат strftime %Y-%m-%d_%H-%M-%S или его часть, в зависимости от интервала переключения.

При вычислении следующего времени переключения в первый раз (при создании обработчика) используется последнее время изменения существующего файла журнала или текущее время для вычисления времени следующего переключения.

Если аргумент utc равен true, будут использоваться времена UTC; в противном случае используется местное время.

Если backupCount не равно нулю, будет сохранено не более backupCount файлов, а если при переключении будет создано больше, то самый старый из них будет удален. Логика удаления использует интервал для определения файлов, которые необходимо удалить, поэтому изменение интервала может оставить старые файлы.

Если delay равно true, то открытие файла откладывается до первого вызова emit().

Если atTime не None, он должен быть экземпляром datetime.time, который указывает время суток, когда происходит переключение, в случаях, когда переключение задано на «полночь» или «в определенный день недели». Обратите внимание, что в этих случаях значение atTime используется для вычисления начального переключения, а последующие переключения будут рассчитываться с использованием обычного вычисления интервала.

Примечание

Вычисление начального времени переключения выполняется при инициализации обработчика. Вычисление последующих времен переключения выполняется только при возникновении переключения, а переключение происходит только при выводе вывода. Если это не учитывать, это может привести к путанице. Например, если задан интервал «каждую минуту», это не означает, что вы всегда будете видеть файлы логов с временами (в имени файла), разделенными минутой; если во время выполнения приложения генерируется вывод журнала чаще, чем раз в минуту, тогда вы можете ожидать увидеть файлы логов с временами, разделенными минутой. С другой стороны, если сообщения журнала выводятся только один раз в пять минут (скажем), то в временах файлов будут пробелы, соответствующие минутам, в которые не было вывода (и, следовательно, не было переключения).

Изменено в версии 3.4: Параметр atTime был добавлен.

Изменено в версии 3.6: Помимо строковых значений, для аргумента filename также принимаются объекты Path.

doRollover()

Производит переключение, как описано выше.

emit(record)

Выводит запись в файл, учитывая переключение, как описано выше.

16.8.8. Обработчик сокета

Класс SocketHandler, расположенный в модуле logging.handlers, отправляет вывод журнала в сокет сети. Базовый класс использует TCP-сокет.

class logging.handlers.SocketHandler(host, port)

Возвращает новый экземпляр класса SocketHandler, предназначенный для связи с удаленной машиной, адрес которой задан параметрами host и port.

Изменено в версии 3.4: Если port указано как None, создается сокет Unix-доменного сокета, используя значение в host - в противном случае создается TCP-сокет.

close()

Закрывает сокет.

emit()

Сериализует словарь атрибутов записи с помощью протокола pickle и записывает его в сокет в двоичном формате. Если возникла ошибка с сокетом, пакет отбрасывается без предупреждения. Если соединение ранее было потеряно, соединение восстанавливается. Чтобы десериализовать запись в приемнике в LogRecord, используйте функцию makeLogRecord().

handleError()

Обрабатывает ошибку, возникшую во время emit(). Наиболее вероятной причиной является потерянное соединение. Закрывает сокет, чтобы мы могли повторить попытку при следующем событии.

makeSocket()

Это фабричный метод, который позволяет подклассам определять точный тип сокета, который они хотят. По умолчанию реализация создает TCP-сокет (socket.SOCK_STREAM).

makePickle(record)

Сериализует словарь атрибутов записи в двоичном формате с префиксом длины и возвращает его, готовый для передачи по сокету.

Обратите внимание, что протокол pickle не полностью безопасен. Если вы беспокоитесь о безопасности, вы можете переопределить этот метод, чтобы реализовать более безопасный механизм. Например, вы можете подписать pickle с помощью HMAC, а затем проверить их на принимающей стороне, или, как вариант, вы можете отключить десериализацию глобальных объектов на принимающей стороне.

send(packet)

Отправляет закодированную строку packet в сокет. Эта функция позволяет осуществлять частичные отправки, что может происходить при загруженной сети.

createSocket()

Пытается создать сокет; при неудаче использует алгоритм экспоненциального замедления. При первой неудаче обработчик отбросит сообщение, которое пытался отправить. При обработке последующих сообщений тем же экземпляром он не будет пытаться подключиться, пока не пройдет некоторое время. Значения параметров по умолчанию такие, что начальная задержка составляет одну секунду, и если по истечении этой задержки соединение всё ещё не установлено, обработчик будет удваивать задержку каждый раз до максимального значения в 30 секунд.

Это поведение контролируется следующими атрибутами обработчика:

• retryStart (начальная задержка, по умолчанию 1,0 секунды).
• retryFactor (множитель, по умолчанию 2,0).
• retryMax (максимальная задержка, по умолчанию 30,0 секунд).

Это означает, что если удаленный слушатель запускается после того, как обработчик был использован, вы можете потерять сообщения (так как обработчик не будет даже пытаться установить соединение, пока не истечет задержка, но просто будет молча отбрасывать сообщения в течение периода задержки).

16.8.9. Обработчик датаграмм

Класс DatagramHandler, расположенный в модуле logging.handlers, наследуется от SocketHandler, чтобы поддерживать отправку сообщений журнала через UDP-сокеты.

class logging.handlers.DatagramHandler(host, port)

Возвращает новый экземпляр класса DatagramHandler, предназначенного для связи с удалённой машиной по адресу host и port.

Изменено в версии 3.4: Если port задано как None, создаётся Unix-сокет доменного типа, используя значение из host - в противном случае создаётся UDP-сокет.

emit()

Сериализует словарь атрибутов записи и записывает его в сокет в двоичном формате. Если возникнет ошибка с сокетом, пакет будет проигнорирован. Для десериализации записи на стороне получателя в LogRecord используйте функцию makeLogRecord().

makeSocket()

Здесь переопределён фабричный метод класса SocketHandler для создания UDP-сокета (socket.SOCK_DGRAM).

send(s)

Отправляет сериализованную строку в сокет.

16.8.10. SysLogHandler

Класс SysLogHandler из модуля logging.handlers поддерживает отправку сообщений логирования на удалённый или локальный Unix syslog.

class logging.handlers.SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM)

Возвращает новый экземпляр класса SysLogHandler, предназначенного для связи с удалённой Unix-машиной по адресу, указанному в кортеже address. Если address не указан, используется ('localhost', 514). Адрес используется для открытия сокета. В качестве альтернативы кортежу (host, port) можно указать адрес как строку, например ‘/dev/log’. В этом случае используется Unix-сокет доменного типа для отправки сообщения в syslog. Если facility не задан, используется LOG_USER. Тип открытого сокета зависит от аргумента socktype, который по умолчанию равен socket.SOCK_DGRAM, открывая UDP-сокет. Для открытия TCP-сокета (для использования с более новыми syslog-демонами, такими как rsyslog), укажите значение socket.SOCK_STREAM.

Обратите внимание, что если ваш сервер не прослушивает порт UDP 514, SysLogHandler может не работать. В этом случае проверьте, какой адрес вы должны использовать для сокета доменного типа - это зависит от системы. Например, в Linux обычно это ‘/dev/log’, а в OS/X - ‘/var/run/syslog’. Вам нужно проверить свою платформу и использовать соответствующий адрес (возможно, вам придётся делать эту проверку во время выполнения, если ваше приложение должно работать на нескольких платформах). В Windows, по большей части, нужно использовать UDP-вариант.

Изменено в версии 3.2: Добавлен параметр socktype.

close()

Закрывает сокет с удалённым хостом.

emit(record)

Запись форматируется и отправляется на сервер syslog. Если присутствует информация об исключении, она не отправляется на сервер.

Изменено в версии 3.2.1: (См.: bpo-12168.) В более ранних версиях сообщение, отправляемое syslog-демонам, всегда завершалось байтом NUL, потому что ранние версии этих демонов ожидали NUL-завершённое сообщение - даже несмотря на то, что это не соответствует соответствующему стандарту (RFC 5424). Более поздние версии этих демонов не ожидают байт NUL, но удаляют его, если он есть, а ещё более новые демоны (которые более точно соответствуют RFC 5424) передают байт NUL как часть сообщения.

Чтобы упростить обработку сообщений syslog при различных поведении демонов, добавление байта NUL стало настраиваемым через атрибут класса append_nul. По умолчанию он равен True (сохраняя предыдущее поведение), но может быть установлен в False для экземпляра SysLogHandler, чтобы этот экземпляр не добавлял завершающий NUL.

Изменено в версии 3.3: (См.: bpo-12419.) В предыдущих версиях не было возможности для префикса «ident» или «tag» для идентификации источника сообщения. Теперь это можно указать с помощью атрибута класса, по умолчанию равного "" для сохранения предыдущего поведения, но который может быть изменён для экземпляра SysLogHandler, чтобы этот экземпляр добавлял префикс ident к каждому обработанному сообщению. Обратите внимание, что предоставленный ident должен быть строкой, а не байтами, и он добавляется к сообщению в точности таком виде.

encodePriority(facility, priority)

Кодирует facility и priority в целое число. Вы можете передавать строки или целые числа - если передаются строки, используются внутренние словари сопоставлений для их преобразования в целые числа.

Символьные значения LOG_ определены в SysLogHandler и отражают значения, определённые в заголовке sys/syslog.h.

Уровни приоритета

Имя (строка)	Символическое значение
alert	LOG_ALERT
crit или critical	LOG_CRIT
debug	LOG_DEBUG
emerg или panic	LOG_EMERG
err или error	LOG_ERR
info	LOG_INFO
notice	LOG_NOTICE
warn или warning	LOG_WARNING

Facility

Имя (строка)	Символическое значение
auth	LOG_AUTH
authpriv	LOG_AUTHPRIV
cron	LOG_CRON
daemon	LOG_DAEMON
ftp	LOG_FTP
kern	LOG_KERN
lpr	LOG_LPR
mail	LOG_MAIL
news	LOG_NEWS
syslog	LOG_SYSLOG
user	LOG_USER
uucp	LOG_UUCP
local0	LOG_LOCAL0
local1	LOG_LOCAL1
local2	LOG_LOCAL2
local3	LOG_LOCAL3
local4	LOG_LOCAL4
local5	LOG_LOCAL5
local6	LOG_LOCAL6
local7	LOG_LOCAL7

mapPriority(levelname)

Преобразует имя уровня логирования в имя приоритета syslog. Вам может потребоваться переопределить эту функцию, если вы используете пользовательские уровни или если стандартный алгоритм не подходит для ваших нужд. По умолчанию алгоритм преобразует DEBUG, INFO, WARNING, ERROR и CRITICAL в эквивалентные имена syslog, а все остальные имена уровней в ‘warning’.

16.8.11. NTEventLogHandler

Класс NTEventLogHandler из модуля logging.handlers поддерживает отправку сообщений логирования в локальный журнал событий Windows NT, Windows 2000 или Windows XP. Для его использования вам необходимо установить расширения Win32 для Python от Марка Хаммонда.

class logging.handlers.NTEventLogHandler(appname, dllname=None, logtype='Application')

Возвращает новый экземпляр класса NTEventLogHandler. Параметр appname используется для определения имени приложения в журнале событий. Используя это имя, создается соответствующая запись в реестре. Параметр dllname должен содержать полное имя файла .dll или .exe, содержащего определения сообщений для хранения в журнале (если не указано, используется 'win32service.pyd' — этот файл установлен с расширениями Win32 и содержит некоторые базовые определения местодержателей сообщений. Обратите внимание, что использование этих местодержателей сделает ваши журналы событий большими, поскольку в журнале хранится весь источник сообщения. Если вам нужны более компактные журналы, вы должны передать имя собственного файла .dll или .exe, содержащего определения сообщений, которые вы хотите использовать в журнале событий). Параметр logtype может принимать значения 'Application', 'System' или 'Security', по умолчанию — 'Application'.

close()

На этом этапе вы можете удалить имя приложения из реестра в качестве источника записей журнала событий. Однако, если вы это сделаете, вы не сможете увидеть события так, как предполагалось в просмотре событий — ему необходимо получить доступ к реестру для получения имени .dll. Текущая версия этого не делает.

emit(record)

Определяет идентификатор сообщения, категорию события и тип события, а затем записывает сообщение в журнал событий NT.

getEventCategory(record)

Возвращает категорию события для записи. Переопределите этот метод, если хотите указать свои собственные категории. Эта версия возвращает 0.

getEventType(record)

Возвращает тип события для записи. Переопределите этот метод, если хотите указать свои собственные типы. Эта версия выполняет сопоставление, используя атрибут typemap обработчика, который настроен в __init__() в словарь, который содержит сопоставления для DEBUG, INFO, WARNING, ERROR и CRITICAL. Если вы используете свои собственные уровни, вам нужно будет либо переопределить этот метод, либо поместить подходящий словарь в атрибут typemap обработчика.

getMessageID(record)

Возвращает идентификатор сообщения для записи. Если вы используете собственные сообщения, вы можете сделать это, сделав msg, переданный в логгер, ID, а не строкой формата. Затем здесь вы могли бы использовать поиск в словаре для получения идентификатора сообщения. Эта версия возвращает 1, что является базовым идентификатором сообщения в win32service.pyd.

16.8.12. SMTPHandler

Класс SMTPHandler, расположенный в модуле logging.handlers, поддерживает отправку сообщений журналов на адрес электронной почты по протоколу SMTP.

class logging.handlers.SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0)

Возвращает новый экземпляр класса SMTPHandler. Экземпляр инициализируется адресами отправителя и получателя, а также строкой темы электронного письма. Параметр toaddrs должен быть списком строк. Для указания нестандартного порта SMTP используйте формат кортежа (host, port) для аргумента mailhost. Если вы используете строку, используется стандартный порт SMTP. Если ваш SMTP-сервер требует аутентификации, вы можете указать кортеж (имя пользователя, пароль) для аргумента credentials.

Для указания использования защищённого протокола (TLS) передайте кортеж в аргумент secure. Это будет использоваться только при наличии учетных данных аутентификации. Кортеж должен быть либо пустым кортежем, либо кортежем с одним значением — именем файла ключа, или кортежем из двух значений с именами файла ключа и файла сертификата. (Этот кортеж передаётся методу smtplib.SMTP.starttls().)

Таймаут для связи с SMTP-сервером может быть задан с помощью аргумента timeout.

Добавлена в версии 3.3: Аргумент timeout был добавлен.

emit(record)

Форматирует запись и отправляет её указанным получателям.

getSubject(record)

Если вы хотите указать строку темы, зависящую от записи, переопределите этот метод.

16.8.13. MemoryHandler

Класс MemoryHandler, расположенный в модуле logging.handlers, поддерживает буферизацию записей журналов в памяти, периодически очищая их в обработчик target. Очистка происходит всякий раз, когда буфер заполняется или когда наблюдается событие определённой или большей степени серьёзности.

MemoryHandler является подклассом более общего класса BufferingHandler, который является абстрактным классом. Он буферизует записи журналов в памяти. Всякий раз, когда запись добавляется в буфер, производится проверка, вызывая shouldFlush(), чтобы определить, следует ли очищать буфер. Если следует, то ожидается, что flush() выполнит эту очистку.

class logging.handlers.BufferingHandler(capacity)

Инициализирует обработчик с буфером заданной ёмкости.

emit(record)

Добавляет запись в буфер. Если shouldFlush() возвращает true, вызывает flush() для обработки буфера.

flush()

Вы можете переопределить его, чтобы реализовать пользовательское поведение очистки. Эта версия просто очищает буфер.

shouldFlush(record)

Возвращает true, если буфер заполнен. Этот метод можно переопределить, чтобы реализовать пользовательские стратегии очистки.

class logging.handlers.MemoryHandler(capacity, flushLevel=ERROR, target=None, flushOnClose=True)

Возвращает новый экземпляр класса MemoryHandler. Экземпляр инициализируется размером буфера capacity. Если flushLevel не указан, используется ERROR. Если target не указан, необходимо установить целевой обработчик с помощью setTarget(), прежде чем этот обработчик будет выполнять полезную работу. Если flushOnClose задан как False, буфер не очищается при закрытии обработчика. Если не указан или указан как True, то будет выполняться предыдущее поведение — очистка буфера при закрытии обработчика.

Изменено в версии 3.6: Параметр flushOnClose был добавлен.

close()

Вызывает flush(), устанавливает целевой обработчик на None и очищает буфер.

flush()

Для MemoryHandler, очистка означает просто отправку буферизованных записей в целевой обработчик, если он есть. Буфер также очищается в этом случае. Переопределите, если требуется другое поведение.

setTarget(target)

Устанавливает целевой обработчик для данного обработчика.

shouldFlush(record)

Проверяет буфер на заполненность или наличие записи с уровнем flushLevel или выше.

16.8.14. HTTPHandler

Класс HTTPHandler, расположенный в модуле logging.handlers, поддерживает отправку сообщений журналов на веб-сервер, используя либо GET или POST семантику.

class logging.handlers.HTTPHandler(host, url, method='GET', secure=False, credentials=None, context=None)

Возвращает новый экземпляр класса HTTPHandler. Параметр host может иметь вид host:port, если необходимо использовать определённый номер порта. Если параметр method не указан, используется значение GET. Если параметр secure имеет значение True, будет использовано HTTPS-соединение. Параметр context может быть установлен в экземпляр ssl.SSLContext для настройки параметров SSL, используемых для HTTPS-соединения. Если указан параметр credentials, он должен быть 2-кортежем, содержащим имя пользователя и пароль, которые будут помещены в заголовок HTTP «Authorization» с использованием аутентификации по основанию. Если вы указываете учетные данные, вы также должны указать secure=True, чтобы ваши имя пользователя и пароль не передавались в открытом виде по сети.

Изменено в версии 3.5: Добавлен параметр context.

mapLogRecord(record)

Возвращает словарь, основанный на record, который должен быть закодирован в URL и отправлен на веб-сервер. По умолчанию возвращается record.__dict__. Этот метод можно переопределить, например, если нужно отправить на веб-сервер только часть данных из объекта LogRecord, или если требуется более точная настройка данных, отправляемых на сервер.

emit(record)

Отправляет запись на веб-сервер в виде закодированного в URL словаря. Для преобразования записи в словарь для отправки используется метод mapLogRecord().

Примечание

Поскольку подготовка записи для отправки на веб-сервер отличается от операции общего форматирования, использование setFormatter() для указания Formatter для HTTPHandler не имеет эффекта. Вместо вызова format() данный обработчик вызывает mapLogRecord(), а затем urllib.parse.urlencode() для кодирования словаря в формате, подходящем для отправки на веб-сервер.

16.8.15. Обработчик очереди

Класс QueueHandler, расположенный в модуле logging.handlers, поддерживает отправку сообщений логирования в очередь, например, реализованных в модулях queue или multiprocessing.

Вместе с классом QueueListener, класс QueueHandler может использоваться для выполнения обработки событий логирования в отдельном потоке от потока, осуществляющего запись. Это важно в веб-приложениях и других сервисных приложениях, где потоки, обслуживающие клиентов, должны реагировать как можно быстрее, в то время как любые потенциально медленные операции (например, отправка письма через SMTPHandler) выполняются в отдельном потоке.

class logging.handlers.QueueHandler(queue)

Возвращает новый экземпляр класса QueueHandler. Экземпляр инициализируется очередью для отправки сообщений. Очередь может быть любым объектом, похожим на очередь; он используется как есть методом enqueue(), которому необходимо знать, как отправлять сообщения в неё.

emit(record)

Добавляет результат подготовки записи логирования в очередь.

prepare(record)

Подготавливает запись для добавления в очередь. Объект, возвращаемый этим методом, добавляется в очередь.

Базовая реализация форматирует запись для объединения сообщения и аргументов, а также удаляет неупаковываемые элементы из записи на месте.

Вы можете переопределить этот метод, если хотите преобразовать запись в словарь или строку JSON, или отправить изменённую копию записи, оставив исходную запись неизменённой.

enqueue(record)

Добавляет запись в очередь с использованием put_nowait(); вы можете переопределить этот метод, если хотите использовать блокирующее поведение, таймаут или настраиваемую реализацию очереди.

16.8.16. Прослушиватель очереди

Класс QueueListener, расположенный в модуле logging.handlers, поддерживает получение сообщений логирования из очереди, например, реализованных в модулях queue или multiprocessing. Сообщения получаются из очереди в внутреннем потоке и передаются в том же потоке одному или нескольким обработчикам для обработки. Хотя QueueListener сам по себе не является обработчиком, он документирован здесь, потому что работает в паре с QueueHandler.

Вместе с классом QueueHandler, класс QueueListener может использоваться для выполнения обработки событий логирования в отдельном потоке от потока, осуществляющего запись. Это важно в веб-приложениях и других сервисных приложениях, где потоки, обслуживающие клиентов, должны реагировать как можно быстрее, в то время как любые потенциально медленные операции (например, отправка письма через SMTPHandler) выполняются в отдельном потоке.

class logging.handlers.QueueListener(queue, *handlers, respect_handler_level=False)

Возвращает новый экземпляр класса QueueListener. Экземпляр инициализируется очередью для отправки сообщений и списком обработчиков, которые будут обрабатывать записи, помещённые в очередь. Очередь может быть любым объектом, похожим на очередь; она передаётся в метод dequeue() без изменений, который должен знать, как извлекать сообщения из неё. Если respect_handler_level равно True, уровень обработчика учитывается (сравнивается с уровнем сообщения) при решении, передавать ли сообщения этому обработчику; в противном случае поведение соответствует предыдущим версиям Python — каждый раз передавать каждое сообщение каждому обработчику.

Изменено в версии 3.5: Добавлен аргумент respect_handler_levels.

dequeue(block)

Извлекает запись и возвращает её, при необходимости блокируя.

Базовая реализация использует get(). Вы можете переопределить этот метод, если хотите использовать таймауты или работать с пользовательскими реализациями очереди.

prepare(record)

Подготавливает запись к обработке.

Эта реализация просто возвращает переданную запись. Вы можете переопределить этот метод, если необходимо выполнить пользовательскую сериализацию или манипуляции с записью перед передачей её обработчикам.

handle(record)

Обрабатывает запись.

Это просто перебирает обработчики, предлагая им запись для обработки. Фактический объект, передаваемый обработчикам, — это тот, который возвращается из prepare().

start()

Запускает слушатель.

Это запускает фоновый поток для мониторинга очереди на наличие записей журнала для обработки.

stop()

Останавливает слушателя.

Это просит поток завершиться и затем ожидает его завершения. Обратите внимание, что если вы не вызываете этот метод перед выходом приложения, некоторые записи могут остаться в очереди и не будут обработаны.

enqueue_sentinel()

Записывает контрольный объект в очередь, чтобы сообщить слушателю о необходимости завершения. Эта реализация использует put_nowait(). Вы можете переопределить этот метод, если хотите использовать таймауты или работать с пользовательскими реализациями очереди.

Новое в версии 3.3.