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)

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

Parameters:

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

Returns:

предыдущий поток, если поток был изменен, или 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, расположенный в модуле logging.handlers, является FileHandler , который отслеживает файл, в который ведется протоколирование. Если файл меняется, он закрывается и открывается заново с использованием имени файла.

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

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

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

reopenIfNeeded()

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

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

emit(record)

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

Базовый обработчик вращения

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

Параметры:

• source – Имя исходного файла. Обычно это базовое имя файла, например, ‘test.log’.
• dest – Имя целевого файла. Обычно в это имя переименовывается source, например, ‘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, чтобы разрешить файлу перезапись (rollover) при достижении определённого размера. Когда размер приближается к пределу maxBytes, файл закрывается, и новый файл молча открывается для вывода. Перезапись происходит всякий раз, когда текущий файл лога приближается к размеру 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()

Производит перезапись (rollover), как описано выше.

emit(record)

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

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

Производит перезапись (rollover), как описано выше.

emit(record)

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

getFilesToDelete()

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

Обработчик сокета

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

class logging.handlers.SocketHandler(host, port)

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

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

close()

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

emit()

Сериализует (pickle) словарь атрибутов записи и записывает его в сокет в двоичном формате. Если возникнет ошибка с сокетом, пакет будет тихо сброшен. Если соединение было ранее потеряно, восстанавливается соединение. Для десериализации (unpickle) записи на стороне приёма в 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) не полностью безопасна. Если вы обеспокоены безопасностью, вы можете переопределить этот метод, чтобы реализовать более безопасный механизм. Например, вы можете подписать сериализованные данные с помощью HMAC и затем проверить их на принимающей стороне, или, как вариант, вы можете отключить распаковку глобальных объектов на принимающей стороне.

send(packet)

Отправка сериализованной (pickle) битовой строки 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.

Примечание

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

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

emit()

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

makeSocket()

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

send(s)

Отправка сериализованной (pickle) битовой строки в сокет. Формат отправляемой битовой строки описан в документации для 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’. В этом случае используется сокет 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.

Примечание

В 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 (сохраняя предыдущее поведение), но может быть установлено в False для экземпляра SysLogHandler для того, чтобы этот экземпляр не добавлял терминатор NUL.

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

encodePriority(facility, priority)

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

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

Приоритеты

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

Установки

Имя (строка)	Символическое значение
auth	LOG_AUTH
authpriv	LOG_AUTHPRIV
cron	LOG_CRON
daemon	LOG_DAEMON
ftp	LOG_FTP
kern	LOG_KERN
lpr	LOG_LPR
mail	LOG_MAIL
news	LOG_NEWS
syslog	LOG_SYSLOG
user	LOG_USER
uucp	LOG_UUCP
local0	LOG_LOCAL0
local1	LOG_LOCAL1
local2	LOG_LOCAL2
local3	LOG_LOCAL3
local4	LOG_LOCAL4
local5	LOG_LOCAL5
local6	LOG_LOCAL6
local7	LOG_LOCAL7

mapPriority(levelname)

Сопоставляет имя уровня логирования с именем приоритета syslog. Возможно, вам потребуется переопределить это, если вы используете пользовательские уровни или если алгоритм по умолчанию не подходит для ваших потребностей. Алгоритм по умолчанию сопоставляет DEBUG, INFO, WARNING, ERROR и CRITICAL с эквивалентными именами syslog, а все остальные имена уровней с ‘warning’.

NTEventLogHandler

Класс NTEventLogHandler, расположенный в модуле logging.handlers, поддерживает отправку сообщений логирования в локальный журнал событий Windows NT, Windows 2000 или Windows XP. Для его использования необходимы расширения Win32 для Python от Марка Хаммонда.

class logging.handlers.NTEventLogHandler(appname, dllname=None, logtype='Application')

Возвращает новый экземпляр класса NTEventLogHandler. Параметр appname используется для определения имени приложения в журнале событий. С помощью этого имени создаётся соответствующая запись в реестре. Параметр dllname должен содержать полное имя файла .dll или .exe, содержащего определения сообщений для хранения в журнале (если не указано, используется 'win32service.pyd', который установлен вместе с расширениями Win32 и содержит некоторые базовые определения замещающих сообщений. Обратите внимание, что использование этих заменителей сделает ваши журналы событий большими, так как весь исходный текст сообщения хранится в журнале. Если вы хотите более компактные журналы, вы должны указать имя собственного файла .dll или .exe, который содержит определения сообщений, которые вы хотите использовать в журнале событий). Параметр logtype может принимать значения 'Application', 'System' или 'Security', по умолчанию 'Application'.

close()

На этом этапе вы можете удалить имя приложения из реестра в качестве источника записей журнала событий. Однако, если вы сделаете это, вы не сможете видеть события так, как предполагалось в Просмотрщике журналов событий — ему необходимо иметь доступ к реестру для получения имени .dll. Текущая версия этого не делает.

emit(record)

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

getEventCategory(record)

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

getEventType(record)

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

getMessageID(record)

Возвращает идентификатор сообщения для записи. Если вы используете свои собственные сообщения, вы можете сделать это, передав в логгер значение msg как ID, а не строку форматирования. Затем в этом методе вы можете использовать поиск по словарю для получения идентификатора сообщения. Эта версия возвращает 1, что является базовым идентификатором сообщения в win32service.pyd.

SMTPHandler

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

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

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

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

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

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

emit(record)

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

getSubject(record)

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

MemoryHandler

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

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

class logging.handlers.BufferingHandler(capacity)

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

emit(record)

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

flush()

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

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

mapLogRecord(record)

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

emit(record)

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

Примечание

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

QueueHandler

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

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

class logging.handlers.QueueHandler(queue)

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

Примечание

Если вы используете multiprocessing, следует избегать использования SimpleQueue и вместо этого использовать multiprocessing.Queue.

emit(record)

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

prepare(record)

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

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

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

Примечание

Базовая реализация форматирует сообщение с аргументами, устанавливает атрибуты message и msg в отформатированное сообщение и устанавливает атрибуты args и exc_text в None, чтобы обеспечить сериализацию и предотвратить дальнейшие попытки форматирования. Это означает, что обработчик на стороне QueueListener не будет иметь информации для выполнения пользовательского форматирования, например, исключений. Вы можете захотеть создать подкласс QueueHandler и переопределить этот метод, чтобы, например, избежать установки exc_text в None. Обратите внимание, что изменения в message / msg / args связаны с обеспечением сериализуемости записи, и вы можете или не можете избежать этого в зависимости от того, являются ли ваши 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 отслеживания задач (хотя он используется, если доступен), что означает, что вы можете использовать экземпляры SimpleQueue для queue.

Примечание

Если вы используете multiprocessing, следует избегать использования SimpleQueue и вместо этого использовать multiprocessing.Queue.

Если 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.