logging.handlers — Обработчики журналов

Источник: Lib/logging/handlers.py

В пакете представлены следующие полезные обработчики. Обратите внимание, что три обработчика (StreamHandler, FileHandler и NullHandler) на самом деле определены в самом модуле logging, но были задокументированы здесь вместе с другими обработчиками.

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, если не был.

Added in version 3.7.

terminator

Строка, используемая в качестве терминатора при записи форматированной записи в поток. Значение по умолчанию - '\n'.

Если вам не нужна новая строка, вы можете установить атрибут terminator экземпляра обработчика на пустую строку.

В ранних версиях терминатор был жестко закодирован как '\n'.

Added in version 3.2.

FileHandler

Класс FileHandler, расположенный в основном пакете logging, отправляет вывод логов в дисковый файл. Он наследует функциональность вывода от StreamHandler.

class logging.FileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

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

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

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

close()

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

emit(record)

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

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

NullHandler

Added in version 3.1.

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

class logging.NullHandler

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

emit(record)

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

handle(record)

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

createLock()

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

Дополнительные сведения об использовании Настройка ведения журнала для библиотеки см. в разделе NullHandler.

WatchedFileHandler

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

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

Этот обработчик не подходит для использования под Windows, поскольку под Windows открытые файлы журналов нельзя перемещать или переименовывать - при журналировании файлы открываются с помощью эксклюзивных блокировок - и поэтому в таком обработчике нет необходимости. Кроме того, ST_INO не поддерживается в Windows; stat() всегда возвращает ноль для этого значения.

class logging.handlers.WatchedFileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

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

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

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

reopenIfNeeded()

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

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

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

Added in version 3.3.

rotator

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

Added in version 3.3.

rotation_filename(default_name)

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

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

Реализация по умолчанию вызывает атрибут „namer“ обработчика, если он является вызываемым, передавая ему имя по умолчанию. Если атрибут не является вызываемым (по умолчанию это None), имя возвращается без изменений.

Параметры:

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

Added in version 3.3.

rotate(source, dest)

При вращении поверните текущий журнал.

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

Параметры:

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

  • dest – Имя файла назначения. Обычно это то, во что поворачивается источник, например, „test.log.1“.

Added in version 3.3.

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

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

В качестве примера смотрите Использование ротатора и именователя для настройки обработки ротации журнала.

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

Значение

Тип интервала

Если/как используется 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

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

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

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

createSocket()

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

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

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

  • retryFactor (множитель, по умолчанию 2,0).

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

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

DatagramHandler

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

class logging.handlers.DatagramHandler(host, port)

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

Примечание

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

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

emit()

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

makeSocket()

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

send(s)

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

SysLogHandler

Класс 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 используется сокет домена Unix. Если 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()

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

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

encodePriority(facility, priority)

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

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

Приоритеты

Имя (строка)

Символическое значение

alert

LOG_ALERT

crit или critical

LOG_CRIT

debug

LOG_DEBUG

emerg или panic

LOG_EMERG

err или error

LOG_ERR

info

LOG_INFO

notice

LOG_NOTICE

warn или warning

LOG_WARNING

Удобства

Имя (строка)

Символическое значение

auth

LOG_AUTH

authpriv

LOG_AUTHPRIV

cron

LOG_CRON

daemon

LOG_DAEMON

ftp

LOG_FTP

kern

LOG_KERN

lpr

LOG_LPR

mail

LOG_MAIL

news

LOG_NEWS

syslog

LOG_SYSLOG

user

LOG_USER

uucp

LOG_UUCP

local0

LOG_LOCAL0

local1

LOG_LOCAL1

local2

LOG_LOCAL2

local3

LOG_LOCAL3

local4

LOG_LOCAL4

local5

LOG_LOCAL5

local6

LOG_LOCAL6

local7

LOG_LOCAL7
mapPriority(levelname)

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

NTEventLogHandler

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

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

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

close()

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

emit(record)

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

getEventCategory(record)

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

getEventType(record)

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

getMessageID(record)

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

SMTPHandler

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

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

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

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

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

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

emit(record)

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

getSubject(record)

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

MemoryHandler

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

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

class logging.handlers.BufferingHandler(capacity)

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

emit(record)

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

flush()

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

shouldFlush(record)

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

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

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

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

close()

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

flush()

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

setTarget(target)

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

shouldFlush(record)

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

HTTPHandler

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

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

Возвращает новый экземпляр класса HTTPHandler. В качестве хоста может быть указан host:port, если вам нужно использовать определенный номер порта. Если не указан метод, используется GET. Если параметр secure равен true, будет использоваться HTTPS-соединение. Параметр context может быть установлен в экземпляр ssl.SSLContext для настройки параметров SSL, используемых для HTTPS-соединения. Если указан параметр credentials, то это должен быть кортеж из двух слов, состоящий из userid и password, который будет помещен в 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

Added in version 3.2.

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

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

class logging.handlers.QueueHandler(queue)

Возвращает новый экземпляр класса QueueHandler. Экземпляр инициализируется очередью для отправки сообщений. Очередью* может быть любой объект типа очереди; она используется как таковая методом 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.

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

Примечание

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

enqueue(record)

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

listener

При создании через конфигурацию с помощью dictConfig() этот атрибут будет содержать экземпляр QueueListener для использования с этим обработчиком. В противном случае это будет None.

Added in version 3.12.

QueueListener

Added in version 3.2.

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

Запускает слушателя.

При этом запускается фоновый поток для мониторинга очереди на обработку записей LogRecords.

stop()

Остановите слушателя.

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

enqueue_sentinel()

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

Added in version 3.3.

См.также

Модуль logging

Ссылка на API для модуля протоколирования.

Модуль logging.config

API конфигурации для модуля протоколирования.