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

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

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

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

Обработчик null

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

class logging.NullHandler

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

emit(record)

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

handle(record)

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

createLock()

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

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

ОбработчикWatchedFileHandler

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

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

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

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

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

doRollover()

Производит переход к новому файлу (rollover), как описано выше.

emit(record)

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

getFilesToDelete()

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

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

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

class logging.handlers.SocketHandler(host, port)

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

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

close()

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

emit()

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

handleError()

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

makeSocket()

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

makePickle(record)

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

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

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

send(packet)

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

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

createSocket()

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

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

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

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

Обработчик датаграмм

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

class logging.handlers.DatagramHandler(host, port)

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

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

emit()

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

makeSocket()

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

send(s)

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

Обработчик SysLog

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

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

Возвращает новый экземпляр класса SysLogHandler, предназначенный для связи с удалённой Unix-машиной, адрес которой задан в виде кортежа (host, port). Если address не указан, используется ('localhost', 514). Адрес используется для открытия сокета. В качестве альтернативы кортежу (host, port) можно указать адрес в виде строки, например ‘/dev/log’. В этом случае используется сокет доменной системы для отправки сообщения в syslog. Если facility не указан, используется LOG_USER. Тип открытого сокета зависит от аргумента socktype, который по умолчанию равен socket.SOCK_DGRAM, и таким образом открывается UDP-сокет. Для открытия TCP-сокета (для использования с более новыми демонами syslog, такими как rsyslog), укажите значение socket.SOCK_STREAM.

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

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

close()

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

emit(record)

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

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

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

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

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’.

Обработчик событий NTEventLog

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

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

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

close()

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

emit(record)

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

getEventCategory(record)

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

getEventType(record)

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

getMessageID(record)

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

Обработчик SMTP

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

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

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

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

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

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

emit(record)

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

getSubject(record)

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

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

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

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

class logging.handlers.BufferingHandler(capacity)

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

emit(record)

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

flush()

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

shouldFlush(record)

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

class logging.handlers.MemoryHandler(capacity, flushLevel=ERROR, target=None, flushOnClose=True)

Возвращает новый экземпляр класса MemoryHandler. Экземпляр инициализируется размером буфера capacity (число буферизованных записей). Если flushLevel не указан, используется ERROR. Если target не указан, необходимо установить 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.

emit(record)

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

prepare(record)

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

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

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

enqueue(record)

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

QueueListener

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

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

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

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