logging.handlers — Обработчики логов

Исходный код: Lib/logging/handlers.py

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

1. Обработчик потоков

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

2. Обработчик файлов

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

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

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

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

close()

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

emit(record)

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

3. Обработчик пустого значения

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

class logging.NullHandler

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

emit(record)

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

handle(record)

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

createLock()

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

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

4. Обработчик отслеживания файла

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

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

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

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

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

emit(record)

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

5. Обработчик вращающихся файлов

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

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

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

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

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

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)

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

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)

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

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

send(packet)

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

createSocket()

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

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

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

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

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)

Отправка сериализованной строки в сокет.

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. Если address не указан, используется ('localhost', 514). Адрес используется для открытия сокета. В качестве альтернативы кортежу address можно использовать строку, например, ‘/dev/log’. В этом случае используется сокет Unix-доменного типа для отправки сообщения в syslog. Если facility не указан, используется LOG_USER. Тип открытого сокета зависит от аргумента socktype, который по умолчанию равен socket.SOCK_DGRAM (UDP сокет). Для открытия TCP сокета (для использования с более новыми демонами syslog, такими как rsyslog), укажите значение socket.SOCK_STREAM.

Обратите внимание, что если ваш сервер не прослушивает UDP-порт 514, класс SysLogHandler может не работать. В этом случае проверьте, какой адрес следует использовать для сокета доменного типа — он зависит от системы. Например, в Linux это обычно ‘/dev/log’, а в OS/X — ‘/var/run/syslog’. Вам нужно проверить вашу платформу и использовать соответствующий адрес (возможно, вам нужно будет выполнить эту проверку во время выполнения, если ваше приложение должно работать на нескольких платформах). В Windows, как правило, используется UDP.

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

close()

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

emit(record)

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

encodePriority(facility, priority)

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

Facilities

Имя (строка)	Символьное значение
auth	LOG_AUTH
authpriv	LOG_AUTHPRIV
cron	LOG_CRON
daemon	LOG_DAEMON
ftp	LOG_FTP
kern	LOG_KERN
lpr	LOG_LPR
mail	LOG_MAIL
news	LOG_NEWS
syslog	LOG_SYSLOG
user	LOG_USER
uucp	LOG_UUCP
local0	LOG_LOCAL0
local1	LOG_LOCAL1
local2	LOG_LOCAL2
local3	LOG_LOCAL3
local4	LOG_LOCAL4
local5	LOG_LOCAL5
local6	LOG_LOCAL6
local7	LOG_LOCAL7

mapPriority(levelname)

Преобразует имя уровня логирования в имя приоритета syslog. Возможно, потребуется переопределить этот метод, если вы используете пользовательские уровни или если стандартный алгоритм не подходит для ваших нужд. По умолчанию алгоритм сопоставляет DEBUG, INFO, WARNING, ERROR и CRITICAL с эквивалентными именами syslog, а все остальные имена уровней — со строкой ‘warning’.

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

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)

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

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(), устанавливает target в None и очищает буфер.

flush()

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

setTarget(target)

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

shouldFlush(record)

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

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() для кодирования словаря в формате, подходящем для отправки на веб-сервер.