15.7. logging – Система логирования для Python¶logging – Logging facility for Python

15.7.1. Объекты Logger¶Logger Objects

Логгеры имеют следующие атрибуты и методы. Обратите внимание, что логгеры никогда не создаются напрямую, а всегда через функцию уровня модуля logging.getLogger(name). Многократные вызовы getLogger() с одним и тем же именем всегда возвращают ссылку на один и тот же объект Logger.

Имя name – это иерархическое значение, разделённое точками, например, foo.bar.baz (хотя это может быть и просто foo). Логгеры, расположенные ниже в иерархическом списке, являются дочерними по отношению к логгерам выше по списку. Например, для логгера с именем foo логгеры с именами foo.bar, foo.bar.baz и foo.bam являются потомками foo. Иерархия имён логгеров аналогична иерархии пакетов Python и совпадает с ней, если организовывать логгеры по модулям с помощью рекомендуемой конструкции logging.getLogger(__name__). Это потому, что в модуле __name__ – это имя модуля в пространстве имён пакетов Python.

class logging.Logger¶

Logger.propagate¶

Если это значение истинно, события, записанные в этот логгер, будут передаваться обработчикам логгеров вышестоящего уровня (родительских логгеров) в дополнение к любым обработчикам, присоединённым к этому логгеру. Сообщения передаются напрямую обработчикам родительских логгеров – ни уровень, ни фильтры этих родительских логгеров не учитываются.

Если это ложно, сообщения логирования не передаются обработчикам логгеров-предков.

Конструктор устанавливает этот атрибут в True.

Примечание

Если прикрепить обработчик к логгеру и к одному или нескольким его предкам, одна и та же запись может быть выдана несколько раз. В общем случае не следует прикреплять обработчик более чем к одному логгеру – если прикрепить его только к подходящему логгеру, находящемуся выше всех в иерархии логгеров, то он будет видеть все события, записанные всеми дочерними логгерами, при условии, что их параметр propagate остаётся равным True. Распространённый сценарий – прикреплять обработчики только к корневому логгеру и позволить распространению обрабатывать остальное.

Logger.setLevel(lvl)¶

Устанавливает порог для этого логгера в lvl. Сообщения логирования, уровень которых ниже lvl, будут игнорироваться. При создании логгера уровень устанавливается в NOTSET (что приводит к обработке всех сообщений, если логгер является корневым, или к делегированию родительскому логгеру, если логгер не корневой). Обратите внимание, что корневой логгер создаётся с уровнем WARNING.

Термин «делегирование родительскому регистратору» означает, что если у регистратора уровень NOTSET, то просматривается цепочка его регистраторов-предков, пока не будет найден предок с уровнем, отличным от NOTSET, или не будет достигнут корень.

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

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

Изменено в версии 3.2: Параметр lvl теперь принимает строковое представление уровня, например 'INFO', как альтернативу целочисленным константам, таким как INFO.

Logger.isEnabledFor(lvl)¶

Указывает, будет ли сообщение с уровнем серьёзности lvl обработано этим логгером. Этот метод сначала проверяет уровень, установленный на уровне модуля с помощью logging.disable(lvl), а затем эффективный уровень логгера, определяемый getEffectiveLevel().

Logger.getEffectiveLevel()¶

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

Logger.getChild(suffix)¶

Возвращает логгер, являющийся потомком данного логгера, в соответствии с суффиксом. Таким образом, logging.getLogger('abc').getChild('def.ghi') вернёт тот же логгер, что и logging.getLogger('abc.def.ghi'). Это удобный метод, полезный, когда родительский логгер именуется, например, через __name__, а не литеральной строкой.

Новое в версии 3.2.

Logger.debug(msg, *args, **kwargs)¶

Записывает сообщение уровня DEBUG в этот логгер. msg – это строка форматирования сообщения, а args – аргументы, которые подставляются в msg с помощью оператора форматирования строк. (Обратите внимание, что это означает, что можно использовать ключевые слова в строке форматирования вместе с одним словарным аргументом.)

В kwargs проверяются три именованных аргумента: exc_info, который, если его значение не равно false, приводит к добавлению информации об исключении в сообщение логирования. Если предоставлен кортеж исключения (в формате, возвращаемом sys.exc_info()), используется он; в противном случае вызывается sys.exc_info() для получения информации об исключении.

Второй необязательный именованный аргумент – stack_info, по умолчанию равен False. Если указано True, в сообщение журнала добавляется информация о стеке, включая фактический вызов логирования. Обратите внимание, что это не та же информация о стеке, которая отображается при указании exc_info: первый – это кадры стека от дна стека до вызова логирования в текущем потоке, тогда как второй – это информация о кадрах стека, которые были развернуты после исключения при поиске обработчиков исключений.

Можно указать stack_info независимо от exc_info, например, чтобы просто показать, как был достигнут определённый участок кода, даже если исключения не возникали. Кадры стека выводятся после строки заголовка, которая гласит:

Stack (most recent call last):

Это имитирует Traceback (most recent call last):, который используется при отображении кадров исключений.

Третий именованный аргумент – extra, который можно использовать для передачи словаря, который заполняет __dict__ объекта LogRecord, созданного для события журналирования, пользовательскими атрибутами. Затем эти пользовательские атрибуты можно использовать по своему усмотрению. Например, их можно включать в журналируемые сообщения. Например:

FORMAT = '%(asctime)-15s %(clientip)s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logger = logging.getLogger('tcpserver')
logger.warning('Protocol problem: %s', 'connection reset', extra=d)

выведет что-то вроде

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

Ключи в словаре, переданном в extra, не должны пересекаться с ключами, используемыми системой логирования. (См. документацию Formatter для получения дополнительной информации о том, какие ключи используются системой логирования.)

Если вы решите использовать эти атрибуты в логируемых сообщениях, нужно соблюдать осторожность. Например, в приведённом выше примере Formatter настроен с форматной строкой, которая ожидает 'clientip' и 'user' в словаре атрибутов LogRecord. Если они отсутствуют, сообщение не будет записано, так как возникнет исключение форматирования строки. Поэтому в этом случае всегда нужно передавать словарь extra с этими ключами.

Хотя это может быть раздражающим, эта функция предназначена для использования в специализированных обстоятельствах, таких как многопоточные серверы, где один и тот же код выполняется во многих контекстах, и интересующие условия зависят от этого контекста (например, IP-адрес удалённого клиента и имя аутентифицированного пользователя в приведённом выше примере). В таких обстоятельствах, скорее всего, будут использоваться специализированные Formatter с конкретными Handler.

Новое в версии 3.2: Добавлен параметр stack_info.

Logger.info(msg, *args, **kwargs)¶

Записывает сообщение уровня INFO в этот логгер. Аргументы интерпретируются так же, как для debug().

Logger.warning(msg, *args, **kwargs)¶

Записывает сообщение уровня WARNING в этот логгер. Аргументы интерпретируются так же, как для debug().

Logger.error(msg, *args, **kwargs)¶

Записывает сообщение уровня ERROR в этот логгер. Аргументы интерпретируются так же, как для debug().

Logger.critical(msg, *args, **kwargs)¶

Записывает сообщение с уровнем CRITICAL в этот логгер. Аргументы интерпретируются так же, как для debug().

Logger.log(lvl, msg, *args, **kwargs)¶

Записывает сообщение с целочисленным уровнем lvl в этот логгер. Остальные аргументы интерпретируются так же, как для debug().

Logger.exception(msg, *args)¶

Записывает сообщение с уровнем ERROR в этот логгер. Аргументы интерпретируются так же, как для debug(). Информация об исключении добавляется в сообщение лога. Этот метод следует вызывать только из обработчика исключений.

Logger.addFilter(filt)¶

Добавляет указанный фильтр filt к этому логгеру.

Logger.removeFilter(filt)¶

Удаляет указанный фильтр filt из этого логгера.

Logger.filter(record)¶

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

Logger.addHandler(hdlr)¶

Добавляет указанный обработчик hdlr к этому логгеру.

Logger.removeHandler(hdlr)¶

Удаляет указанный обработчик hdlr из этого логгера.

Logger.findCaller(stack_info=False)¶

Находит имя исходного файла и номер строки вызывающего кода. Возвращает имя файла, номер строки, имя функции и информацию о стеке в виде кортежа из 4 элементов. Информация о стеке возвращается как None, если stack_info не равно True.

Logger.handle(record)¶

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

Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)¶

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

Logger.hasHandlers()¶

Проверяет, настроены ли у этого регистратора какие-либо обработчики. Для этого выполняется поиск обработчиков в этом регистраторе и его родителях в иерархии регистраторов. Возвращает True, если обработчик найден, иначе False. Метод прекращает поиск вверх по иерархии, как только встречается регистратор, у которого атрибут ‘propagate’ установлен в False – это будет последний регистратор, проверяемый на наличие обработчиков.

Новое в версии 3.2.

15.7.2. Объекты Handler¶Handler Objects

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

Handler.__init__(level=NOTSET)¶

Инициализирует экземпляр Handler, устанавливая его уровень, устанавливая список фильтров в пустой список и создавая блокировку (с помощью createLock()) для сериализации доступа к механизму ввода-вывода.

Handler.createLock()¶

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

Handler.acquire()¶

Захватывает блокировку потока, созданную с помощью createLock().

Handler.release()¶

Освобождает блокировку потока, полученную с помощью acquire().

Handler.setLevel(lvl)¶

Устанавливает порог для этого обработчика в lvl. Сообщения журнала, которые менее серьезны, чем lvl, будут игнорироваться. При создании обработчика уровень устанавливается в NOTSET (из-за чего обрабатываются все сообщения).

Изменено в версии 3.2: Параметр lvl теперь принимает строковое представление уровня, например «INFO», как альтернативу целочисленным константам, таким как INFO.

Handler.setFormatter(form)¶

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

Handler.addFilter(filt)¶

Добавляет указанный фильтр фильтр в данный обработчик.

Handler.removeFilter(filt)¶

Удаляет указанный фильтр фильтр из данного обработчика.

Handler.filter(record)¶

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

Handler.flush()¶

Обеспечивает сброс всего вывода логирования. Данная версия ничего не делает и предназначена для реализации в подклассах.

Handler.close()¶

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

Handler.handle(record)¶

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

Handler.handleError(record)¶

Этот метод должен вызываться из обработчиков при возникновении исключения во время вызова emit(). Если атрибут уровня модуля raiseExceptions равен False, исключения молча игнорируются. Обычно это то, что нужно для системы журналирования – большинство пользователей не будут беспокоиться об ошибках в системе журналирования, они больше заинтересованы в ошибках приложения. Однако вы можете заменить это на собственный обработчик, если захотите. Указанная запись (record) – это та, которая обрабатывалась, когда произошло исключение. (Значение по умолчанию raiseExceptions равно True, так как это более полезно во время разработки).

Handler.format(record)¶

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

Handler.emit(record)¶

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

Список стандартных обработчиков см. в logging.handlers.

15.7.3. Объекты Formatter¶Formatter Objects

Объекты Formatter имеют следующие атрибуты и методы. Они отвечают за преобразование LogRecord в строку (как правило), которую может интерпретировать как человек, так и внешняя система. Базовый Formatter позволяет задать форматирующую строку. Если она не указана, используется значение по умолчанию '%(message)s'.

Объект Formatter можно инициализировать строкой форматирования, использующей атрибуты LogRecord, например, как в упомянутом выше значении по умолчанию, использующем тот факт, что сообщение пользователя и аргументы предварительно форматируются в атрибут LogRecord's message. Эта строка форматирования содержит стандартные %-ключи сопоставления Python. Дополнительную информацию о форматировании строк см. в разделе Old String Formatting Operations.

Полезные ключи отображения в LogRecord приведены в разделе LogRecord attributes.

class logging.Formatter(fmt=None, datefmt=None, style='%')¶

Возвращает новый экземпляр класса Formatter. Экземпляр инициализируется строкой форматирования для всего сообщения, а также строкой форматирования для части даты/времени сообщения. Если fmt не указан, используется '%(message)s'. Если datefmt не указан, используется формат даты ISO8601.

Параметр style может принимать значения '%', '{' или '$' и определяет, каким образом строка форматирования будет объединяться со своими данными: с помощью %-форматирования, str.format() или string.Template.

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

format(record)¶

Словарь атрибутов записи используется как операнд для операции форматирования строки. Возвращает результирующую строку. Перед форматированием словаря выполняется несколько подготовительных шагов. Атрибут message записи вычисляется с помощью msg % args. Если строка форматирования содержит '(asctime)', вызывается formatTime() для форматирования времени события. Если присутствует информация об исключении, она форматируется с помощью formatException() и добавляется к сообщению. Обратите внимание, что отформатированная информация об исключении кэшируется в атрибуте exc_text. Это полезно, поскольку информацию об исключении можно сериализовать и отправить по сети, но следует быть осторожным, если имеется более одного подкласса Formatter, который настраивает форматирование информации об исключении. В этом случае вам придется очищать кэшированное значение после того, как форматировщик выполнит свое форматирование, чтобы следующий форматировщик, обрабатывающий событие, не использовал кэшированное значение, а пересчитал его заново.

Если информация о стеке доступна, она добавляется после информации об исключении, с использованием formatStack() для преобразования при необходимости.

formatTime(record, datefmt=None)¶

Этот метод должен вызываться из format() форматировщиком, который хочет использовать отформатированное время. Этот метод может быть переопределен в форматировщиках для любых специфических требований, но базовое поведение следующее: если указан datefmt (строка), он используется с time.strftime() для форматирования времени создания записи. В противном случае используется формат ISO8601. Возвращается результирующая строка.

Эта функция использует настраиваемую пользователем функцию для преобразования времени создания в кортеж. По умолчанию используется time.localtime(); чтобы изменить это для конкретного экземпляра форматировщика, установите атрибут converter на функцию с той же сигнатурой, что и time.localtime() или time.gmtime(). Чтобы изменить его для всех форматировщиков, например, если вы хотите, чтобы все временные метки отображались в GMT, установите атрибут converter в классе Formatter.

formatException(exc_info)¶

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

formatStack(stack_info)¶

Форматирует указанную информацию о стеке (строку, возвращаемую traceback.print_stack(), но с удалённым последним символом новой строки) в виде строки. Эта реализация по умолчанию просто возвращает входное значение.

15.7.4. Объекты Filter¶Filter Objects

Фильтры могут использоваться обработчиками и логгерами для более сложной фильтрации, чем та, что обеспечивается уровнями. Базовый класс фильтра пропускает только события, которые находятся ниже определённой точки в иерархии логгеров. Например, фильтр, инициализированный строкой 'A.B', будет пропускать события, зарегистрированные логгерами 'A.B', 'A.B.C', 'A.B.C.D', 'A.B.D' и т.д., но не 'A.BB', 'B.A.B' и т.д. Если инициализировать пустой строкой, пропускаются все события.

class logging.Filter(name='')¶

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

filter(record)¶

Следует ли регистрировать указанную запись? Возвращает ноль, если нет, и ненулевое значение, если да. Если это уместно, запись может быть изменена на месте данным методом.

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

На самом деле не обязательно создавать подкласс Filter: можно передать любой экземпляр, у которого есть метод filter с той же семантикой.

Изменено в версии 3.2: Больше не нужно создавать специализированные классы Filter или использовать другие классы с методом filter: в качестве фильтра можно использовать функцию (или другой вызываемый объект). Логика фильтрации проверяет, есть ли у объекта фильтра атрибут filter: если есть, то считается, что это Filter, и вызывается его метод filter(). В противном случае считается, что это вызываемый объект, и он вызывается с записью в качестве единственного параметра. Возвращаемое значение должно соответствовать тому, что возвращает filter().

Хотя фильтры в первую очередь используются для фильтрации записей на основе более сложных критериев, чем уровни, они видят каждую запись, которая обрабатывается обработчиком или регистратором, к которому они прикреплены: это может быть полезно, если нужно, например, подсчитать, сколько записей было обработано конкретным регистратором или обработчиком, или добавить, изменить или удалить атрибуты в обрабатываемом LogRecord. Очевидно, что изменение LogRecord требует определённой осторожности, но это позволяет внедрять контекстную информацию в журналы (см. Использование фильтров для передачи контекстной информации).

15.7.5. Объекты LogRecord¶LogRecord Objects

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

class logging.LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None)¶

Содержит всю информацию, относящуюся к регистрируемому событию.

Основная информация передаётся в msg и args, которые объединяются с помощью msg % args для создания поля message записи.

Параметры:

name – Имя логгера, используемого для регистрации события, представленного этой LogRecord. Обратите внимание, что это имя всегда будет иметь данное значение, даже если событие может быть отправлено обработчиком, прикреплённым к другому (родительскому) логгеру. level – числовой уровень события логирования (один из DEBUG, INFO и т.д.). Обратите внимание, что это преобразуется в два атрибута LogRecord: levelno для числового значения и levelname для соответствующего имени уровня. pathname – Полный путь к исходному файлу, в котором был выполнен вызов логирования. lineno – Номер строки в исходном файле, в которой был выполнен вызов логирования. msg – Описание события, возможно, строка форматирования с заполнителями для переменных данных. args – Переменные данные для подстановки в аргумент msg для получения описания события. exc_info – кортеж исключения с текущей информацией об исключении, или None, если информация об исключении отсутствует. func – Имя функции или метода, из которого был выполнен вызов логирования. sinfo – Текстовая строка, представляющая информацию о стеке от основания стека в текущем потоке до вызова логирования.

getMessage()¶

Возвращает сообщение для данного экземпляра LogRecord после объединения любых предоставленных пользователем аргументов с сообщением. Если предоставленный пользователем аргумент сообщения при вызове логирования не является строкой, для его преобразования в строку вызывается str(). Это позволяет использовать пользовательские классы в качестве сообщений, чей метод __str__ может возвращать фактическую строку форматирования для использования.

Изменено в версии 3.2: Создание LogRecord стало более настраиваемым благодаря предоставлению фабрики, используемой для создания записи. Фабрику можно установить с помощью getLogRecordFactory() и setLogRecordFactory() (см. эти функции для сигнатуры фабрики).

Эту функциональность можно использовать для внедрения собственных значений в LogRecord при его создании. Можно воспользоваться следующим шаблоном:

old_factory = logging.getLogRecordFactory()

def record_factory(*args, **kwargs):
    record = old_factory(*args, **kwargs)
    record.custom_attribute = 0xdecafbad
    return record

logging.setLogRecordFactory(record_factory)

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

15.7.6. Атрибуты LogRecord¶LogRecord attributes

LogRecord имеет ряд атрибутов, большинство из которых получены из параметров конструктора. (Обратите внимание, что имена не всегда точно соответствуют между параметрами конструктора LogRecord и атрибутами LogRecord.) Эти атрибуты можно использовать для объединения данных из записи в строку форматирования. В следующей таблице перечислены (в алфавитном порядке) имена атрибутов, их значения и соответствующий заполнитель в строке форматирования в стиле %.

Если используется форматирование через {} (str.format()), можно использовать {attrname} в качестве заполнителя в строке форматирования. Если используется $-форматирование (string.Template), используйте форму ${attrname}. В обоих случаях, конечно, замените attrname на фактическое имя атрибута, которое требуется использовать.

В случае форматирования через {} можно указать флаги форматирования, разместив их после имени атрибута, отделив двоеточием. Например: заполнитель {msecs:03d} отформатирует значение миллисекунд 4 как 004. Обратитесь к документации str.format() для получения полной информации о доступных опциях.

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

15.7.7. Объекты LoggerAdapter¶LoggerAdapter Objects

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

class logging.LoggerAdapter(logger, extra)¶

Возвращает экземпляр LoggerAdapter, инициализированный базовым экземпляром Logger и объектом, подобным словарю.

process(msg, kwargs)¶

Изменяет сообщение и/или именованные аргументы, переданные в вызов логирования, чтобы вставить контекстную информацию. Эта реализация берёт объект, переданный как extra конструктору, и добавляет его в kwargs с ключом 'extra'. Возвращаемое значение – кортеж (msg, kwargs), содержащий (возможно изменённые) версии переданных аргументов.

В дополнение к вышеперечисленному, LoggerAdapter поддерживает следующие методы Logger, а именно: debug(), info(), warning(), error(), exception(), critical(), log(), isEnabledFor(), getEffectiveLevel(), setLevel(), hasHandlers(). Эти методы имеют те же сигнатуры, что и их аналоги в Logger, поэтому два типа экземпляров можно использовать взаимозаменяемо.

Изменено в версии 3.2: Методы isEnabledFor(), getEffectiveLevel(), setLevel() и hasHandlers() были добавлены в LoggerAdapter. Эти методы делегируют выполнение базовому логгеру.

15.7.8. Безопасность потоков¶Thread Safety

Модуль logging спроектирован так, чтобы быть потокобезопасным без каких-либо специальных действий требуемых от его клиентов. Это достигается за счёт использования threading блокировок; одна блокировка сериализует доступ к общим данным модуля, а каждый обработчик также создаёт блокировку для сериализации доступа к своему нижележащему вводу-выводу.

Если вы реализуете асинхронные обработчики сигналов с помощью модуля signal, вы можете не иметь возможности использовать логирование из таких обработчиков. Это связано с тем, что реализации блокировок в модуле threading не всегда реентерабельны, и поэтому их нельзя вызывать из таких обработчиков сигналов.

15.7.9. Функции уровня модуля¶Module-Level Functions

В дополнение к классам, описанным выше, существует ряд функций уровня модуля.

logging.getLogger(name=None)¶

Возвращает регистратор с указанным именем или, если имя равно None, возвращает корневой регистратор иерархии. Если имя указано, оно обычно представляет собой иерархическое имя с точками в качестве разделителей, например 'a', 'a.b' или 'a.b.c.d'. Выбор этих имен полностью зависит от разработчика, использующего логирование.

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

logging.getLoggerClass()¶

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

class MyLogger(logging.getLoggerClass()):
    # ... переопределить поведение здесь

logging.getLogRecordFactory()¶

Возвращает вызываемый объект, который используется для создания LogRecord.

Новое в версии 3.2: Эта функция предоставлена вместе с setLogRecordFactory(), чтобы дать разработчикам больше контроля над тем, как конструируется LogRecord, представляющий событие журналирования.

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

logging.debug(msg, *args, **kwargs)¶

Записывает сообщение с уровнем DEBUG в корневой регистратор. msg – это форматная строка сообщения, а args – аргументы, которые объединяются с msg с помощью оператора форматирования строк. (Обратите внимание, что это означает, что в форматной строке можно использовать ключевые слова вместе с единственным аргументом-словарём.)

В kwargs проверяются три именованных аргумента: exc_info, который, если его значение не равно false, приводит к добавлению информации об исключении в сообщение логирования. Если предоставлен кортеж исключения (в формате, возвращаемом sys.exc_info()), используется он; в противном случае вызывается sys.exc_info() для получения информации об исключении.

Второй необязательный именованный аргумент – stack_info, по умолчанию равный False. Если указать True, в сообщение журнала добавляется информация о стеке, включая сам вызов журналирования. Обратите внимание, что это не та же информация о стеке, что отображается при указании exc_info: первая – это кадры стека от его основания до вызова журналирования в текущем потоке, тогда как вторая – информация о кадрах стека, которые были развёрнуты после возникновения исключения в процессе поиска обработчиков исключений.

Можно указать stack_info независимо от exc_info, например, чтобы просто показать, как был достигнут определённый участок кода, даже если исключения не возникали. Кадры стека выводятся после строки заголовка, которая гласит:

Stack (most recent call last):

Это имитирует Traceback (most recent call last):, который используется при отображении кадров исключений.

Третий необязательный именованный аргумент – extra, с помощью которого можно передать словарь, используемый для заполнения __dict__ объекта LogRecord, созданного для события логирования, пользовательскими атрибутами. Затем эти пользовательские атрибуты можно использовать по своему усмотрению. Например, их можно включать в логируемые сообщения. Пример:

FORMAT = '%(asctime)-15s %(clientip)s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logging.warning('Protocol problem: %s', 'connection reset', extra=d)

выведет что-то вроде:

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

Ключи в словаре, переданном в extra, не должны пересекаться с ключами, используемыми системой логирования. (См. документацию Formatter для получения дополнительной информации о том, какие ключи используются системой логирования.)

Если вы решите использовать эти атрибуты в логируемых сообщениях, нужно соблюдать осторожность. Например, в приведённом выше примере Formatter настроен с форматной строкой, которая ожидает 'clientip' и 'user' в словаре атрибутов LogRecord. Если они отсутствуют, сообщение не будет записано, так как возникнет исключение форматирования строки. Поэтому в этом случае всегда нужно передавать словарь extra с этими ключами.

Хотя это может быть раздражающим, эта функция предназначена для использования в специализированных обстоятельствах, таких как многопоточные серверы, где один и тот же код выполняется во многих контекстах, и интересующие условия зависят от этого контекста (например, IP-адрес удалённого клиента и имя аутентифицированного пользователя в приведённом выше примере). В таких обстоятельствах, скорее всего, будут использоваться специализированные Formatter с конкретными Handler.

Новое в версии 3.2: Был добавлен параметр stack_info.

logging.info(msg, *args, **kwargs)¶

Записывает сообщение с уровнем INFO в корневой регистратор. Аргументы интерпретируются так же, как для debug().

logging.warning(msg, *args, **kwargs)¶

Регистрирует сообщение с уровнем WARNING в корневом логгере. Аргументы интерпретируются так же, как для debug().

logging.error(msg, *args, **kwargs)¶

Записывает сообщение с уровнем ERROR в корневой регистратор. Аргументы интерпретируются так же, как для debug().

logging.critical(msg, *args, **kwargs)¶

Регистрирует сообщение с уровнем CRITICAL в корневом логгере. Аргументы интерпретируются так же, как для debug().

logging.exception(msg, *args)¶

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

logging.log(level, msg, *args, **kwargs)¶

Регистрирует сообщение с уровнем level в корневом логгере. Остальные аргументы интерпретируются так же, как для debug().

Примечание

Вышеупомянутые функции уровня модуля, которые делегируют вызов корневому логгеру, не следует использовать в потоках в версиях Python ниже 2.7.1 и 3.2, если только до запуска потоков в корневой логгер не был добавлен хотя бы один обработчик. Эти вспомогательные функции вызывают basicConfig(), чтобы гарантировать наличие хотя бы одного обработчика; в ранних версиях Python это (при редких обстоятельствах) может привести к многократному добавлению обработчиков в корневой логгер, что, в свою очередь, может привести к множественным сообщениям для одного события.

logging.disable(lvl)¶

Предоставляет переопределяющий уровень lvl для всех логгеров, который имеет приоритет над собственным уровнем логгера. Когда возникает необходимость временно снизить объём вывода журнала во всём приложении, эта функция может быть полезна. Её действие заключается в отключении всех вызовов журналирования с серьёзностью lvl и ниже, так что если вызвать её со значением INFO, то все события INFO и DEBUG будут отброшены, а события с серьёзностью WARNING и выше будут обрабатываться в соответствии с действующим уровнем логгера. Чтобы отменить эффект вызова logging.disable(lvl), вызовите logging.disable(logging.NOTSET).

logging.addLevelName(lvl, levelName)¶

Связывает уровень lvl с текстом levelName во внутреннем словаре, который используется для сопоставления числовых уровней с текстовым представлением, например, когда Formatter форматирует сообщение. Эта функция также может использоваться для определения собственных уровней. Единственные ограничения: все используемые уровни должны быть зарегистрированы с помощью этой функции, уровни должны быть положительными целыми числами и должны возрастать в порядке увеличения серьёзности.

Примечание

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

logging.getLevelName(lvl)¶

Возвращает текстовое представление уровня журналирования lvl. Если уровень является одним из предопределённых уровней CRITICAL, ERROR, WARNING, INFO или DEBUG, то возвращается соответствующая строка. Если вы связали уровни с именами с помощью addLevelName(), то возвращается имя, которое вы связали с lvl. Если передано числовое значение, соответствующее одному из определённых уровней, возвращается соответствующее строковое представление. В противном случае возвращается строка 'Level %s' % lvl.

logging.makeLogRecord(attrdict)¶

Создаёт и возвращает новый экземпляр LogRecord, атрибуты которого определяются attrdict. Эта функция полезна для приёма сериализованного (pickled) LogRecord словаря атрибутов, отправленного через сокет, и восстановления его как экземпляра LogRecord на принимающей стороне.

logging.basicConfig(**kwargs)¶

Выполняет базовую настройку системы журналирования, создавая StreamHandler с форматтером по умолчанию Formatter и добавляя его в корневой логгер. Функции debug(), info(), warning(), error() и critical() будут автоматически вызывать basicConfig(), если для корневого логгера не определено ни одного обработчика.

Эта функция ничего не делает, если для корневого логгера уже настроены обработчики.

Примечание

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

Поддерживаются следующие аргументы ключевых слов.

Формат	Описание
filename	Указывает, что создаётся FileHandler, с использованием указанного имени файла, а не StreamHandler.
filemode	Задает режим открытия файла, если указан filename (если filemode не указан, по умолчанию используется ‘a’).
format	Использует указанную строку формата для обработчика.
datefmt	Использовать указанный формат даты/времени.
style	Если указан format, используйте этот стиль для строки формата. Один из символов: '%', '{' или '$' для %-форматирования, str.format() или string.Template соответственно; по умолчанию используется '%', если не указано иное.
level	Установить уровень корневого регистратора на указанный уровень.
поток данных	Использовать указанный поток данных для инициализации StreamHandler. Обратите внимание, что этот аргумент несовместим с «filename» – если оба присутствуют, «поток данных» игнорируется.

Изменено в версии 3.2: Добавлен аргумент style.

logging.shutdown()¶

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

logging.setLoggerClass(klass)¶

Указывает системе логирования использовать класс klass при создании экземпляра логгера. Класс должен определять __init__() таким образом, чтобы требовался только аргумент name, а __init__() должен вызывать Logger.__init__(). Эта функция обычно вызывается до создания любых логгеров приложениями, которым требуется использовать собственное поведение логгера.

logging.setLogRecordFactory(factory)¶

Устанавливает вызываемый объект, который используется для создания LogRecord.

Параметры:	factory – вызываемый объект фабрики, используемый для создания записи журнала.

Новое в версии 3.2: Эта функция предоставлена вместе с getLogRecordFactory(), чтобы дать разработчикам больше контроля над тем, как создаётся LogRecord, который представляет событие журналирования.

Фабрика имеет следующую сигнатуру:

factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, **kwargs)

имя:	Имя регистратора.
уровень:	Уровень логирования (числовой).
fn:	Полный путь к файлу, в котором был выполнен вызов логирования.
lno:	Номер строки в файле, в котором был выполнен вызов логирования.
сообщение:	Сообщение логирования.
аргументы:	Аргументы для сообщения логирования.
exc_info:	Кортеж исключения или None.
func:	Имя функции или метода, из которого был сделан вызов логирования.
sinfo:	Трассировка стека, например, предоставляемая функцией traceback.print_stack(), показывающая иерархию вызовов.
kwargs:	Дополнительные именованные аргументы.

15.7.10. Атрибуты уровня модуля¶Module-Level Attributes

logging.lastResort¶

Через этот атрибут доступен «обработчик последней надежды». Это StreamHandler, который пишет в sys.stderr с уровнем WARNING и используется для обработки событий логирования при отсутствии какой-либо конфигурации логирования. В конечном итоге сообщение просто выводится в sys.stderr. Это заменяет раннее сообщение об ошибке, которое говорило, что «не удалось найти обработчики для логгера XYZ». Если по какой-то причине требуется прежнее поведение, lastResort можно установить в None.

Новое в версии 3.2.

15.7.11. Интеграция с модулем warnings¶Integration with the warnings module

Функция captureWarnings() может использоваться для интеграции logging с модулем warnings.

logging.captureWarnings(capture)¶

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

Если capture равно True, предупреждения, выпущенные модулем warnings, будут перенаправлены в систему логирования. В частности, предупреждение будет отформатировано с помощью warnings.formatwarning(), и результирующая строка будет записана в логгер с именем 'py.warnings' с уровнем важности WARNING.

Если capture равно False, перенаправление предупреждений в систему логирования прекратится, и предупреждения будут перенаправляться на исходные места назначения (т.е. те, которые действовали до вызова captureWarnings(True)).