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

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

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

1. StreamHandler

Класс 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().

2. FileHandler

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

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

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

close()

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

emit(record)

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

3. NullHandler

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

class logging.NullHandler

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

emit(record)

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

handle(record)

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

createLock()

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

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

4. WatchedFileHandler

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

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

Этот обработчик не подходит для использования под 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(). По умолчанию файл растёт неограниченно.

emit(record)

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

5. BaseRotatingHandler

Класс 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 просто переименовывается в destination.

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

Введено в версии 3.3.

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

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

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

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», «.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 соответственно.

doRollover()

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

emit(record)

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

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. Список возможных значений приведён ниже. Обратите внимание, что регистр значения не важен.

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

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

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

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

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

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

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

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

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

doRollover()

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

emit(record)

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

8. SocketHandler

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

class logging.handlers.SocketHandler(host, port)

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

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

close()

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

emit()

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

handleError()

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

makeSocket()

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

makePickle(record)

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

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

send(packet)

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

createSocket()

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

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

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

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

9. DatagramHandler

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

class logging.handlers.DatagramHandler(host, port)

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

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

emit()

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

makeSocket()

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

send(s)

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

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 в формате кортежа (host, port). Если address не указан, используется ('localhost', 514). Этот адрес используется для открытия сокета. Вместо кортежа (host, port) можно указать адрес в виде строки, например, ‘/dev/log’. В этом случае используется сокет доменного типа для отправки сообщения в 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, чтобы он не добавлял нулевой терминатор.

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

encodePriority(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

Области

Имя (строка)	Символьное значение
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, а все остальные имена уровней в «предупреждение».

11. Обработчик NTEventLog

Класс 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.

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)

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

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)

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

close()

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

flush()

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

setTarget(target)

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

shouldFlush(record)

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

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, они должны быть кортежем из двух элементов: идентификатора пользователя и пароля, которые будут размещены в заголовке HTTP «Authorization» с использованием аутентификации Basic. Если вы указываете учетные данные, вы также должны указать secure=True, чтобы ваши идентификатор пользователя и пароль не передавались в открытом виде по сети.

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

mapLogRecord(record)

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

emit(record)

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

Примечание

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

15. QueueHandler

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

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

class logging.handlers.QueueHandler(queue)

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

emit(record)

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

prepare(record)

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

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

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

enqueue(record)

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

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.