Модуль logging определяет функции и классы, которые реализуют гибкую систему лога для приложений и библиотек Python.

Основное достоинство API модуля logging, предоставляемого стандартной библиотекой, состоит в том, что все модули Python могут участвовать в логе, так что лог вашего приложения может включать свои собственные сообщения, интегрированные с сообщениями из модулей сторонних производителей.

Вот простой пример идиоматического использования лога для приложения:

# myapp.py
import logging
import mylib

logger = logging.getLogger(__name__)

def main():
    logging.basicConfig(filename='myapp.log', level=logging.INFO)
    logger.info('Программа запущена')
    mylib.do_something()
    logger.info('Программа завершена')

if __name__ == '__main__':
    main()

Для пользовательского модуля:

# mylib.py
import logging

logger = logging.getLogger(__name__)

def do_something():
    logger.info('Некоторые действия')

Если вы запустите myapp.py, то должны увидеть следующее в файле myapp.log:

INFO:__main__:Программа запущена
INFO:mylib:Некоторые действия
INFO:__main__:Программа завершена

Для вывода в лог от программиста требуется минимум усилий - нужно просто создать объект лога с помощью getLogger(__name__), и использовать его в любом нужном месте. Выводимые сообщения лога на уровне модуля объект logger пересылает обработчикам лога в модулях более высокого уровня, вплоть до самого верхнего, так называемого корневого, или верхнего уровня (root logger); этот подход известен как иерархическое логирование.

Для успешного вывода в лог он должен быть сконфигурирован: установлены уровни и место назначения сообщений для каждого логгера, что потенциально меняет поведение лога определенных модулей, часто на основании аргументов командной строки или конфигурации приложения. Во многих случаях, как в показанном выше примере, необходимо сконфигурировать только логгер верхнего уровня (root logger), поскольку все более низкоуровневые логгеры на уровне модуля иногда перенаправляют свои сообщения собственным обработчикам. Метод basicConfig() предоставляет простой способ конфигурирования root-логгера, что подходит для многих случаев использования.

Основные классы, определенные модулем, а также их атрибуты и методы перечислены в разделах ниже.

• Регистраторы лога (Logger) предоставляют интерфейс, который непосредственно использует код приложения.
• Обработчики (Handler) посылают сообщения лога (созданные регистраторами) в подходящее место назначения.
• Фильтры (Filter) позволяют тонко управлять тем, какие записи должны попадать в лог.
• Форматтеры (Formatter) определяют вид записей лога в окончательном выводе.

[Объекты Logger]

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

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

class logging.Logger

name

Имя регистратора, и это значение было передано в getLogger() для получения регистратора.

Замечание: этот атрибут должен обрабатываться как read-only (только для чтения).

level

Пороговый уровень вывода регистратора, установленный методом setLevel().

Замечание: не устанавливайте этот атрибут напрямую, всегда используйте для этой цели setLevel(), который проверяет переданный в него уровень.

parent

Родительский регистратор для этого регистратора. Он может изменяться на основе более поздней реализации регистраторов, которые выше в иерархии пространства имен.

Замечание: это значение должно обрабатываться как read-only (только для чтения).

propagate

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

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

Объяснение на примере: если атрибут propagate логгера с именем A.B.C вычисляется как true, то любые события, регистрируемые в логе для A.B.C через вызов метода, такого как logging.getLogger('A.B.C').error(...) будет [при условии передачи уровня этого логгера и настроек фильтра] передаваться в свою очередь любым обработчикам, присоединенным к логгерам с именем A.B, A и root-логгеру, после того, как сначала сообщения события были переданы любым обработчикам, присоединенным к A.B.C. Если любой логгер в цепочке A.B.C, A.B, A имеет атрибут propagate, установленный в false, то это последний логгер, обработчикам которого предлагается обработать событие, и распространение останавливается на этой точке.

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

Замечание: если вы подсоедините обработчик к логгеру и одному или нескольким его предкам, он может выдавать одну или несколько одинаковых записей несколько раз. Как правило вам не нужно присоединять обработчики к более чем одному логгеру - если вы просто подсоедините его подходящему регистратору, который является самым верхним в иерархии логгеров, то он увидит все события, выведенные в лог всеми нижележащими логгерами при условии, что все их настройки propagate оставлены установленными в True. Обычный сценарий состоит в том, чтобы присоединять обработчики только к root-логгеру logger, и распространение (propagate) позаботится от остальном.

handlers

Список обработчиков, напрямую подсоединенных к этому экземпляру логгера.

Обратите внимание, что этот атрибут обрабатывается как read-only; он обычно меняется через методы addHandler() и removeHandler(), которые используют блокировки для гарантии thread-safe функционирования.

disabled

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

Замечание: этот атрибут должен обрабатываться как read-only.

setLevel(level)

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

Когда создается логгер, его уровень устанавливается на NOTSET (который вызывает обработку всех сообщений, когда логгер является корневым, т. е. root logger, или происходит делегирование родителю, если логгер не корневой). Обратите внимание, что root logger создается с уровне WARNING.

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

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

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

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

| Изменено в версии 3.2: параметр level теперь принимает строковое представление уровня, такое как 'INFO', в качестве альтернативы целочисленным константам, таким как INFO. Однако имейте в виду, что уровни внутренне хранятся как целые числе, и такие методы, как например getEffectiveLevel() и isEnabledFor() возвращают/ожидают переданные целые числа.

isEnabledFor(level)

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

getEffectiveLevel()

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

getChild(suffix)

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

| Добавлено в версии 3.2.

getChildren()

Возвратит набор логгеров, которые являются непосредственными потомками этого логгера. Так например logging.getLogger().getChildren() может возвратить набор, содержащий логгеры с именами foo и bar, но логгер с именем foo.bar не будет включен в набор. Подобным образом logging.getLogger('foo').getChildren() может возвратить набор, включающий логгер с именем foo.bar, но он не будет включать в себя логгер с именем foo.bar.baz.

| Добавлено в версии 3.12.

debug(msg, *args, **kwargs)

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

В kwargs проверяются 4 именованных аргумента (keyword argument): exc_info, stack_info, stacklevel и extra.

Если 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): который используется при отображении фреймов исключения.

Третий опциональный аргумент это stacklevel, который по умолчанию 1. Если больше 1, то пропускается соответствующее количество фреймов стека при вычислении номера строки и имени функции, заданных в LogRecord, созданном для события лога. Это может использоваться в помощниках по логу, чтобы записанные имя функции, имя файла и номер строки были не информацией для функции/метода помощника, а скорее её вызывающей стороной. Имя этого параметра отражает эквивалентное имя в модуле warnings.

Четвертый именованный аргумент является дополнительным, который может использоваться для передачи словаря для заполнения пользовательскими атрибутами __dict__ LogRecord, созданной для события лога. Эти пользовательские атрибуты могут затем использоваться по вашему усмотрению. Например, они могут быть включены в сообщения лога:

FORMAT = '%(asctime)s %(clientip)-15s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logger = logging.getLogger('tcpserver')
logger.warning('Проблема протокола: %s', 'connection reset', extra=d)

Это напечатает что-то наподобие:

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Проблема протокола: connection reset

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

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

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

Если к этому логгеру не был присоединен обработчик (или к любому из его предков с учетом соответствующих атрибутов Logger.propagate), то сообщение будет отправлено набору обработчиков на lastResort.

| Изменено в версии 3.2: добавлен параметр stack_info.

| Изменено в версии 3.5: параметр exc_info теперь может принимать экземпляры исключений.

| Изменено в версии 3.8: добавлен параметр stacklevel.

info(msg, *args, **kwargs)

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

warning(msg, *args, **kwargs)

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

Замечание: существует устаревший метод warn, который функционально идентичен warning. Поскольку warn устарел, то всегда используйте вместо него warning.

error(msg, *args, **kwargs)

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

critical(msg, *args, **kwargs)

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

log(level, msg, *args, **kwargs)

Выведет сообщение с целочисленным уровнем level на этом логгере. Другие аргументы интерпретируются также как для debug().

exception(msg, *args, **kwargs)

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

addFilter(filter)

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

removeFilter(filter)

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

filter(record)

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

addHandler(hdlr)

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

removeHandler(hdlr)

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

findCaller(stack_info=False, stacklevel=1)

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

Параметр stacklevel передается из кода, вызвавшего debug() и другие API-функции. Если больше 1, то избыточное значение используется для пропуска фреймов стека перед определением возвращаемых значений. Это как правило, будет полезно при вызове API лога из кода helper/wrapper, чтобы информация в логе событий ссылалась не на код helper/wrapper, а на код, который его вызывает.

handle(record)

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

makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)

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

hasHandlers()

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

| Добавлено в версии 3.2.

| Изменено в версии 3.7: логгеры могут быть pickled и unpickled.

[Уровни лога]

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

[Объекты Handler]

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

class logging.Handler

__init__(level=NOTSET)

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

createLock()

Инициализирует блокировку потока (thread lock), которая может использоваться для сериализации доступа к нижележащему функционалу I/O, который может быть не потокобезопасный.

acquire()

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

release()

Освободит блокировку потока, захваченную acquire().

setLevel(level)

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

См. список уровней лога.

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

setFormatter(fmt)

Установит форматтер fmt для этого обработчика. Аргумент fmt должен быть экземпляром Formatter либо None.

addFilter(filter)

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

removeFilter(filter)

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

filter(record)

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

flush()

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

close()

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

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

handle(record)

Условно выдает указанную запись лога, в зависимости от фильтров, которые могли быть добавлены в обработчик. Обертывает фактическую эмиссию record с получением/освобождением блокировки ввода/вывода потока (I/O thread lock).

handleError(record)

Этот метод должен быть вызван из обработчиков, когда обнаружилось исключение во время вызова emit(). Если атрибут уровня модуля raiseExceptions == False, то исключения тихо игнорируются. Это то, что в основном требуется для системы регистрации - большинство пользователей не будут заботиться об ошибках в системе лога, их больше интересуют ошибки приложения. Однако при желании вы можете заменить это пользовательским обработчиком. Указанная record является той, которая обрабатывалась при возникновении исключения (значение по умолчанию raiseExceptions == True, что больше подходит во время разработкиas that is more useful during development).

format(record)

Выполняет форматирование для записи record - если форматтер установлен, то он используется. Иначе используется форматтер по умолчанию для модуля.

emit(record)

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

Предупреждение: этот метод вызывается после того, как была захвачена блокировка уровня обработчика, которая освобождается после возврата из этого метода. Когда вы переопределяете этот метод, будьте осторожны при вызове всего, что вовлекает другие части logging API, которые могут делать блокировку, потому что это может привести к deadlock. В особенности:

• API-функции конфигурации лога захватывают блокировку на уровне модуля, и затем отдельные блокировки уровня обработчика, когда эти обработчики конфигурируются.
• Многие API-функции лога применяют блокировку на уровне модуля. Если такой вызов API сделан из этого метода, то он приведет к deadlock, если конфигурационный вызов сделан их другого потока, потому что этот поток попытается захватить блокировку уровня модуля перед блокировкой уровня обработчика, а то время как этот поток пытается получить блокировку на уровне модуля после блокировки на уровне обработчика (потому что в этом методе блокировка уровня обработчика уже была захвачена).

Список стандартных обработчиков см. в [5].

[Объекты Formatter]

class logging.Formatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Отвечает за преобразование LogRecord в выводимую строку, интерпретируемую человеком или внешней системой.

Параметры:

fmt (str) – строка формата в заданном стиле для регистрируемых выходных данных в целом. Возможные ключи для сопоставления извлекаются из атрибутов объекта LogRecord. Если не указано, то используется '%(message)s', что является просто выводимым в лог сообщением.

datefmt (str) – строка формата в заданном стиле для порции даты/времени вывода лога. Если не указано, то используется умолчание, описанное в formatTime().

style (str) – может быть одним из '%', '{' или '$', и определяет, как строка формата будет сливаться с её данными: используется один из стилей printf String Formatting (%), str.format() ({) или string.Template ($). Это применяется только к fmt и datefmt (например '%(message)s' против '{message}'), но не к фактическим сообщениям лога, переданным в методы логирования. Однако есть другие пути использования {- и $-форматирования для сообщений лога.

validate (bool) – если True (по умолчанию), то некорректный или не соответствующий fmt и style будет выбрасывать исключение ValueError; например logging.Formatter('%(asctime)s - %(message)s', style='{').

defaults (dict[str, Any]) – словарь со значениями по умолчанию для использования в пользовательских полях. Например, logging.Formatter('%(ip)s %(message)s', defaults={"ip": None}).

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

| Изменено в версии 3.8: добавлен параметр validate.

| Изменено в версии 3.10: добавлен параметр defaults.

format(record)

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

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

formatTime(record, datefmt=None)

Этот метод должен быть вызван из format() форматтером, который хочет использовать форматированное время. Этот метод может быть переназначен в форматтерах для обеспечения любого конкретного требования, однако базовое поведение следующее: если указан datefmt (строкой), то это используется с time.strftime() для форматирования времени создания записи. Иначе используется формат '%Y-%m-%d %H:%M:%S,uuu', где часть uuu это значение миллисекунд, и другие буквы спецификации соответствуют документации time.strftime(). Пример представления времени в этом формате: 2003-01-23 00:29:50,411. Будет возвращена результирующая строка.

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

| Изменено в версии 3.3: ранее формат по умолчанию был жестко зашит в коде, как в этом примере: 2010-09-06 22:38:15,292, где часть перед запятой обрабатывалась строкой формата strptime ('%Y-%m-%d %H:%M:%S'), а часть после запятой это значение миллисекунд. Поскольку нет местозаполнителя формата для миллисекунд, значение миллисекунд присоединяется с использованием другой строки формата '%s,%03d' — и обе эти строки формата жестко вшиты в коде этого метода. При введении изменения эти строки определены как атрибуты уровня класса, которые можно переопределить в на уровне экземпляра, когда это необходимо. Имена атрибутов default_time_format (для строки формата strptime) и default_msec_format (для присоединения значения миллисекунд).

| Изменено в версии 3.9: default_msec_format может быть None.

formatException(exc_info)

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

formatStack(stack_info)

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

class logging.BufferingFormatter(linefmt=None)

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

formatHeader(records)

Возвратит заголовок для списка записей records. Базовая реализация просто возвратит пустую строку. Вам понадобится переопределить этот метод, если вы хотите получить специальное поведение, например показать количество записей, заголовок или строку разделителя.

formatFooter(records)

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

format(records)

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

[Объекты Filter]

Фильтры могут использоваться обработчиками (Handler) и логгерами (Logger) для более продвинутой фильтрации, чем предоставляют уровни лога. Базовый класс фильтра допускает только события, которые находятся ниже определенной точки в иерархии логгера. Например, если фильтр инициализирован '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, то это указывает логгер, который вместе со своими потомками будет разрешать событиям проходить через фильтр. Если имя это пустая строка, то разрешены все события.

filter(record)

Должна ли быть выведена в лог запись record? Возвратит false если нет, true если yes. Фильтры могут либо модифицировать записи лога по месту, или возвратить полностью другой экземпляр записи, которая заменит оригинальную запись лога в любой будущей обработке события.

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

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

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

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

Хотя фильтры используются главным образом для фильтрации записей на основе более продвинутых критериев, чем уровни, они видят каждую запись которая обрабатывается Handler или Logger, к которому они были прикреплены: это может быть полезно, если вы хотите например подсчитать, сколько записей было обработано определенным логгером или обработчиком, либо добавить, изменить или удалить атрибуты в обрабатываемой LogRecord. Очевидно, что изменение LogRecord должно быть сделано с некоторой осторожностью, но оно позволяет вводить контекстную информацию в логи (см. Using Filters to impart contextual information [6]).

[Объекты LogRecord]

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

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

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

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

Параметры:

name (str) – имя логгера, используемого для лога события, представленного этой LogRecord. Обратите внимание, что имя логгера в LogRecord будет всегда иметь это значение, даже если оно может быть выдано обработчиком, подключенным к другому логгеру (предку).

level (int) – числовое значение уровня отправляемого в лог события (такое как 10 для DEBUG, 20 для INFO, и т. д.). Обратите внимание, что это преобразуется в 2 атрибута LogRecord: levelno для числового значения и levelname для соответствующего имени уровня.

pathname (str) – полный строковый путь к исходному файлу, в котором был выполнен вызов лога.

lineno (int) – номер строки исходного файла, где был сделан вызов лога.

msg (Any) – сообщение описания события, которое может быть строкой %-формата с местами размещения данных переменных или произвольных объектов (см. Using arbitrary objects as messages [2]).

args (tuple | dict[str, Any]) – данные переменной для вставки в аргумент msg для получения описания события.

exc_info (tuple[type[BaseException], BaseException, types.TracebackType] | None) – кортеж исключения с текущей информацией исключения, как это возвращается sys.exc_info(), или None, если информация исключения недоступна.

func (str | None) – имя функции или метода, из которого был сделан вызвов лога.

sinfo (str | None) – строка текста, представляющая информацию стека из базы стека в текущем потоке, до момента вызова лога.

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)

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

[Атрибуты LogRecord]

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

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

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

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

| Изменено в версии 3.12: было добавлено taskName.

[Объекты LoggerAdapter]

Экземпляры LoggerAdapter используются для удобной передачи контекстной информации в вызовы лога. Для примера использования см. секцию добавления контекстной информации в ваш вывод лога [3].

class logging.LoggerAdapter(logger, extra, merge_extra=False)

Возвратит экземпляр LoggerAdapter, инициализированный нижележащим экземпляром Logger, объектом наподобие словаря (extra) и boolean (merge_extra), показывающий, следует ли объединять дополнительный аргумент отдельных вызовов лога с дополнительным LoggerAdapter. Поведение по умолчанию - игнорировать аргумент extra индивидуальных вызовов лога и использовать только один экземпляр LoggerAdapter.

process(msg, kwargs)

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

manager

Делегирует нижележащему менеджеру на логгере.

_log

Делегирует нижележащему методу _log() на логгере.

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

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

| Изменено в версии 3.6: добавлен атрибут manager и метод method _log(), которые делегируют нижележащему логгеру и позволяют применять вложенные адаптеры.

| Изменено в версии 3.13: добавлен аргумент merge_extra.

[Безопасность потоков]

Модуль регистрации предназначен для защиты потоков (thread-safe) без необходимости выполнения каких-либо специальных работ его клиентами. Это достигается с помощью использования блокировок потоков (threading locks); одна блокировка используется для сериализации доступа к общим данным модуля, и каждый обработчики также создает блокировку для сериализации доступа к своему нижележащему I/O.

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

[Функции уровня модуля]

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

logging.getLogger(name=None)

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

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

logging.getLoggerClass()

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

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

logging.getLogRecordFactory()

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

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

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

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

Это удобная функция, которая вызывает Logger.debug() на корневом логгере (root logger). Обработка аргументов во всех отношениях подобна тому, что приведено в описании для этого метода.

Единственное отличие в том, что если у root logger нет обработчиков, то вызывается basicConfig() перед вызовом debug на root logger.

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

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

Выведет в лог сообщение в уровнем INFO на корневом логгере. В остальном аргументы и поведение те же, что и для debug().

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

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

Обратите внимание, что существует устаревшая функция warn, функционал которой идентичен warning. Поскольку warn устарела, используйте вместо неё функцию warning.

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

Выведет в лог сообщение в уровнем ERROR на корневом логгере. В остальном аргументы и поведение те же, что и для debug().

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

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

logging.exception(msg, *args, **kwargs)

Выведет в лог сообщение в уровнем ERROR on the root logger. В остальном аргументы и поведение те же, что и для debug(). Exception info is added to the logging message. This function should only be called from an exception handler.

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

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

logging.disable(level=CRITICAL)

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

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

| Изменено в версии 3.7: параметр level стал по умолчанию уровня CRITICAL. См. bpo-28524 для дополнительной информации по этому изменению.

logging.addLevelName(level, levelName)

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

Замечание: если вы думаете об определении своих собственных уровней, см. описание пользовательских уровней документации HOWTO [7].

logging.getLevelNamesMapping()

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

| Добавлено в версии 3.11.

logging.getLevelName(level)

Возвратит текстовое или числовое представление уровня лога level.

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

Параметр level также принимает строковое представление уровня, такое как 'INFO'. В таких случаях эта функция возвратит соответствующее числовое значение уровня.

Если не существует числового или строкового значения, переданного в функцию, то возвращается строка ‘Level %s’ % уровня.

Замечание: уровни внутри модуля это целые числа (поскольку они должны сравниваться логикой лога). Эта функция используется для преобразования между целочисленным уровнем и именем уровня, отображаемом в форматированном выводе лога с помощью спецификатора формата %(levelname)s (см. описание атрибутов LogRecord), и наоборот.

| Изменено в версии 3.4: в версиях Python, более ранних чем 3.4, эта функция может быть также передана на текстовый уровень, и будет возвращать соответствующее числовое представление уровня. Это не документированное поведение считалось ошибкой, и было удалено в Python 3.4, но было восстановлено в 3.4.2 для сохранения обратной совместимости.

logging.getHandlerByName(name)

Возвратит обработчик с указанным именем или None, если нет обработчика с таким именем.

| Добавлено в версии 3.12.

logging.getHandlerNames()

Возвратит немутируемый набор всех известных имен обработчиков.

| Добавлено в версии 3.12.

logging.makeLogRecord(attrdict)

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

logging.basicConfig(**kwargs)

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

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

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

Поддерживаются следующие именованные аргументы (keyword arguments).

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

| Изменено в версии 3.3: добавлен аргумент handlers. Добавлены дополнительные проверки для перехвата ситуаций, где указаны несовместимые аргументы (например handlers вместе со stream или filename, или stream вместе с filename).

| Изменено в версии 3.8: добавлен аргумент force.

| Изменено в версии 3.9: добавлены аргументы encoding и errors.

logging.shutdown()

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

Когда модуль logging импортирован, он регистрирует эту функцию как обработчик выхода (exit handler, см. atexit [4]), так что обычно нет необходимости делать это вручную.

logging.setLoggerClass(klass)

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

logging.setLogRecordFactory(factory)

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

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

| Добавлено в версии 3.2: эта функция была предоставлена вместе с getLogRecordFactory(), чтобы дать разработчикам больше контроля над тем, как создается LogRecord предоставляющая событие лога.

У factory следующая сигнатура:

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

name: имя логгера.

level: уровень лога (числовой).

fn: полное имя файла, где был сделан вызов лога.

lno: номер строки в файле, где был сделан вызов лога.

msg: сообщение лога.

args: аргументы для сообщения лога.

exc_info: кортеж исключения, или None.

func: имя функции (или метода), которая вызвала вывод в лог.

sinfo: информация стека, такая как предоставляется traceback.print_stack(), в которой показана иерархия вызовов.

kwargs: дополнительные именованные аргументы.

[Атрибуты уровня модуля]

logging.lastResort

Обработчик последнего шанса (handler of last resort) доступен через этот атрибут. Это StreamHandler, записывающий в sys.stderr с уровнем WARNING, и используемый для обработки событий ведения лога при отсутствии какой-либо конфигурации лога. Конечный результат - просто печать сообщения в sys.stderr. Это заменяет предыдущее сообщение об ошибке, говорящее что "no handlers could be found for logger XYZ" (не найдены обработчики для логгера XYZ). Если по какой-либо причине требуется более раннее поведение, для lastResort можно установить значение None.

| Добавлено в версии 3.2.

logging.raiseExceptions

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

По умолчанию: True. Если raiseExceptions == False, то исключения тихо игнорируются. Это то, что в основном требуется для системы лога - большинство пользователей не будут заботиться от ошибках в системе лога, их больше интересуют ошибки приложения.

[Интеграция с модулем warnings]

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

logging.captureWarnings(capture)

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

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

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

[Ссылки]

1. logging — Logging facility for Python site:python.org.
2. Using arbitrary objects as messages site:python.org.
3. Adding contextual information to your logging output site:python.org.
4. atexit — Exit handlers site:python.org.
5. logging.handlers — Logging handlers site:python.org.
6. Logging Cookbook site:python.org.
7. Python Logging HOWTO.