15.9. logging.handlers – Обработчики журналирования¶logging.handlers – Logging handlers

15.9.1. StreamHandler¶

Класс StreamHandler, находящийся в основном пакете logging, отправляет вывод логирования в потоки данных, такие как sys.stdout, sys.stderr или любой объект, похожий на файл (или, точнее, любой объект, который поддерживает методы write() и flush()).

class logging.StreamHandler(stream=None)¶

Возвращает новый экземпляр класса StreamHandler. Если указан stream, экземпляр будет использовать его для вывода логирования; в противном случае будет использоваться sys.stderr.

emit(record)¶

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

flush()¶

Сбрасывает поток данных вызовом его метода flush(). Обратите внимание, что метод close() наследуется от Handler и поэтому не производит вывода, так что иногда может потребоваться явный вызов flush().

15.9.2. FileHandler¶

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

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

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

Изменено в версии 2.6: delay добавлен.

close()¶

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

emit(record)¶

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

15.9.3. NullHandler¶

Класс NullHandler, находящийся в основном пакете logging, не выполняет никакого форматирования или вывода. По сути это обработчик-пустышка (‘no-op’), предназначенный для разработчиков библиотек.

class logging.NullHandler¶

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

emit(record)¶

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

handle(record)¶

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

createLock()¶

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

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

15.9.4. WatchedFileHandler¶

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

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

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

class logging.handlers.WatchedFileHandler(filename[, mode[, encoding[, delay]]])¶

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

emit(record)¶

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

15.9.5. RotatingFileHandler¶

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

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

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

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

Изменено в версии 2.6: delay добавлен.

doRollover()¶

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

emit(record)¶

Записывает запись (record) в файл, выполняя при необходимости ротацию, как описано ранее.

15.9.6. TimedRotatingFileHandler¶

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

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

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

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

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

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

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

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

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

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

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

Изменено в версии 2.6: delay и utc добавлены.

doRollover()¶

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

emit(record)¶

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

15.9.7. SocketHandler¶

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

class logging.handlers.SocketHandler(host, port)¶

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

close()¶

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

emit()¶

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

handleError()¶

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

makeSocket()¶

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

makePickle(record)¶

Сериализует словарь атрибутов записи в двоичном формате с префиксом длины и возвращает его готовым к передаче через сокет.

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

send(packet)¶

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

createSocket()¶

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

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

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

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

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

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

15.9.8. DatagramHandler¶

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

class logging.handlers.DatagramHandler(host, port)¶

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

emit()¶

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

makeSocket()¶

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

send(s)¶

Отправляет сериализованную с помощью pickle строку в сокет.

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

Изменено в версии 2.7: socktype добавлен.

close()¶

Закрывает сокет, подключённый к удалённому узлу.

emit(record)¶

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

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

15.9.10. NTEventLogHandler¶

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

15.9.11. SMTPHandler¶

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

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

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

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

Изменено в версии 2.6: credentials был добавлен.

Изменено в версии 2.7: secure был добавлен.

emit(record)¶

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

getSubject(record)¶

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

15.9.12. MemoryHandler¶

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

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

class logging.handlers.BufferingHandler(capacity)¶

Инициализирует обработчик буфером указанной ёмкости.

emit(record)¶

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

flush()¶

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

shouldFlush(record)¶

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

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

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

close()¶

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

flush()¶

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

setTarget(target)¶

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

shouldFlush(record)¶

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

15.9.13. HTTPHandler¶

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

class logging.handlers.HTTPHandler(host, url, method='GET')¶

Возвращает новый экземпляр класса HTTPHandler. host может иметь форму host:port, если необходимо использовать определённый номер порта.

mapLogRecord(record)¶

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

emit(record)¶

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

Примечание

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