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()¶
Закрывает файл.
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.
- 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 конфигурации для модуля протоколирования.