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

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

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

Stack (most recent call last):

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

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

Имя этого параметра отражает аналогичный параметр в модуле warnings.

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

FORMAT = '%(asctime)s %(clientip)-15s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logger = logging.getLogger('tcpserver')
logger.warning('Protocol problem: %s', 'connection reset', extra=d)

будет выводить что-то вроде

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

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

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

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

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

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

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

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

info(msg, *args, **kwargs)

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

warning(msg, *args, **kwargs)

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

Примечание

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

error(msg, *args, **kwargs)

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

critical(msg, *args, **kwargs)

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

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

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

exception(msg, *args, **kwargs)

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

addFilter(filter)

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

removeFilter(filter)

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

filter(record)

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

addHandler(hdlr)

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

removeHandler(hdlr)

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

findCaller(stack_info=False, stacklevel=1)

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

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

handle(record)

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

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

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

hasHandlers()

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

Введено в версии 3.2.

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

Уровни ведения логов

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

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

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

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 используются для удобного передачи контекстной информации в вызовы logging. Пример использования см. в разделе добавление контекстной информации в ваш лог-вывод.

class logging.LoggerAdapter(logger, extra)

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

process(msg, kwargs)

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

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

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

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

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

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

logging.getLogger(name=None)

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

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

logging.getLoggerClass()

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

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

logging.getLogRecordFactory()

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

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

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

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

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

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

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

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

Stack (most recent call last):

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

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

FORMAT = '%(asctime)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.getLevelNamesMapping()

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

Введено в версии 3.11.

logging.getLevelName(level)

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

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

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

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

Примечание

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

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

logging.makeLogRecord(attrdict)

Создаёт и возвращает новый экземпляр LogRecord, атрибуты которого определяются attrdict. Эта функция полезна для взятия закодированного в формате pickle словаря атрибутов 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)).