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


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

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.

Изменено в версии 3.2: У класса StreamHandler теперь есть атрибут terminator, значение по умолчанию '\n', которое используется в качестве признака конца при записи форматированной записи в поток. Если вам не нужно завершение новой строки, вы можете установить для атрибута terminator экземпляра обработчика пустую строку. В более ранних версиях завершитель был жёстко запрограммирован как '\n'.

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

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

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

class logging.NullHandler

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

emit(record)

Метод ничего не делает.

handle(record)

Метод ничего не делает.

createLock()

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

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

WatchedFileHandler

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

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

reopenIfNeeded()

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

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

emit(record)

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

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 – Имя исходного файла. Обычно это база имени файла, например «test.log».
  • dest – Имя файла назначения. Нормально, если источник ротируется, например в «test.log.1».

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

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

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

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

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 истинен, будет использоваться время в формате UTC; в противном случае используется местное время.

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

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

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

Примечание

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

Изменено в версии 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

Обратите внимание, что пикли (pickles) не совсем безопасны. Если вас беспокоит безопасность, вы можете переопределить этот метод, чтобы реализовать более безопасный механизм. Например, вы можете подписать пикли с помощью 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.

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». В этом случае сокет домена Unix используется для отправки сообщения в syslog. Если facility не указан, используется LOG_USER. Тип открытого сокета зависит от аргумента socktype, у которого по умолчанию значение socket.SOCK_DGRAM и, таким образом, открывает UDP сокет. Чтобы открыть TCP сокет (для использования с новыми демонами syslog, такими как rsyslog), укажите значение socket.SOCK_STREAM.

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

Изменено в версии 3.2: Был добавлен socktype.

close()

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

emit(record)

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

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

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

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

encodePriority(facility, priority)

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

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

Приоритеты

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

Возможности

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

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

getEventCategory(record)

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

getEventType(record)

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

getMessageID(record)

Возвращает ID сообщения для записи. Если вы используете свои собственные сообщения, вы можете сделать это, передав регистратору msg ID, а не форматную строку. Затем здесь вы можете использовать поиск по словарю, чтобы получить ID сообщения. Версия возвращает 1, которая является базовым ID сообщения в 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, использовать формат кортежа (хост, порт) для аргумента mailhost. Если вы используете строку, используется стандартный порт SMTP. Если ваш SMTP-сервер требует аутентификации, вы можете указать кортеж (имя пользователя, пароль) для аргумента credentials.

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

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

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

emit(record)

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

getSubject(record)

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

MemoryHandler

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

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

class logging.handlers.BufferingHandler(capacity)

Инициализирует обработчик с буфером указанной ёмкости. Здесь capacity означает количество буферизованных записей журнала.

emit(record)

Добавить запись в буфер. Если shouldFlush() возвращает истину, вызвать 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 истинно, будет использоваться HTTPS-соединение. Параметр context может быть установлен на экземпляр ssl.SSLContext для настройки SSL параметров, используемых для HTTPS соединения. Если указан credentials, он должен быть кортежем из двух элементов, состоящий из идентификатора пользователя и пароля, который будет помещён в HTTP заголовок «Authorization» с использованием базовой проверки подлинности. Если вы указываете учётные данные, вы также должны указать secure=True, чтобы ваш идентификатор пользователя и пароль не передавались по сети в виде открытого текста.

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

mapLogRecord(record)

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

emit(record)

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

Примечание

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

QueueHandler

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

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

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

class logging.handlers.QueueHandler(queue)

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

emit(record)

Ставит в очередь результат подготовки LogRecord. В случае возникновения исключения (например, из-за заполнения ограниченной очереди) для обработки ошибки вызывается метод handleError(). Может привести к тому, что запись будет отброшена без уведомления (если logging.raiseExceptionsFalse) или сообщение будет напечатано в sys.stderr (если logging.raiseExceptionsTrue).

prepare(record)

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

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

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

enqueue(record)

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

QueueListener

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

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

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

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

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

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

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

dequeue(block)

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

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

prepare(record)

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

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

handle(record)

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

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

start()

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

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

stop()

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

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

enqueue_sentinel()

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

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

См.также

Модуль logging
Справочник по API для модуля logging.
Модуль logging.config
API конфигурации для модуля logging.