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

Класс 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 имеет значение true, то открытие файла откладывается до первого вызова emit(). По умолчанию размер файла увеличивается неограниченно. Если задано errors, оно определяет, как обрабатываются ошибки кодирования.

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

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

reopenIfNeeded()

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

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

emit(record)

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

Базовый обработчик BaseRotatingHandler

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

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

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

namer

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

Примечание

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

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

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

rotator

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

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

rotation_filename(default_name)

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

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

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

Параметры:

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

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

rotate(source, dest)

При ротации выполняется ротация текущего файла журнала.

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

Параметры:

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

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

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

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

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

RotatingFileHandler

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

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

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

Вы можете использовать значения maxBytes и backupCount, чтобы разрешить файлу переключение при достижении определенного размера. Когда размер близок к превышению, файл закрывается, и новый файл тихо открывается для вывода. Переключение происходит всякий раз, когда текущий файл журнала приближается к размеру 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’. В этом случае используется сокет доменной системы для отправки сообщения в 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)

Кодирует 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)

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

Обработчик Memory

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

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

class logging.handlers.BufferingHandler(capacity)

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

emit(record)

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

flush()

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

shouldFlush(record)

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

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

Возвращает новый экземпляр класса MemoryHandler. Экземпляр инициализируется размером буфера capacity (количество буферизованных записей). Если flushLevel не указан, используется ERROR . Если target не указан, целевой обработчик необходимо установить с помощью setTarget(), прежде чем этот обработчик будет работать. Если flushOnClose указано как False, буфер не очищается при закрытии обработчика. Если не указано или указано как True, будет происходить предыдущее поведение очистки буфера при закрытии обработчика.

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

close()

Вызывает flush(), устанавливает целевой обработчик в None и очищает буфер.

flush()

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

setTarget(target)

Устанавливает целевой обработчик для этого обработчика.

shouldFlush(record)

Проверяет, заполнен ли буфер или есть запись на уровне flushLevel или выше.

HTTPHandler

Класс HTTPHandler, расположенный в модуле logging.handlers, поддерживает отправку сообщений логгирования на веб-сервер, используя либо GET либо POST семантику.

class logging.handlers.HTTPHandler(host, url, method='GET', secure=False, credentials=None, context=None)

Возвращает новый экземпляр класса HTTPHandler. Параметр host может иметь вид host:port, если требуется использовать определённый номер порта. Если параметр method не указан, используется GET. Если secure имеет значение True, будет использовано HTTPS-соединение. Параметр context может быть установлен в экземпляр ssl.SSLContext для настройки параметров SSL, используемых для HTTPS-соединения. Если указаны credentials, они должны быть кортежем из двух элементов — идентификатора пользователя и пароля, который будет добавлен в заголовок HTTP «Authorization» с использованием аутентификации Basic. Если вы указываете учетные данные, необходимо также указать secure=True, чтобы ваши имя пользователя и пароль не передавались в открытом виде по сети.

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

mapLogRecord(record)

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

emit(record)

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

Примечание

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

QueueHandler

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

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

class logging.handlers.QueueHandler(queue)

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

Примечание

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

emit(record)

Добавляет результат подготовки 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 для 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.