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

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

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

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

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

# myapp.py
import logging
import mylib
logger = logging.getLogger(__name__)

def main():
    logging.basicConfig(filename='myapp.log', level=logging.INFO)
    logger.info('Started')
    mylib.do_something()
    logger.info('Finished')

if __name__ == '__main__':
    main()

# mylib.py
import logging
logger = logging.getLogger(__name__)

def do_something():
    logger.info('Doing something')

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

INFO:__main__:Started
INFO:mylib:Doing something
INFO:__main__:Finished

Ключевые особенности этого идиоматического подхода: большая часть кода лишь создаёт логгер на уровне модуля с помощью getLogger(__name__) и использует его для выполнения необходимых операций ведения журнала. Такой подход лаконичен и при этом позволяет вызывающему коду при необходимости детально управлять поведением. Зарегистрированные сообщения, отправленные логгеру уровня модуля, передаются обработчикам логгеров в модулях более высокого уровня, вплоть до корневого логгера; поэтому этот подход называется иерархическим ведением журналов.

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

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

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

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

Объекты Logger

Логгеры имеют следующие атрибуты и методы. Обратите внимание: объекты Logger НИКОГДА не следует создавать напрямую — для этого всегда нужно использовать функцию уровня модуля 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

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

Примечание

Этот атрибут следует считать доступным только для чтения.

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

Примечание

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

parent: Родительский логгер этого логгера. Он может измениться при последующем создании логгеров, находящихся выше в иерархии пространства имён.

Примечание

Это значение следует считать доступным только для чтения.

propagate

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

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

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

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

Примечание

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

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

Примечание

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

disabled: Этот атрибут отключает обработку любых событий. В инициализаторе ему присваивается значение False; изменяется он только кодом настройки ведения журналов.

Примечание

Этот атрибут следует считать доступным только для чтения.

setLevel(level)

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

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

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

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

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

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

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

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

getEffectiveLevel(): Показывает эффективный уровень этого логгера. Если с помощью setLevel() было задано значение, отличное от NOTSET, оно возвращается. В противном случае выполняется обход иерархии в направлении корневого логгера, пока не будет найдено значение, отличное от 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 с помощью оператора форматирования строк. (Это означает, что в форматирующей строке можно использовать ключевые слова вместе с одним аргументом-словарём.) Если аргументы args не переданы, операция форматирования с помощью % для msg не выполняется.

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

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

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

Четвёртый именованный аргумент — extra. С его помощью можно передать словарь, который используется для заполнения __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('Protocol problem: %s', 'connection reset', extra=d)

выведет примерно следующее:

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: 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(). К сообщению журнала добавляются сведения об исключении. Этот метод следует вызывать только из обработчика исключений.

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

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

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

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

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

findCaller(stack_info=False, stacklevel=1)

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

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

handle(record): Обрабатывает запись, передавая её всем обработчикам, связанным с этим логгером и его предками (до тех пор, пока не будет найдено ложное значение 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: Теперь объекты Logger можно сериализовать и десериализовать.

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

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

Уровень	Числовое значение	Значение / Когда использовать
`logging.NOTSET`	0	Если установлен для логгера, указывает, что для определения эффективного уровня нужно проверить логгеры-предки. Если в результате по-прежнему получается `NOTSET`, регистрируются все события. Если установлен для обработчика, обрабатываются все события.
`logging.DEBUG`	10	Подробная информация, обычно интересная только разработчику, который пытается диагностировать проблему.
`logging.INFO`	20	Подтверждение того, что всё работает ожидаемым образом.
`logging.WARNING`	30	Указывает на то, что произошло что-то неожиданное или что в ближайшем будущем может возникнуть проблема (например, «мало места на диске»). Программное обеспечение пока работает ожидаемым образом.
`logging.ERROR`	40	Из-за более серьёзной проблемы программному обеспечению не удалось выполнить какую-либо функцию.
`logging.CRITICAL`	50	Серьёзная ошибка, указывающая на то, что программа может оказаться не в состоянии продолжить работу.

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

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

class logging.Handler

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

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

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

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

setLevel(level)

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

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

setFormatter(fmt): Устанавливает для этого обработчика форматировщик Formatter в значение fmt.

addFilter(filter): Добавляет указанный фильтр filter к этому обработчику.

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

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

flush(): Гарантирует сброс всех выходных данных журналирования. Эта версия ничего не делает и предназначена для реализации в подклассах.

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

handle(record): Условно выводит указанную запись журнала в зависимости от фильтров, добавленных к обработчику. Оборачивает фактический вывод записи захватом и освобождением блокировки потока ввода-вывода.

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

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

emit(record)

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

Предупреждение

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

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

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

Объекты форматировщиков

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

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

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

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

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

Параметр style может принимать значение ‘%’, ‘{’ или ‘$’ и определяет способ объединения строки форматирования с данными: с использованием %-форматирования, str.format() или string.Template. Это относится только к строке форматирования fmt (например, '%(message)s' или {message}), но не к фактическим сообщениям журнала, передаваемым в Logger.debug и т. д.; дополнительные сведения об использовании форматирования в стилях { и $ для сообщений журнала см. в разделе Использование определённых стилей форматирования во всём приложении.

Параметр defaults может быть словарём значений по умолчанию для пользовательских полей. Например: logging.Formatter('%(ip)s %(message)s', defaults={"ip": None})

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

Изменено в версии 3.8: Добавлен параметр validate. Неправильное или несоответствующее значение style и fmt вызывает исключение ValueError. Например: logging.Formatter('%(asctime)s - %(message)s', style='{').

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

format(record)

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

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

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

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

class logging.BufferingFormatter(linefmt=None)

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

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

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

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

Объекты фильтров

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 с такой же семантикой.

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

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

Объекты 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 (str) – Имя регистратора, использованного для журналирования события, представленного этой записью LogRecord. Обратите внимание: имя регистратора в LogRecord всегда будет иметь это значение, даже если событие выводится обработчиком, прикреплённым к другому (родительскому) регистратору.
level (int) – Числовой уровень события журналирования (например, 10 для DEBUG, 20 для INFO и т. д.). Обратите внимание: это значение преобразуется в два атрибута LogRecord: levelno для числового значения и levelname для соответствующего имени уровня.
pathname (str) – Полный путь к исходному файлу, из которого был выполнен вызов журналирования.
lineno (int) – Номер строки в исходном файле, из которой был выполнен вызов журналирования.
msg (Any) – Описание события: строка форматирования в стиле % с заполнителями для переменных данных либо произвольный объект (см. раздел Использование произвольных объектов в качестве сообщений).
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().

Имя атрибута	Формат	Описание
args	Обычно вам не требуется форматировать это самостоятельно.	Кортеж аргументов, объединённых с `msg` для получения `message`, или словарь, значения которого используются для объединения (если передан только один аргумент и это словарь).
asctime	`%(asctime)s`	Удобочитаемое время создания `LogRecord`. По умолчанию оно имеет вид «2003-07-08 16:49:45,896» (числа после запятой обозначают миллисекундную часть времени).
created	`%(created)f`	Время создания `LogRecord` (возвращаемое `time.time()`).
exc_info	Обычно вам не требуется форматировать это самостоятельно.	Кортеж исключения (как в `sys.exc_info`) или `None`, если исключение не возникало.
filename	`%(filename)s`	Имя файла — часть `pathname`.
funcName	`%(funcName)s`	Имя функции, содержащей вызов логирования.
levelname	`%(levelname)s`	Текстовое обозначение уровня логирования сообщения (`'DEBUG'`, `'INFO'`, `'WARNING'`, `'ERROR'`, `'CRITICAL'`).
levelno	`%(levelno)s`	Числовое обозначение уровня логирования сообщения (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`).
lineno	`%(lineno)d`	Номер строки исходного кода, в которой был выполнен вызов логирования (если доступен).
message	`%(message)s`	Записанное в журнал сообщение, вычисляемое как `msg % args`. Устанавливается при вызове `Formatter.format()`.
module	`%(module)s`	Модуль (часть `filename`, содержащая имя).
msecs	`%(msecs)d`	Миллисекундная часть времени создания `LogRecord`.
msg	Обычно вам не требуется форматировать это самостоятельно.	Строка форматирования, переданная в исходный вызов логирования. Объединяется с `args` для получения `message` либо представляет собой произвольный объект (см. раздел Использование произвольных объектов в качестве сообщений).
name	`%(name)s`	Имя регистратора, использованного для записи сообщения.
pathname	`%(pathname)s`	Полный путь к файлу исходного кода, в котором был выполнен вызов логирования (если доступен).
process	`%(process)d`	Идентификатор процесса (если доступен).
processName	`%(processName)s`	Имя процесса (если доступно).
relativeCreated	`%(relativeCreated)d`	Время в миллисекундах, прошедшее с момента загрузки модуля логирования до создания LogRecord.
stack_info	Обычно вам не требуется форматировать это самостоятельно.	Информация о кадрах стека (если доступна) от основания стека текущего потока до кадра стека, в котором был выполнен вызов логирования, приведший к созданию этой записи, включительно.
thread	`%(thread)d`	Идентификатор потока (если доступен).
threadName	`%(threadName)s`	Имя потока (если доступно).

Изменено в версии 3.1: Добавлен атрибут processName.

Объекты LoggerAdapter

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

class logging.LoggerAdapter(logger, extra)

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

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

manager: Делегирует вызов базовому manager` объекта logger.

_log: Делегирует вызов базовому методу _log`() объекта logger.

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

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

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

Потокобезопасность

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

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

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

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

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)

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

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

Для очень коротких скриптов или быстрых демонстраций средств logging могут быть удобны 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 для корневого регистратора. Аргументы и поведение в остальном совпадают с debug(). В сообщение журнала добавляются сведения об исключении. Эту функцию следует вызывать только из обработчика исключений.

logging.log(level, msg, *args, **kwargs): Записывает сообщение с уровнем level для корневого регистратора. Аргументы и поведение в остальном совпадают с debug().

logging.disable(level=CRITICAL)

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

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

Изменено в версии 3.7: Для параметра level по умолчанию задан уровень CRITICAL. Дополнительные сведения об этом изменении см. в bpo-28524.

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

Примечание

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

logging.getLevelNamesMapping(): Возвращает соответствие имён уровней их соответствующим уровням ведения журнала. Например, строке «CRITICAL» соответствует CRITICAL. При каждом вызове этой функции возвращаемое соответствие копируется из внутреннего соответствия.

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

logging.getLevelName(level)

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

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

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

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

Примечание

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

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

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

logging.basicConfig(**kwargs)

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

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

Примечание

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

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

Формат	Описание
filename	Указывает, что вместо `StreamHandler` следует создать `FileHandler`, используя указанное имя файла.
filemode	Если указан filename, открывает файл в этом режиме. По умолчанию — `'a'`.
format	Использует для обработчика указанную строку формата. По умолчанию используются атрибуты `levelname`, `name` и `message`, разделённые двоеточиями.
datefmt	Использует указанный формат даты и времени, принимаемый функцией `time.strftime()`.
style	Если указан format, использует этот стиль для строки формата. Для стиля printf, `str.format()` или `string.Template` используется один из вариантов `'%'`, `'{'` или `'$'` соответственно. По умолчанию — `'%'`.
level	Задаёт для корневого регистратора указанный уровень.
stream	Использует указанный поток для инициализации `StreamHandler`. Обратите внимание, что этот аргумент несовместим с filename: если указаны оба, возникает исключение `ValueError`.
handlers	Если аргумент указан, это должен быть итерируемый объект с уже созданными обработчиками, которые нужно добавить к корневому регистратору. Всем обработчикам, для которых ещё не задан форматтер, будет назначен форматтер по умолчанию, созданный этой функцией. Обратите внимание, что этот аргумент несовместим с filename или stream: если указаны оба, возникает исключение `ValueError`.
force	Если этому именованному аргументу присвоено значение true, все существующие обработчики корневого регистратора удаляются и закрываются до выполнения настройки, заданной другими аргументами.
encoding	Если этот именованный аргумент указан вместе с filename, его значение используется при создании `FileHandler`, а значит, и при открытии выходного файла.
errors	Если этот именованный аргумент указан вместе с filename, его значение используется при создании `FileHandler`, а значит, и при открытии выходного файла. Если аргумент не указан, используется значение ‘backslashreplace’. Обратите внимание: если указано `None`, оно будет передано в `open()` без изменений, то есть будет обрабатываться так же, как при передаче ‘errors’.

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

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

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

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

logging.shutdown()

Уведомляет систему ведения журнала о необходимости корректно завершить работу: сбросить буферы и закрыть все обработчики. Эту функцию следует вызывать при завершении приложения; после её вызова систему ведения журнала больше не следует использовать.

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

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

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:: Дополнительные именованные аргументы.

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

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

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

logging.raiseExceptions

Используется для определения того, следует ли передавать исключения, возникшие при обработке.

По умолчанию: True.

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

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

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

logging.captureWarnings(capture)

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

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

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

См. также

Module logging.config: API настройки модуля ведения журнала.
Module logging.handlers: Полезные обработчики, входящие в модуль ведения журнала.
PEP 282 - Система ведения журнала: Предложение, описывающее эту возможность для включения в стандартную библиотеку Python.
Исходный пакет ведения журнала Python: Это первоначальный источник пакета logging. Версия пакета, доступная на этом сайте, подходит для Python 1.5.2, 2.1.x и 2.2.x, в стандартную библиотеку которых не входит пакет logging.