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

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

Important

Эта страница содержит справочную информацию по API. Для учебной информации и обсуждения более сложных тем, см.

• Основной учебник
• Продвинутый учебник
• Поваренная книга логирования

---

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

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

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

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

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

Объекты Logger

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

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

class logging.Logger

propagate

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

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

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

Примечание

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

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

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

debug(msg, *args, **kwargs)

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

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

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

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

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

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

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

hasHandlers()

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

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

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

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

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

Уровень	Числовое значение
CRITICAL	50
ERROR	40
WARNING	30
INFO	20
DEBUG	10
NOTSET	0

Объекты Handler

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

class logging.Handler

__init__(level=NOTSET)

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

createLock()

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

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

flush()

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

close()

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

handle(record)

Условно испускает указанную запись логирование, в зависимости от фильтров, которые могли быть добавлены в обработчик. Завершение фактической эмиссии записи с получением/выпуском блокировки I/O поток.

handleError(record)

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

format(record)

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

emit(record)

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

Список обработчики, включенных в качестве стандартных, см. в разделе logging.handlers.

Объекты Formatter

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

Средство форматирования может быть инициализировано с форматом строка, который использует знание LogRecord атрибуты - такого как дефолт значение, упомянутый выше использования того, что сообщение и аргументы пользователя предварительно отформатированы в LogRecord message атрибут. Этот формат строка содержит стандартные ключи отображения %-стиля 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 (a строка), то форматировать время создания записи используемый с 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. Если параметр name указан, он называет логгер, который вместе со своими дочерними элементами будет иметь события, разрешенные фильтром. Если name является пустым строка, разрешает каждое событие.

filter(record)

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

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

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

Изменено в версии 3.2: Не нужно создавать специализированные классы Filter или использовать другие классы с методом filter: в качестве фильтра можно использовать функцию (или другую вызываемую). Логика фильтрации проверит, есть ли у объекта фильтра filter атрибут: если это так, то предполагается, что он является Filter, и вызывается его метод filter(). В противном случае предполагается, что он является вызываемым и вызывается с записью в качестве единственного параметра. Эти возвращенный значение должны соответствовать этому возвращенный к filter().

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

Объекты LogRecord

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

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

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

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

Параметры:

• name – Имя логгер используемый для регистрации события, представленного этой LogRecord. Обратите внимание, что у этого имени всегда будет этот значение, даже при том, что это может быть испущено обработчиком, приложенным к другому (предоку) логгера.
• level – Числовой уровень события логирование (DEBUG, INFO и т.д.) Обратите внимание, что он преобразуется в two атрибуты 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 атрибуты.) эти атрибуты могут быть используемый, чтобы слить данные из отчета в формат строка. В следующей таблице перечислены (в алфавитном порядке) имена атрибут, их значения и соответствующие местозаполнители в формате% -style строка.

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

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

Имя атрибута	Формат	Описание
args	Вам не нужно форматировать его самостоятельно.	Кортеж аргументов слился в msg, чтобы произвести message или словарь, значения которого используются для слияния (когда есть только один аргумент, и это словарь).
asctime	%(asctime)s	Читаемое человеком время создания LogRecord. По умолчанию это имеет вид „2003-07-08 16:49: 45,896“ (числа после запятой являются миллисекундной частью времени).
created	%(created)f	Время, когда LogRecord был создан (как возвращенный time.time()).
exc_info	Вам не нужно форматировать его самостоятельно.	Кортеж исключения (в духе``sys.exc_info``) или, если не произошло исключения, None.
filename	%(filename)s	Filename части pathname.
funcName	%(funcName)s	Имя функции, содержащей вызов логирования.
levelname	%(levelname)s	Текстовый уровень логирования для сообщения ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL').
levelno	%(levelno)s	Числовой уровень логирование для сообщения (DEBUG, INFO, WARNING, ERROR, CRITICAL).
lineno	%(lineno)d	Номер строки исходника, из которой был зделан вызов логирования (если доступен).
message	%(message)s	Зарегистрированное сообщение, вычисленное как msg %  args. Этот параметр устанавливается при вызове функции «Formatter.format()».
module	%(module)s	Модуль (часть имени filename).
msecs	%(msecs)d	Миллисекундная часть времени создания LogRecord.
msg	Вам не нужно форматировать его самостоятельно.	Форматная строка переданная в исходном вызове логирования. Слитый с args, чтобы произвести message или произвольный объект (см. Использование произвольных объектов в качестве сообщений).
name	%(name)s	Имя логгера используемого для регистрации вызова.
pathname	%(pathname)s	Полное имя пути к исходному файлу, в котором был выполнен вызов логирования (если доступно).
process	%(process)d	ID процесса (если доступен).
processName	%(processName)s	Имя процесса (если доступен).
relativeCreated	%(relativeCreated)d	Время в миллисекундах при создании LogRecord относительно времени загрузки модуля logging.
stack_info	Вам не нужно форматировать это самостоятельно.	Информация о стековом кадре (если таковая имеется) из нижней части стека в текущем потоке, вплоть до стекового фрейма вызова регистрации, который привел к созданию этой записи.
thread	%(thread)d	ID потока (если доступен).
threadName	%(threadName)s	Имя потока (если доступно).

Изменено в версии 3.1: processName был добавлен.

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

Изменено в версии 3.2: Методы isEnabledFor(), getEffectiveLevel(), setLevel() и hasHandlers() были добавлены к LoggerAdapter. Эти методы делегируются базовому логгеру.

Потоковая безопасность

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

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

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

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

logging.getLogger(name=None)

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

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

logging.getLoggerClass()

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

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

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. Если уровень - один из предопределенных уровней CRITICAL, ERROR, WARNING, INFO или DEBUG тогда, вы получаете соответствующий строка. Если уровни связаны с именами с помощью addLevelName(), то имя, связанное с level, равно возвращенный. Если числовой значение, соответствующий одному из определенных уровней, передан в, соответствующее представление строка - возвращенный. Иначе строка „Уровень %s“ уровень % является возвращенный.

Примечание

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

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

Формат	Описание
filename	Указывает, что FileHandler должен создаваться с использованием указанного имени файла, а не StreamHandler.
filemode	Если filename определен, открыть файл n этим режимом. По умолчанию используется значение 'a'.
format	Использовать указанную форматную строка для обработчика.
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()

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

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

logging.setLoggerClass(klass)

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

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:Полный путь к файлу, в который был сделан вызов logging. lno:Номер строки в файле, где был сделан вызов logging. msg:Сообщение журнала. args:Аргументы для сообщения журналирования. exc_info:Кортеж исключений или None. func:Имя функции или метода, которая вызвала logging. 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)).

См.также

Модуль logging.config

Конфигурационное API для модуля logging.

Модуль logging.handlers

Полезные обработчики, входящие в состав модуля logging.

PEP 282 - система логирования

Предложение, описывающее эту функцию для включения в стандартную библиотеку Python.

Оригинальный пакет logging Python

Это исходный исходник для пакета logging. Версия пакета, доступная с этого сайта, подходит для использования с Python 1.5.2, 2.1.x и 2.2.x, которые не включают пакет logging в стандартную библиотеку.