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

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

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

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

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

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

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

1. Объекты логгеров

Логгеры имеют следующие атрибуты и методы. Обратите внимание, что логгеры никогда не создаются напрямую, а всегда через функцию уровня модуля logging.getLogger(name). Несколько вызовов getLogger() с одинаковым именем всегда возвращают ссылку на один и тот же объект Logger.

Имя логгера — это потенциально значение с разделителями «точка», например foo.bar.baz (хотя оно также может быть просто foo, например). Логгеры, находящиеся ниже в иерархическом списке, являются потомками логгеров, расположенных выше в списке. Например, при наличии логгера с именем foo, логгеры с именами foo.bar, foo.bar.baz, и foo.bam являются потомками foo. Иерархия имен логгеров аналогична иерархии пакетов Python и идентична ей, если вы организуете свои логгеры на основе каждого модуля, используя рекомендуемую конструкцию logging.getLogger(__name__). Это потому, что в модуле __name__ — это имя модуля в пространстве имен пакета Python.

class logging.Logger

Logger.propagate

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

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

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

Примечание

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

Logger.setLevel(level)

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

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

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

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

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

Logger.isEnabledFor(lvl)

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

Logger.getEffectiveLevel()

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

Logger.getChild(suffix)

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

Новая в версии 2.7.

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

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

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

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

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

выведет что-то вроде

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

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

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

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

Logger.info(msg, *args, **kwargs)

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

Logger.warning(msg, *args, **kwargs)

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

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

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

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

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

Logger.log(lvl, msg, *args, **kwargs)

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

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

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

Logger.addFilter(filter)

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

Logger.removeFilter(filter)

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

Logger.filter(record)

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

Logger.addHandler(hdlr)

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

Logger.removeHandler(hdlr)

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

Logger.findCaller()

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

Изменено в версии 2.4: Добавлено имя функции. В более ранних версиях имя файла и номер строки возвращались в кортеже из 2 элементов.

Logger.handle(record)

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

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

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

Изменено в версии 2.5: Добавлены func и extra.

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

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

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

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

Handler.__init__(level=NOTSET)

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

Handler.createLock()

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

Handler.acquire()

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

Handler.release()

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

Handler.setLevel(level)

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

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

Handler.setFormatter(fmt)

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

Handler.addFilter(filter)

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

Handler.removeFilter(filter)

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

Handler.filter(record)

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

Handler.flush()

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

Handler.close()

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

Handler.handle(record)

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

Handler.handleError(record)

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

Handler.format(record)

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

Handler.emit(record)

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

Для списка обработчиков, включённых в стандарт, см. logging.handlers.

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

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

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

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

class logging.Formatter(fmt=None, datefmt=None)

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

format(record)

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

formatTime(record, datefmt=None)

Этот метод должен вызываться из format() форматировщиком, который хочет использовать отформатированное время. Этот метод можно переопределить в форматировщиках, чтобы удовлетворить любые конкретные требования, но основное поведение следующее: если datefmt (строка) указан, он используется с time.strftime() для форматирования времени создания записи. В противном случае используется формат ISO8601. Возвращается результирующая строка.

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

formatException(exc_info)

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

5. Объекты фильтра

Filters могут использоваться Handlers и Loggers для более сложной фильтрации, чем та, которая предоставляется уровнями. Базовый класс фильтра позволяет только событиям, которые находятся ниже определенной точки в иерархии логгеров. Например, фильтр, инициализированный «A.B», позволит событиям, зарегистрированным логгерами «A.B», «A.B.C», «A.B.C.D», «A.B.D» и т. д., но не «A.BB», «B.A.B» и т. д. Если инициализирован пустой строкой, все события пропускаются.

class logging.Filter(name='')

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

filter(record)

Должно ли указанная запись быть зарегистрирована? Возвращает ноль для нет, ненулевое значение для да. При необходимости метод может изменять запись на месте.

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

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

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

6. Объекты LogRecord

LogRecord экземпляры создаются автоматически логгером Logger каждый раз, когда что-то регистрируется, и могут быть созданы вручную с помощью makeLogRecord() (например, из сериализованного события, полученного по сети).

class logging.LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None)

Содержит всю информацию, относящуюся к регистрируемому событию.

Основная информация передается в msg и args, которые объединяются с помощью msg % args для создания поля message записи.

Параметры

• name – Имя логгера, используемого для регистрации события, представленного этой записью LogRecord. Обратите внимание, что это имя всегда будет иметь это значение, даже если оно может быть выведено обработчиком, присоединенным к другому (предковому) логгеру.
• level – Числовой уровень события регистрации (один из DEBUG, INFO и т. д.). Обратите внимание, что это преобразуется в *два* атрибута записи LogRecord: levelno для числового значения и levelname для соответствующего имени уровня.
• pathname – Полный путь к исходному файлу, где был вызван вызов регистрации.
• lineno – Номер строки в исходном файле, где был вызван вызов регистрации.
• msg – Описание события, возможно, строка формата с заполнительными метками для данных переменных.
• args – Данные переменных для объединения с аргументом msg для получения описания события.
• exc_info – Кортеж исключения с текущей информацией об исключении или None, если информация об исключении недоступна.
• func – Имя функции или метода, из которого был вызван вызов регистрации.

Изменено в версии 2.5: Добавлен func.

getMessage()

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

7. Атрибуты LogRecord

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

8. Объекты LoggerAdapter

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

class logging.LoggerAdapter(logger, extra)

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

process(msg, kwargs)

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

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

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

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

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

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

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

logging.getLogger([name])

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

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

logging.getLoggerClass()

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

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

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

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

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

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

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

выведет что-то вроде:

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

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

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

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

Изменено в версии 2.5: Добавлен extra.

logging.info(msg[, *args[, **kwargs]])

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

logging.warning(msg[, *args[, **kwargs]])

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

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

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

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

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

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

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

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

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

Примечание

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

logging.disable(lvl)

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

logging.addLevelName(lvl, levelName)

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

Примечание

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

logging.getLevelName(lvl)

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

Примечание

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

logging.makeLogRecord(attrdict)

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

logging.basicConfig([**kwargs])

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

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

Изменено в версии 2.4: Ранее, basicConfig() не принимала ключевые аргументы.

Примечание

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

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

Формат	Описание
filename	Указывает на создание FileHandler, используя указанное имя файла, вместо StreamHandler.
filemode	Если указан filename, откройте файл в этом режиме. По умолчанию 'a'.
format	Используйте указанную строку формата для обработчика.
datefmt	Используйте указанный формат даты/времени, как принимается time.strftime().
level	Установите уровень корневого логгера на указанный уровень.
stream	Используйте указанный поток для инициализации StreamHandler. Обратите внимание, что этот аргумент несовместим с filename - если оба присутствуют, stream игнорируется.

logging.shutdown()

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

logging.setLoggerClass(klass)

Уведомляет систему ведения журналов об использовании класса klass при создании логгера. Класс должен определять __init__() таким образом, чтобы требовался только аргумент name, а __init__() должен вызывать Logger.__init__(). Эта функция обычно вызывается до создания логгеров приложениями, которые нуждаются в пользовательском поведении логгера.

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

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

logging.captureWarnings(capture)

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

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

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