logging — Система ведения журнала для Python

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

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

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

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

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

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

16.6.1. Объекты логгера

Логгеры имеют следующие атрибуты и методы. Обратите внимание, что логгеры никогда не создаются напрямую, а всегда через функцию модуля 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

propagate

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

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

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

Примечание

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

setLevel(level)

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

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

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

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

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

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

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

isEnabledFor(lvl)

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

getEffectiveLevel()

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

getChild(suffix)

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

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

debug(msg, *args, **kwargs)

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

В kwargs проверяются три ключевых аргумента: exc_info, stack_info и extra.

Если exc_info не ложно, это добавляет информацию об исключении в сообщение логгирования. Если предоставлена кортеж исключения (в формате, возвращаемом 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.

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

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(lvl, msg, *args, **kwargs)

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

exception(msg, *args, **kwargs)

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

addFilter(filter)

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

removeFilter(filter)

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

filter(record)

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

addHandler(hdlr)

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

removeHandler(hdlr)

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

findCaller(stack_info=False)

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

handle(record)

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

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

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

hasHandlers()

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

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

Изменено в версии 3.7: Теперь логгеры можно получать и распаковывать.

16.6.2. Уровни ведения журнала

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

16.6.3. Объекты обработчиков

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

class logging.Handler

__init__(level=NOTSET)

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

createLock()

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

acquire()

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

release()

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

setLevel(level)

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

См. Уровни ведения журнала для списка уровней.

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

setFormatter(fmt)

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

addFilter(filter)

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

removeFilter(filter)

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

filter(record)

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

flush()

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

close()

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

handle(record)

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

handleError(record)

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

format(record)

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

emit(record)

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

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

16.6.4. Объекты форматизаторов

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

Форматировщик можно инициализировать строкой формата, которая использует знания об атрибутах LogRecord — например, о значениях по умолчанию, используя тот факт, что сообщение пользователя и аргументы предварительно отформатированы в атрибут message записи LogRecord. Эта строка формата содержит стандартные ключи сопоставления в стиле Python %. Для получения дополнительной информации об форматировании строк см. раздел Форматирование строк в стиле printf.

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

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

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

Параметр 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() для форматирования времени создания записи. В противном случае используется формат ‘%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'), а часть после запятой — значение миллисекунд. Поскольку strptime не имеет формального заполнитель для миллисекунд, значение миллисекунд добавляется с помощью другой строки формата, '%s,%03d' — и обе эти строки формата были жестко заданы в этом методе. После изменения эти строки определены как атрибуты уровня класса, которые могут быть переопределены на уровне экземпляра при необходимости. Имена атрибутов default_time_format (для строки формата strptime) и default_msec_format (для добавления значения миллисекунд).

formatException(exc_info)

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

formatStack(stack_info)

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

16.6.5. Объекты-фильтры

Filters могут использоваться Handlers и Loggers для более сложной фильтрации, чем предоставляется уровнями. Базовый класс фильтра допускает только события, которые находятся ниже определённой точки в иерархии логгеров. Например, фильтр, инициализированный ‘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 с той же семантикой.

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

16.6.6. Объекты LogRecord

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)

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

16.6.7. Атрибуты LogRecord

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

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

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

16.6.8. Объекты LoggerAdapter

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, поэтому вы можете использовать два типа экземпляров взаимозаменяемо.

16.6.9. Безопасность потоков

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

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

16.6.10. Функции уровня модуля

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

logging.getLogger(name=None)

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

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

logging.getLoggerClass()

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

class MyLogger(logging.getLoggerClass()):
    # ... override behaviour here

logging.getLogRecordFactory()

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

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

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

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

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

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

Второй необязательный аргумент ключевого слова — stack_info, по умолчанию равный False. Если он равен истине, в сообщение регистрации добавляется информация о стеке вызовов, включая сам вызов регистрации. Обратите внимание, что это не та же информация о стеке вызовов, что и при указании 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().

Примечание

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

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

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

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

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

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

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

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

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

Примечание

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

logging.disable(lvl=CRITICAL)

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

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

Изменено в версии 3.7: Параметр lvl был по умолчанию установлен в уровень CRITICAL. Подробности об этом изменении см. в Issue #28524.

logging.addLevelName(lvl, levelName)

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

Примечание

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

logging.getLevelName(lvl)

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

Примечание

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

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

logging.makeLogRecord(attrdict)

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

logging.basicConfig(**kwargs)

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

Если корневой логикатор уже настроен, эта функция ничего не делает.

Примечание

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

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

Формат	Описание
filename	Указывает на создание FileHandler, используя указанное имя файла, вместо StreamHandler.
filemode	Если указано filename, откройте файл в этом режиме. По умолчанию 'a'.
format	Используйте указанную строку формата для обработчика.
datefmt	Используйте указанный формат даты/времени, как это допускается time.strftime().
style	Если указано format, используйте этот стиль для строки формата. Один из '%', '{' или '$' для форматирования в стиле printf, str.format() или string.Template соответственно. По умолчанию '%'.
level	Установите уровень корневого логикатора на указанный уровень.
stream	Используйте указанный поток для инициализации StreamHandler. Обратите внимание, что этот аргумент несовместим с filename - если оба присутствуют, будет поднята ValueError.
handlers	Если указано, это должен быть итерируемый объект из уже созданных обработчиков для добавления в корневой логикатор. Любые обработчики, которые еще не имеют установленного форматера, получат форматер по умолчанию, созданный в этой функции. Обратите внимание, что этот аргумент несовместим с filename или stream - если оба присутствуют, будет поднята ValueError.

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

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

logging.shutdown()

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

logging.setLoggerClass(klass)

Устанавливает для системы логирования класс klass при создании экземпляра логикатора. Класс должен определять __init__() так, чтобы требовался только аргумент имени, и __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)

name

Имя логикатора.

level

Уровень логирования (числовой).

fn

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

lno

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

msg

Сообщение логирования.

args

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

exc_info

Кортеж исключения или None.

func

Имя функции или метода, вызвавшего логирование.

sinfo

Стек отладки, подобный предоставляемому traceback.print_stack(), показывающий иерархию вызовов.

kwargs

Дополнительные ключевые аргументы.

16.6.11. Атрибуты уровня модуля

logging.lastResort

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

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

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

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

logging.captureWarnings(capture)

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

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

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