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

StreamHandler

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

class logging.StreamHandler(stream=None)

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

emit(record)

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

flush()

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

setStream(stream)

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

Параметры:

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

Возвращает:

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

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

terminator

Строка, используемая в качестве завершающего символа при записи отформатированной записи в поток. Значение по умолчанию — '\n'.

Если завершающий символ новой строки не нужен, атрибут экземпляра обработчика terminator можно установить в пустую строку.

В предыдущих версиях завершающий символ был жестко задан как '\n'.

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

FileHandler

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

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

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

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

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

close()

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

emit(record)

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

Обратите внимание: если файл был закрыт при завершении журналирования и режим файла — ‘w’, запись не будет выведена (см. bpo-42378).

NullHandler

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

class logging.NullHandler

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

emit(record)

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

handle(record)

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

createLock()

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

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

WatchedFileHandler

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

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

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

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

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

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

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

reopenIfNeeded()

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

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

emit(record)

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

BaseRotatingHandler

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

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

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

namer

Если этому атрибуту присвоен вызываемый объект, метод rotation_filename() делегирует ему выполнение. Вызываемому объекту передаются те же параметры, что и rotation_filename().

Примечание

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

При использовании namer также важно сохранять в имени файла определенные атрибуты, используемые при ротации. Например, RotatingFileHandler ожидает набор файлов журналов, имена которых содержат последовательные целые числа, чтобы ротация работала как задумано, а TimedRotatingFileHandler удаляет старые файлы журналов (на основе параметра backupCount, переданного конструктору обработчика), определяя, какие файлы являются самыми старыми. Для этого имена файлов должны сортироваться по содержащейся в них дате/времени, и namer должен это учитывать. (Если требуется namer, который не следует этой схеме, его нужно использовать в подклассе TimedRotatingFileHandler, переопределяющем метод getFilesToDelete() в соответствии с пользовательской схемой именования.)

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

rotator

Если этому атрибуту присвоен вызываемый объект, метод rotate() делегирует ему выполнение. Вызываемому объекту передаются те же параметры, что и rotate().

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

rotation_filename(default_name)

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

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

Реализация по умолчанию вызывает атрибут ‘namer’ обработчика, если он является вызываемым объектом, и передает ему имя по умолчанию. Если атрибут не является вызываемым объектом (по умолчанию это None), имя возвращается без изменений.

Параметры:

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

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

rotate(source, dest)

Выполняет ротацию текущего журнала.

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

Параметры:

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

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

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

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

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

RotatingFileHandler

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

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

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

Параметры 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.

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

doRollover()

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

emit(record)

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

shouldRollover(record)

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

TimedRotatingFileHandler

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

class logging.handlers.TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None, errors=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 фактически используется для вычисления времени первой ротации, а последующие ротации рассчитываются обычным способом с учетом интервала.

Если указан параметр errors, он используется для определения способа обработки ошибок кодирования.

Примечание

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

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

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

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

doRollover()

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

emit(record)

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

getFilesToDelete()

Возвращает список имен файлов, которые следует удалить при ротации. Эти

shouldRollover(record)

Проверяет, прошло ли достаточно времени для выполнения ротации, и, если да, вычисляет время следующей ротации.

SocketHandler

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

class logging.handlers.SocketHandler(host, port)

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

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

close()

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

emit()

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

handleError()

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

makeSocket()

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

makePickle(record)

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

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

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

send(packet)

Отправляет сериализованный с помощью pickle байтовый блок 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.

Примечание

Поскольку UDP не является потоковым протоколом, между экземпляром этого обработчика и host нет постоянного соединения. Поэтому при использовании сетевого сокета при регистрации каждого события может потребоваться поиск DNS, что способно вызвать задержку в работе системы. Если это представляет для вас проблему, можно самостоятельно выполнить поиск и инициализировать обработчик с найденным IP-адресом вместо имени хоста.

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

emit()

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

makeSocket()

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

send(s)

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

SysLogHandler

Класс SysLogHandler, расположенный в модуле logging.handlers, обеспечивает отправку журнальных сообщений в удалённую или локальную систему syslog 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». В этом случае для отправки сообщения в 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.

Примечание

В macOS 12.x (Monterey) Apple изменила поведение своего демона syslog: теперь он не прослушивает доменный сокет. Поэтому не следует ожидать, что SysLogHandler будет работать в этой системе.

Дополнительные сведения см. в gh-91070.

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

close()

Закрывает сокет, соединённый с удалённым узлом.

createSocket()

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

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

emit(record)

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

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

Чтобы упростить обработку сообщений syslog с учётом различий в поведении демонов, добавление байта NUL сделано настраиваемым с помощью атрибута уровня класса append_nul. По умолчанию он равен True (сохраняя прежнее поведение), но для экземпляра SysLogHandler его можно установить в False, чтобы этот экземпляр не добавлял завершающий байт 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 от Mark Hammond.

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, используйте для аргумента mailhost кортеж (host, port). Если передана строка, используется стандартный порт SMTP. Если SMTP-сервер требует аутентификации, для аргумента credentials можно указать кортеж (username, password).

Чтобы использовать защищённый протокол (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)

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

emit(record)

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

flush()

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

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

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

mapLogRecord(record)

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

emit(record)

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

Примечание

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

QueueHandler

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

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

class logging.handlers.QueueHandler(queue)

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

Примечание

При использовании multiprocessing следует избегать SimpleQueue и вместо него использовать multiprocessing.Queue.

Предупреждение

Модуль multiprocessing использует внутренний регистратор, создаваемый и доступный через get_logger(). multiprocessing.Queue записывает сообщения уровня DEBUG при добавлении элементов в очередь. Если эти сообщения журнала обрабатываются QueueHandler, использующим тот же экземпляр multiprocessing.Queue, это приведёт к взаимной блокировке или бесконечной рекурсии.

emit(record)

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

prepare(record)

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

Базовая реализация форматирует запись, объединяя сообщение, аргументы, сведения об исключении и стеке, если они присутствуют. Кроме того, она на месте удаляет из записи объекты, которые нельзя сериализовать с помощью pickle. В частности, она перезаписывает атрибуты записи msg и message объединённым сообщением (полученным вызовом метода format() обработчика), а атрибутам args, exc_info и exc_text присваивает значение None.

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

Примечание

Базовая реализация форматирует сообщение с аргументами, присваивает атрибутам message и msg отформатированное сообщение, а атрибутам args и exc_text — значение None, чтобы разрешить сериализацию с помощью pickle и предотвратить повторные попытки форматирования. Это означает, что обработчику на стороне QueueListener не будут доступны данные для пользовательского форматирования, например сведений об исключениях. Можно создать подкласс QueueHandler и переопределить этот метод, например, чтобы не присваивать exc_text значение None. Обратите внимание, что изменения message / msg / args необходимы для обеспечения возможности сериализации записи с помощью pickle. Возможно, вам удастся избежать этих изменений, а возможно, и нет — это зависит от того, допускают ли ваши args такую сериализацию. (Учтите, что следует принимать во внимание не только собственный код, но и код используемых библиотек.)

enqueue(record)

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

listener

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

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

QueueListener

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

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

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

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

Примечание

При использовании multiprocessing следует избегать SimpleQueue и вместо него использовать multiprocessing.Queue.

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

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

dequeue(block)

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

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

prepare(record)

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

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

handle(record)

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

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

start()

Запускает прослушиватель.

Запускает фоновый поток, который отслеживает очередь и обрабатывает находящиеся в ней объекты LogRecord.

Изменено в версии 3.13.4: Вызывает RuntimeError, если метод вызван, когда прослушиватель уже работает.

stop()

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

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

enqueue_sentinel()

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

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