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

name

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

Примечание

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

level

Пороговое значение этого логгера, установленное методом setLevel().

Примечание

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

parent

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

Примечание

Это значение должно рассматриваться как только для чтения.

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.

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

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

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

getChild(suffix)

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

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

getChildren()

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

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

debug(msg, *args, **kwargs)

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

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

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

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

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

Stack (most recent call last):

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

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

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

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

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

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

class logging.Handler

__init__(level=NOTSET)

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

createLock()

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

acquire()

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

release()

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

setLevel(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.

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

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

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

Параметры:

• fmt (str) – Строка формата для всего выводимого лог-сообщения в указанном стиле. Возможные ключи сопоставления взяты из атрибутов объекта LogRecord. Если не указано, используется '%(message)s', что соответствует простому сообщению.
• datefmt (str) – Строка формата для части даты/времени лог-сообщения в указанном стиле. Если не указано, используется значение по умолчанию, описанное в formatTime().
• style (str) – Может быть одним из '%', '{' или '$' и определяет, как строка формата будет объединена со своими данными: с использованием одного из форматов строк в стиле printf (%), str.format() ({) или string.Template ($). Это относится только к fmt и datefmt (например, '%(message)s' против '{message}'), а не к самим лог-сообщениям, переданным методам регистрации событий. Тем не менее, существуют другие способы использования {- и $-форматирования для лог-сообщений.
• validate (bool) – Если True (значение по умолчанию), некорректный или несовпадающий fmt и style вызовет ValueError; например, logging.Formatter('%(asctime)s - %(message)s', style='{').
• defaults (dict[str, Any]) – Словарь с значениями по умолчанию для использования в пользовательских полях. Например, logging.Formatter('%(ip)s %(message)s', defaults={"ip": None})

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

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

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

format(record)

Словарь атрибутов записи используется в качестве операнда операции форматирования строк. Возвращает результирующую строку. Перед форматированием словаря выполняется несколько подготовительных шагов. Атрибут 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 не имеет формата placeholder для миллисекунд, значение миллисекунд добавляется с помощью другой строки формата, '%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)

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

formatFooter(records)

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

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

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

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

Вам фактически не нужно подклассифицировать 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() для получения полной информации о доступных вариантах.

Объекты LoggerAdapter

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

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

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

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: Методы isEnabledFor(), getEffectiveLevel(), setLevel() и hasHandlers() были добавлены в LoggerAdapter. Эти методы делегируют обращение к базовому логгеру.

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

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

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

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

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

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

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

logging.getLogger(name=None)

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

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

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() в корневом логгере. Обработка аргументов во всех отношениях идентична описанной в этом методе.

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

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

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

Примечание

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

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

logging.getHandlerByName(name)

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

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

logging.getHandlerNames()

Возвращает неизменяемое множество всех известных имён обработчиков.

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

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