logging — Средства протоколирования для Python¶

Объекты регистратора¶

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

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

class logging.Logger¶

propagate¶

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

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

Разъясним это на примере: Если атрибут propagate регистратора с именем A.B.C имеет значение true, то любое событие, зарегистрированное в A.B.C через вызов метода, например logging.getLogger('A.B.C').error(...), будет [при условии передачи уровня и настроек фильтра этого регистратора] передано по очереди любым обработчикам, присоединенным к регистраторам с именами A.B, A и корневому регистратору, после того, как оно сначала было передано любым обработчикам, присоединенным к A.B.C. Если у любого регистратора в цепочке A.B.C, A.B, A атрибут propagate установлен в false, то это последний регистратор, обработчикам которого предлагается обработать событие, и распространение прекращается в этой точке.

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

Примечание

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

setLevel(level)¶

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

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

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

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

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

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

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

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

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

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

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

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

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

info(msg, *args, **kwargs)¶

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

warning(msg, *args, **kwargs)¶

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

Примечание

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

error(msg, *args, **kwargs)¶

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

critical(msg, *args, **kwargs)¶

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

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

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

exception(msg, *args, **kwargs)¶

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

addFilter(filter)¶

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

removeFilter(filter)¶

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

filter(record)¶

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

addHandler(hdlr)¶

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

removeHandler(hdlr)¶

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

findCaller(stack_info=False, stacklevel=1)¶

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

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

handle(record)¶

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

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

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

hasHandlers()¶

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

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

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

Уровни регистрации¶

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

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

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

class logging.Handler¶

__init__(level=NOTSET)¶

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

createLock()¶

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

acquire()¶

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

release()¶

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

setLevel(level)¶

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

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

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

setFormatter(fmt)¶

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

addFilter(filter)¶

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

removeFilter(filter)¶

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

filter(record)¶

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

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='%', validate=True, *, defaults=None)¶

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

Параметр style может быть одним из „%“, „{“ или „$“ и определяет, как форматная строка будет объединена с данными: с помощью одного из %-форматирования, str.format() или string.Template. Это относится только к строке формата fmt (например, '%(message)s' или {message}), а не к фактическим сообщениям журнала, передаваемым в Logger.debug и т.д.; более подробную информацию об использовании {- и $-форматирования для сообщений журнала см. в Использование определенных стилей форматирования во всем приложении.

Параметр defaults может быть словарем со значениями по умолчанию для использования в пользовательских полях. Например: logging.Formatter('%(ip)s %(message)s', defaults={"ip": None})

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

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

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

format(record)¶

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

Если информация о стеке доступна, она добавляется после информации об исключении, используя formatStack() для ее преобразования, если это необходимо.

formatTime(record, datefmt=None)¶

Этот метод должен вызываться из format() форматером, который хочет использовать отформатированное время. Этот метод может быть переопределен в форматерах для обеспечения любых специфических требований, но основное поведение следующее: если указан datefmt (строка), он используется с time.strftime() для форматирования времени создания записи. В противном случае используется формат „%Y-%m-%d %H:%M:%S,uuu“, где часть uuu - это миллисекунда, а остальные буквы - в соответствии с документацией time.strftime(). Пример времени в этом формате - 2003-01-23 00:29:50,411. Возвращается результирующая строка.

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

Изменено в версии 3.3: Ранее формат по умолчанию был жестко закодирован, как в этом примере: 2010-09-06 22:38:15,292, где часть до запятой обрабатывается строкой формата strptime ('%Y-%m-%d %H:%M:%S'), а часть после запятой является значением миллисекунды. Поскольку strptime не имеет форматного заполнителя для миллисекунд, значение миллисекунды добавляется с помощью другой форматной строки, '%s,%03d' — и обе эти форматные строки были жестко закодированы в этом методе. С изменением эти строки определяются как атрибуты уровня класса, которые при желании можно переопределить на уровне экземпляра. Атрибуты называются default_time_format (для строки формата strptime) и default_msec_format (для добавления значения миллисекунды).

Изменено в версии 3.9: default_msec_format может быть None.

formatException(exc_info)¶

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

formatStack(stack_info)¶

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

Фильтр объектов¶

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

class logging.Filter(name='')¶

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

filter(record)¶

Должна ли указанная запись быть занесена в журнал? Возвращает ноль в случае «нет», ненулевое значение в случае «да». Если будет сочтено целесообразным, запись может быть изменена на месте с помощью этого метода.

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

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

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

Объекты записи журнала¶

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

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

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

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

Parameters

• name (str) – Имя регистратора, используемого для регистрации события, представленного этим LogRecord. Обратите внимание, что имя регистратора в LogRecord всегда будет иметь это значение, даже если оно может быть выдано обработчиком, присоединенным к другому (предковому) регистратору.

• level (int) – numeric level события регистрации (например, 10 для DEBUG, 20 для INFO и т.д.). Обратите внимание, что это преобразуется в два атрибута LogRecord: levelno для числового значения и levelname для соответствующего имени уровня.

• pathname (str) – Полный строковый путь к исходному файлу, в котором был сделан вызов протоколирования.

• lineno (int) – Номер строки в исходном файле, где был сделан вызов протоколирования.

• msg (str) – Сообщение описания события, которое может представлять собой строку %-формата с заполнителями для переменных данных.

• args (tuple | dict[str, typing.Any]) – Переменные данные для объединения с аргументом msg для получения описания события.

• exc_info (tuple[type[BaseException], BaseException, types.TracebackType] | None) – Кортеж исключений с текущей информацией об исключении, возвращенной командой sys.exc_info(), или None, если информация об исключении недоступна.

• func (str | None) – Имя функции или метода, из которого был вызван вызов протоколирования.

• sinfo (str | None) – Текстовая строка, представляющая информацию о стеке от основания стека в текущем потоке до вызова регистрации.

getMessage()¶

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

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

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

old_factory = logging.getLogRecordFactory()

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

logging.setLogRecordFactory(record_factory)

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

Атрибуты LogRecord¶

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

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

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

Объекты LoggerAdapter¶

Экземпляры LoggerAdapter используются для удобной передачи контекстной информации в вызовы логирования. Пример использования см. в разделе adding contextual information to your logging output.

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

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

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

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

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

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

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

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

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

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

logging.info(msg, *args, **kwargs)¶

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

logging.warning(msg, *args, **kwargs)¶

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

Примечание

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

logging.error(msg, *args, **kwargs)¶

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

logging.critical(msg, *args, **kwargs)¶

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

logging.exception(msg, *args, **kwargs)¶

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

logging.log(level, msg, *args, **kwargs)¶

Записывает сообщение с уровнем level в корневой логгер. Остальные аргументы интерпретируются как для debug().

logging.disable(level=CRITICAL)¶

Предоставляет переопределяющий уровень level для всех регистраторов, который имеет приоритет над собственным уровнем регистратора. Когда возникает необходимость временно снизить выход журнала во всем приложении, эта функция может оказаться полезной. Ее действие заключается в отключении всех вызовов логирования со степенью серьезности уровень и ниже, так что если вы вызовете ее со значением 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 также принимает строковое представление уровня, например, „INFO“. В таких случаях эта функция возвращает соответствующее числовое значение уровня.

Если не передано ни одного подходящего числового или строкового значения, возвращается строка „Level %s“ % level.

Примечание

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

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

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

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

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

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

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

Изменено в версии 3.9: Добавлены аргументы encoding и errors.

logging.shutdown()¶

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

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

logging.setLoggerClass(klass)¶

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

logging.setLogRecordFactory(factory)¶

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

Parameters

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

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

Завод имеет следующую подпись:

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

имя

Имя регистратора.

уровень

Уровень регистрации (числовой).

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.

Интеграция с модулем предупреждений¶

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

logging.captureWarnings(capture)¶

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

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

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