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

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

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

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

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

setStream(stream)

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

Параметры

stream – Поток, который должен использовать обработчик.

Возвращает

предыдущий поток, если поток был изменен, или None, если нет.

В версии 3.7.

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

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

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

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

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

close()

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

emit(record)

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

Обработчик «Null»

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

class logging.NullHandler

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

emit(record)

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

handle(record)

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

createLock()

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

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

Обработчик отслеживания файла

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

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

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

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

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

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

reopenIfNeeded()

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

В версии 3.6.

emit(record)

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

Базовый обработчик ротации

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

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

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

В стандартной реализации вызывается атрибут ‘намер’ обработчика, если он вызываемый объект, передавая ему имя по умолчанию. Если атрибут не вызываемый объект (по умолчанию — 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 для настройки обработки вращения журнала.

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 истинно, то открытие файла откладывается до первого вызова метода 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)

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

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)

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

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)

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

data = pickle.dumps(record_attr_dict, 1)
datalen = struct.pack('>L', len(data))
return datalen + data

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

send(packet)

Отправляет сериализованную строку байтов packet в сокет. Формат отправленной строки байтов описан в документации для makePickle().

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

createSocket()

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

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

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

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

DatagramHandler

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

Отправка сериализованной строкой байтов в сокет. Формат отправляемых байтовых строк соответствует документации SocketHandler.makePickle().

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). Адрес используется для открытия сокета. Вместо кортежа address можно указать адрес в виде строки, например, ‘/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 для экземпляра класса, чтобы он не добавлял NUL-терминатор.

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

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, а все остальные имена уровней к ‘warning’.

NTEventLogHandler

Класс NTEventLogHandler из модуля logging.handlers поддерживает отправку сообщений логгирования в локальный журнал событий Windows NT, Windows 2000 или Windows XP. Для использования требуется пакет Win32 extensions for 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 в качестве идентификатора, а не строку форматирования. Затем здесь вы можете использовать поиск в словаре для получения идентификатора сообщения. Эта версия возвращает 1, который является базовым идентификатором сообщения в win32service.pyd.

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)

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

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 или выше.

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() для кодирования словаря в формате, подходящем для отправки на веб-сервер.

QueueHandler

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

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

class logging.handlers.QueueHandler(queue)

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

emit(record)

Добавляет результат подготовки записи LogRecord в очередь. Если произойдёт исключение (например, потому что ограниченная очередь заполнилась), вызывается метод handleError() для обработки ошибки. Это может привести к тому, что запись будет опущена (если logging.raiseExceptions равно False) или к выводу сообщения в sys.stderr (если logging.raiseExceptions равно True).

prepare(record)

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

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

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

enqueue(record)

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

QueueListener

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

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

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

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

Если respect_handler_level равно True, уровень обработчика учитывается (сравнивается с уровнем сообщения) при принятии решения о передаче сообщений данному обработчику; в противном случае поведение такое же, как в предыдущих версиях Python — каждый раз передавать каждое сообщение каждому обработчику.

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

dequeue(block)

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

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

prepare(record)

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

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

handle(record)

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

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

start()

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

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

enqueue_sentinel()

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

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

enqueue_sentinel()

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

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