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

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

Изменено в версии 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), имя возвращается без изменений.

Parameters

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

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

rotate(source, dest)

Вращение текущего журнала при вращении.

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

Parameters

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

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

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

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

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

Обработчик вращающихся файлов

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

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

Возвращает новый экземпляр класса RotatingFileHandler. Указанный файл открывается и используется в качестве потока для ведения журнала. Если mode не указан, используется 'a'. Если encoding не None, он используется для открытия файла с указанной кодировкой. Если delay истинно, то открытие файла откладывается до первого вызова 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: Кроме строковых значений, объекты Path также принимаются для аргумента filename.

Изменено в версии 3.9: Параметр errors был добавлен.

doRollover()

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

emit(record)

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

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

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

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

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

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

Примечание

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

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

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

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

doRollover()

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

emit(record)

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

getFilesToDelete()

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

SocketHandler

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

class logging.handlers.SocketHandler(host, port)

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

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

close()

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

emit()

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

handleError()

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

makeSocket()

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

makePickle(record)

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

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

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

send(packet)

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

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

createSocket()

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

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

• retryStart (начальная задержка, по умолчанию 1,0 секунда).
• retryFactor (множитель, по умолчанию 2,0).
• retryMax (максимальная задержка, по умолчанию 30,0 секунд).

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

DatagramHandler

Класс DatagramHandler, расположенный в модуле logging.handlers, наследуется от SocketHandler для поддержки отправки сообщений регистрации по UDP-сокетам.

class logging.handlers.DatagramHandler(host, port)

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

Примечание

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

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

emit()

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

makeSocket()

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

send(s)

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

Обработчик SysLog

Класс SysLogHandler, расположенный в модуле logging.handlers, поддерживает отправку сообщений регистрации в удалённый или локальный Unix syslog.

class logging.handlers.SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM)

Возвращает новый экземпляр класса SysLogHandler, предназначенный для связи с удалённой Unix-машиной, адрес которой задаётся параметром address в виде кортежа (host, port). Если address не указан, используется ('localhost', 514). Адрес используется для открытия сокета. В качестве альтернативы кортежу (host, port) можно использовать адрес в виде строки, например, ‘/dev/log’. В этом случае используется сокет 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)

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

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

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.