15.7. logging – Средство журналирования для Python¶logging – Logging facility for Python

15.7.1. Объекты Logger¶Logger Objects

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

Logger.propagate¶

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

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

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

Примечание

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

Logger.setLevel(level)¶

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

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

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

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

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

Logger.isEnabledFor(lvl)¶

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

Logger.getEffectiveLevel()¶

Указывает действующий уровень для этого регистратора. Если с помощью setLevel() было установлено значение, отличное от NOTSET, возвращается оно. В противном случае иерархия просматривается в сторону корня, пока не будет найдено значение, отличное от 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-адрес удаленного клиента и имя аутентифицированного пользователя в приведенном выше примере). В таких обстоятельствах, скорее всего, специализированные Formatters будут использоваться с определенными Handlers.

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

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

Logger.addHandler(hdlr)¶

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

Logger.removeHandler(hdlr)¶

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

Logger.findCaller()¶

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

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

Logger.handle(record)¶

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

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

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

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

15.7.2. Уровни журналирования¶Logging Levels

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

15.7.3. Объекты Handler¶Handler Objects

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

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

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.

15.7.4. Объекты Formatter¶Formatter Objects

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

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

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

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

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

format(record)¶

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

formatTime(record, datefmt=None)¶

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

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

formatException(exc_info)¶

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

15.7.5. Объекты Filter¶Filter Objects

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

15.7.6. Объекты LogRecord¶LogRecord Objects

Экземпляры 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__ может возвращать фактическую строку форматирования.

15.7.7. Атрибуты LogRecord¶LogRecord attributes

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

15.7.8. Объекты LoggerAdapter¶LoggerAdapter Objects

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

15.7.9. Безопасность потоков¶Thread Safety

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

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

15.7.10. Функции уровня модуля¶Module-Level Functions

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

logging.getLogger([name])¶

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

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

logging.getLoggerClass()¶

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

class MyLogger(logging.getLoggerClass()):
    # ... переопределить поведение здесь

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

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

В kwargs проверяются два именованных аргумента: exc_info – если он не равен false, информация об исключении добавляется в сообщение лога. Если передается кортеж исключения (в формате, возвращаемом 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-адрес удаленного клиента и имя аутентифицированного пользователя в приведенном выше примере). В таких обстоятельствах, скорее всего, специализированные Formatters будут использоваться с определенными Handlers.

Изменено в версии 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. Эта функция полезна для получения сериализованного словаря атрибутов 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().
уровень	Устанавливает уровень корневого регистратора в указанный уровень.
поток данных	Используйте указанный поток данных для инициализации StreamHandler. Обратите внимание, что этот аргумент несовместим с filename – если указаны оба, stream игнорируется.

logging.shutdown()¶

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

logging.setLoggerClass(klass)¶

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

15.7.11. Интеграция с модулем warnings¶Integration with the warnings module

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

logging.captureWarnings(capture)¶

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

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

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