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

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

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

Разъясним на примере: если атрибут propagate логгера с именем A.B.C равен true, любое событие, записанное в 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.

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

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()

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

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

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

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

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

Stack (most recent call last):

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

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

Четвёртый ключевой аргумент — 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» установленным в ложь, будет найден – это будет последний логгер, который проверяется на наличие обработчиков.

New in version 3.2.

Изменено в версии 3.7: Логгеры теперь могут быть сериализованы и десериализованы.

Уровни логгирования

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

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

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

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

Этот метод вызывается после получения блокировки на уровне обработчика, которая освобождается после возврата этого метода. Когда вы переопределяете этот метод, обратите внимание, что следует быть осторожным при вызове чего-либо, что вызывает другие части 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. Неправильный или несовпадающий стиль и fmt приведут к ValueError. Например: logging.Formatter('%(asctime)s - %(message)s', style='{').

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

format(record)

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

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

formatTime(record, datefmt=None)

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

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

Изменено в версии 3.3: Ранее формат по умолчанию был жёстко задан, как в этом примере: 2010-09-06 22:38:15,292 , где часть перед запятой обрабатывается строкой форматирования strptime ('%Y-%m-%d %H:%M:%S'), а часть после запятой — значение миллисекунд. Поскольку 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 с теми же семантическими значениями.

Хотя фильтры в основном используются для фильтрации записей на основе более сложных критериев, чем уровни, они видят каждую запись, которая обрабатывается обработчиком или логгером, к которому они прикреплены: это может быть полезно, если вы хотите подсчитать, сколько записей было обработано определённым логгером или обработчиком, или добавить, изменить или удалить атрибуты в 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 (typing.Any) – Сообщение об описании события, которое может быть строкой с разделителями % для плацехолдеров переменных данных, или произвольным объектом (см. Использование произвольных объектов в качестве сообщений).
• args (tuple | dict[str, typing.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:03d} отформатирует значение миллисекунд 4 как 004. Обратитесь к документации str.format() для получения подробной информации об имеющихся у вас вариантах.

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

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

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

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

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

В kwargs проверяются три ключевых аргумента: 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)s %(clientip)-15s %(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.

Эта функция (а также info(), warning(), error() и critical()) будет вызывать basicConfig(), если у корневого логгера нет подключённых обработчиков.

Изменено в версии 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().

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.getLevelName(level)

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

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

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

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

Примечание

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

Изменено в версии 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	Указывает, что должен быть создан FileHandler с указанным именем файла, а не StreamHandler.
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__() таким образом, чтобы требовался только аргумент name, и __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.

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

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

logging.captureWarnings(capture)

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

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

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