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

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

Примечание

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

setLevel(level)

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

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

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

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

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

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

Изменено в версии 3.2: Параметр level теперь может принимать строковое представление уровня, например, ‘INFO’, как альтернативу целочисленным константам, таким как INFO. Однако обратите внимание, что уровни хранятся внутри как целые числа, и методы, такие как, например, getEffectiveLevel() и isEnabledFor(), будут возвращать/ожидать целые числа.

isEnabledFor(level)

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

getEffectiveLevel()

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

getChild(suffix)

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

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

debug(msg, *args, **kwargs)

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

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

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

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

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

Stack (most recent call last):

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

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

Четвёртый ключевой аргумент — 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.

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

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 равное false). Этот метод используется для распакованных записей, полученных из сокета, а также для созданных локально. Фильтрация на уровне логгера применяется с помощью filter().

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

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

hasHandlers()

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

New in version 3.2.

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

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

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

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

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

class logging.Handler

__init__(level=NOTSET)

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

createLock()

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

acquire()

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

release()

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

setLevel(level)

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

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

Изменено в версии 3.2: Параметр level теперь принимает строковое представление уровня, например, ‘INFO’, как альтернативу целочисленным константам, таким как INFO.

setFormatter(fmt)

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

addFilter(filter)

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

removeFilter(filter)

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

filter(record)

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

flush()

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

close()

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

handle(record)

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

handleError(record)

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

format(record)

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

emit(record)

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

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

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

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

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

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

class logging.Formatter(fmt=None, datefmt=None, style='%')

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

Параметр style может быть одним из ‘%’, ‘{’ или ‘$’ и определяет способ объединения строки форматирования с данными: с использованием форматирования в стиле %, str.format() или string.Template. См. Использование различных стилей форматирования в вашем приложении для получения дополнительной информации об использовании форматирования {- и $- для сообщений журнала.

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

Изменено в версии 3.8: Добавлен параметр validate. Некорректный или несовпадающий стиль и fmt приведут к ValueError. Например: logging.Formatter('%(asctime)s - %(message)s', style='{').

format(record)

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

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

formatException(exc_info)

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

formatStack(stack_info)

Форматирует указанную информацию о стеке (строку, возвращаемую traceback.print_stack(), но без последней новой строки) в виде строки. Эта реализация по умолчанию просто возвращает входное значение.

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

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

filter(record)

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

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

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

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

Объекты записей событий

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

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

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

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

Параметры

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

getMessage()

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

Изменено в версии 3.2: Создание LogRecord было сделано более настраиваемым путем предоставления фабрики, которая используется для создания записи. Фабрика может быть установлена с помощью getLogRecordFactory() и setLogRecordFactory() (см. для этого сигнатуру фабрики).

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

old_factory = logging.getLogRecordFactory()

def record_factory(*args, **kwargs):
    record = old_factory(*args, **kwargs)
    record.custom_attribute = 0xdecafbad
    return record

logging.setLogRecordFactory(record_factory)

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

Атрибуты LogRecord

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

Если вы используете форматирование {} (str.format()), вы можете использовать {attrname} в качестве заполнителя в строке формата. Если вы используете форматирование $- (string.Template), используйте форму ${attrname}. В обоих случаях, конечно, замените attrname фактическим именем атрибута, который вы хотите использовать.

В случае форматирования {}, вы можете указать флаги форматирования, поместив их после имени атрибута, отделив их от него двоеточием. Например: заполнитель {msecs:03d} отформатирует значение миллисекунд 4 как 004. Обратитесь к документации str.format() для получения подробной информации о доступных вам опциях.

Объекты LoggerAdapter

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

class logging.LoggerAdapter(logger, extra)

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

process(msg, kwargs)

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

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

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

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

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

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

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

logging.getLogger(name=None)

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

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

logging.getLoggerClass()

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

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

logging.getLogRecordFactory()

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

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

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

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

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

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

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

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

Stack (most recent call last):

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

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

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

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

Примечание

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

logging.disable(level=CRITICAL)

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

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

Изменено в версии 3.7: Параметр level был изменён на уровень по умолчанию CRITICAL. См. bpo-28524 для получения дополнительной информации об этом изменении.

logging.addLevelName(level, levelName)

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

Примечание

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

logging.getLevelName(level)

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

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

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

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

Примечание

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

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

logging.makeLogRecord(attrdict)

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

logging.basicConfig(**kwargs)

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

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

Примечание

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

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

Формат	Описание
filename	Указывает, что должен быть создан FileHandler, используя указанное имя файла, а не StreamHandler.
filemode	Если указано filename, откройте файл в этом режиме. По умолчанию 'a'.
format	Используйте указанную строку формата для обработчика. По умолчанию атрибуты levelname, name и message разделены двоеточиями.
datefmt	Используйте указанный формат даты/времени, как принимается time.strftime().
style	Если указан format, используйте этот стиль для строки формата. Один из '%', '{' или '$' для форматирования в стиле printf, str.format() или string.Template соответственно. По умолчанию '%'.
level	Установите уровень корневого регистратора до указанного уровня.
stream	Используйте указанный поток для инициализации StreamHandler. Обратите внимание, что этот аргумент несовместим с filename - если оба присутствуют, будет поднято ValueError.
handlers	Если указано, это должен быть итерируемый объект уже созданных обработчиков для добавления в корневой регистратор. Любые обработчики, у которых ещё нет установленного форматера, получат стандартный форматер, созданный в этой функции. Обратите внимание, что этот аргумент несовместим с filename или stream - если оба присутствуют, будет поднято ValueError.
force	Если этот ключевой аргумент задан как true, любые существующие обработчики, прикреплённые к корневому регистратору, удаляются и закрываются перед выполнением конфигурации, как задано другими аргументами.

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

Изменено в версии 3.3: Добавлен аргумент handlers. Добавлены дополнительные проверки для обнаружения ситуаций, когда указаны несовместимые аргументы (например, handlers вместе с stream или filename, или stream вместе с filename).

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

logging.shutdown()

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

При импорте модуля logging, эта функция регистрируется как обработчик завершения (см. atexit), поэтому обычно нет необходимости делать это вручную.

logging.setLoggerClass(klass)

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

logging.setLogRecordFactory(factory)

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

Параметры

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

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

Фабрика имеет следующий синтаксис:

factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, **kwargs)

name

Имя логгера.

level

Уровень ведения журнала (числовое значение).

fn

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

lno

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

msg

Сообщение ведения журнала.

args

Аргументы для сообщения ведения журнала.

exc_info

Кортеж исключения или None.

func

Имя функции или метода, которые вызвали вызов ведения журнала.

sinfo

Обратный отсчёт стека, например, предоставляемый traceback.print_stack(), показывающий иерархию вызовов.

kwargs

Дополнительные ключевые аргументы.

Атрибуты уровня модуля

logging.lastResort

«Обработчик последней инстанции» доступен через этот атрибут. Это StreamHandler, записывающий в sys.stderr с уровнем WARNING, и используется для обработки событий ведения журнала в отсутствие какой-либо конфигурации ведения журнала. Конечный результат – просто вывести сообщение в sys.stderr. Это заменяет более раннее сообщение об ошибке, гласившее, что «не удалось найти обработчики для логгера XYZ». Если по какой-то причине вам требуется более раннее поведение, lastResort может быть установлено в None.

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

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

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

logging.captureWarnings(capture)

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

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

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