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

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

close()

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

emit(record)

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

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

Обработчик отсутствия данных

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

class logging.NullHandler

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

emit(record)

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

handle(record)

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

createLock()

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

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

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

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

Изменение файла может произойти из-за использования программ, таких как 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 истинно, то открытие файла откладывается до первого вызова 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 – Имя файла назначения. Обычно это то, во что исходный файл вращается, например, ‘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 истинно, открытие файла откладывается до первого вызова emit(). По умолчанию файл увеличивается неограниченно. Если указан errors, он определяет, как обрабатывать ошибки кодирования.

Вы можете использовать значения maxBytes и backupCount, чтобы позволить файлу переключаться на определенный размер. Когда размер приближается к пределу, файл закрывается, а новый файл молча открывается для вывода. Переключение происходит всякий раз, когда текущий файл журнала приближается к размеру maxBytes; но если maxBytes или backupCount равны нулю, переключение никогда не происходит, поэтому вы обычно хотите установить backupCount по крайней мере на 1 и иметь ненулевое значение maxBytes. Когда backupCount ненулевой, система сохранит старые файлы журнала, добавив к имени файла расширения '.1', '.2' и т. д. Например, с backupCount равным 5 и базовым именем файла app.log, вы получите app.log, app.log.1, app.log.2, вплоть до app.log.5. Файл, в который записывается информация, всегда app.log. Когда этот файл заполняется, он закрывается и переименовывается в app.log.1, а если файлы app.log.1, app.log.2, и т. д. существуют, они переименовываются в app.log.2, app.log.3 соответственно.

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

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

doRollover()

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

emit(record)

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

TimedRotatingFileHandler

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

class logging.handlers.TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None, errors=None)

Возвращает новый экземпляр класса TimedRotatingFileHandler. Указанный файл открывается и используется в качестве потока для ведения журнала. При переключении также устанавливается суффикс имени файла. Переключение происходит на основе произведения when и interval.

Вы можете использовать when для указания типа interval. Список возможных значений приведён ниже. Обратите внимание, что регистр не учитывается.

Значение	Тип интервала	Использование atTime
'S'	Секунды	Игнорируется
'M'	Минуты	Игнорируется
'H'	Часы	Игнорируется
'D'	Дни	Игнорируется
'W0'-'W6'	День недели (0=понедельник)	Используется для вычисления начального времени переключения
'midnight'	Переключение в полночь, если atTime не указано, иначе в указанное время atTime	Используется для вычисления начального времени переключения

При использовании ротации по дням недели укажите ‘W0’ для понедельника, ‘W1’ для вторника и так далее до ‘W6’ для воскресенья. В этом случае переданное значение для interval не используется.

Система сохранит старые файлы журнала, добавив расширения к имени файла. Расширения основаны на дате и времени, используя формат strftime %Y-%m-%d_%H-%M-%S или его часть, в зависимости от интервала переключения.

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

Если аргумент utc равен true, будут использоваться значения времени в UTC; в противном случае используется местное время.

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

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

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

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

Примечание

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

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

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

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

doRollover()

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

emit(record)

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

getFilesToDelete()

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

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

Класс 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.

Примечание

Поскольку 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()

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

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 для того, чтобы этот экземпляр предварял каждое обрабатываемое сообщение идентификатором. Обратите внимание, что предоставленный идентификатор должен быть текстовым, а не байтовым, и добавляется к сообщению точно так, как есть.

encodePriority(facility, priority)

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

Символьные значения 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

Facilities

Имя (строка)	Символическое значение
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 используйте формат кортежа (хост, порт) для аргумента 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)

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

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 не указан, целевой обработчик необходимо будет задать с помощью 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 объединённым сообщением (полученным путём вызова метода обработчика format()), и устанавливает атрибуты 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 для *очереди*.

Примечание

Если вы используете 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.