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

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().

setStream(stream)

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

Параметры

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

Возвращает

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

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

FileHandler

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

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

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

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

close()

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

emit(record)

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

NullHandler

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

class logging.NullHandler

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

emit(record)

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

handle(record)

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

createLock()

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

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

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

Класс 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 истинно, открытие файла откладывается до первого вызова emit(). По умолчанию, файл растет неограниченно.

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

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)

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

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

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

Параметры

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

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

rotate(source, dest)

При вращении вращает текущий журнал.

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

Параметры

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

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

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

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

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

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

Класс 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: Помимо строковых значений, объекты Path также принимаются в качестве аргумента filename.

doRollover()

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

emit(record)

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

Обработчик файлов с периодической ротацией

Класс 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, расположенный в модуле 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, расположенный в модуле 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().

Обработчик SysLog

Класс 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 используется сокет Unix-доменного сокета. Если 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

Утилиты

Имя (строка)	Символическое значение
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’.

Обработчик журнала событий NT

Класс 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 в виде идентификатора, а не строку форматирования. Тогда здесь можно использовать поиск в словаре для получения идентификатора сообщения. Эта версия возвращает 1, что является базовым идентификатором сообщения в win32service.pyd.

Обработчик SMTP

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

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

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

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

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

Новое в версии 3.3: Добавлен параметр timeout.

emit(record)

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

getSubject(record)

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

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

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

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

class logging.handlers.BufferingHandler(capacity)

Инициализирует обработчик с буфером заданной емкости. Здесь 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 или выше.

Обработчик HTTP

Класс 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, расположенный в модуле 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()

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

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

stop()

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

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

enqueue_sentinel()

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

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