logging.config – Конфигурация логирования¶logging.config – Logging configuration

Подробности схемы словаря¶Dictionary Schema Details

Словарь, передаваемый dictConfig(), должен содержать следующие ключи:

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

Все остальные ключи необязательны, но если они присутствуют, то будут интерпретироваться, как описано ниже. Во всех случаях, когда ниже упоминается «настраивающий словарь», в нём будет проверяться наличие специального ключа '()', чтобы определить, требуется ли пользовательское создание экземпляра. Если да, то используется механизм, описанный ниже в разделе Пользовательские объекты, для создания экземпляра; в противном случае контекст используется для определения того, что создавать.

• formatters – соответствующее значение будет словарём, в котором каждый ключ – это идентификатор форматтера, а каждое значение – словарь, описывающий, как настроить соответствующий экземпляр Formatter.

  В настраивающем словаре ищутся следующие необязательные ключи, которые соответствуют аргументам, передаваемым для создания объекта Formatter:

  • format

  • datefmt

  • style

  • validate (начиная с версии >=3.8)

  Необязательный ключ class указывает имя класса форматтера (в виде полного имени модуля и класса). Аргументы для создания экземпляра такие же, как для Formatter, поэтому этот ключ наиболее полезен для создания экземпляра настраиваемого подкласса Formatter. Например, альтернативный класс может отображать трассировки исключений в расширенном или сжатом формате. Если ваш форматтер требует других или дополнительных ключей конфигурации, следует использовать раздел Пользовательские объекты.

• filters – соответствующее значение будет словарём, в котором каждый ключ – это идентификатор фильтра, а каждое значение – словарь, описывающий, как настроить соответствующий экземпляр Filter.

  В настраивающем словаре ищется ключ name (по умолчанию пустая строка), и он используется для создания экземпляра logging.Filter.

• handlers – соответствующее значение будет словарём, в котором каждый ключ – это идентификатор обработчика, а каждое значение – словарь, описывающий, как настроить соответствующий экземпляр Handler.

  В словаре конфигурации ищутся следующие ключи:

  • class (обязательный). Это полное имя класса обработчика.

  • level (необязательный). Уровень обработчика.

  • formatter (необязательный). Идентификатор форматтера для этого обработчика.

  • filters (необязательный). Список идентификаторов фильтров для этого обработчика.

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

  handlers:
    console:
      class : logging.StreamHandler
      formatter: brief
      level   : INFO
      filters: [allow_foo]
      stream  : ext://sys.stdout
    file:
      class : logging.handlers.RotatingFileHandler
      formatter: precise
      filename: logconfig.log
      maxBytes: 1024
      backupCount: 3
  

  обработчик с идентификатором console создаётся как logging.StreamHandler, используя sys.stdout в качестве базового потока. Обработчик с идентификатором file создаётся как logging.handlers.RotatingFileHandler с именованными аргументами filename='logconfig.log', maxBytes=1024, backupCount=3.

• loggers – соответствующее значение будет словарём, в котором каждый ключ – это имя регистратора, а каждое значение – словарь, описывающий, как настроить соответствующий экземпляр Logger.

  В словаре конфигурации ищутся следующие ключи:

  • level (необязательно). Уровень регистратора.

  • propagate (необязательно). Настройка распространения записей регистратора.

  • filters (необязательно). Список идентификаторов фильтров для этого регистратора.

  • handlers (необязательно). Список идентификаторов обработчиков для этого регистратора.

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

• root – это конфигурация корневого регистратора. Обработка конфигурации будет такой же, как и для любого другого регистратора, за исключением того, что параметр propagate не применяется.

• incremental – следует ли интерпретировать конфигурацию как дополнение к существующей. Значение по умолчанию – False, что означает, что указанная конфигурация заменяет существующую с той же семантикой, которая используется существующим API fileConfig().

  Если указано значение True, конфигурация обрабатывается так, как описано в разделе Incremental Configuration.

• disable_existing_loggers – следует ли отключать все существующие некорневые регистраторы. Этот параметр повторяет одноимённый параметр в fileConfig(). Если отсутствует, по умолчанию принимает значение True. Это значение игнорируется, если incremental равно True.

Инкрементальная конфигурация¶Incremental Configuration

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

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

Поэтому, когда ключ incremental словаря конфигурации присутствует и равен True, система полностью игнорирует все записи formatters и filters и обрабатывает только настройки level в записях handlers, а также настройки level и propagate в записях loggers и root.

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

Соединения объектов¶Object connections

Схема описывает набор объектов логирования – регистраторы, обработчики, форматировщики, фильтры – которые соединены друг с другом в граф объектов. Таким образом, схема должна представлять соединения между объектами. Например, предположим, что после настройки к определённому регистратору прикреплён определённый обработчик. В рамках данного обсуждения можно сказать, что регистратор представляет источник, а обработчик – приёмник соединения между ними. Конечно, в настроенных объектах это реализовано тем, что регистратор хранит ссылку на обработчик. В словаре конфигурации это делается путём присвоения каждому объекту- приёмнику идентификатора, однозначно его определяющего, а затем использования этого идентификатора в конфигурации объекта-источника для указания наличия соединения между источником и объектом-приёмником с этим идентификатором.

Например, рассмотрим следующий фрагмент YAML:

formatters:
  brief:
    # здесь задаётся конфигурация форматтера с id 'brief'
  precise:
    # здесь задаётся конфигурация форматтера с id 'precise'
handlers:
  h1: #Это идентификатор
   # здесь задаётся конфигурация обработчика с id 'h1'
   formatter: brief
  h2: #Это другой идентификатор
   # здесь задаётся конфигурация обработчика с id 'h2'
   formatter: precise
loggers:
  foo.bar.baz:
    # прочая конфигурация для логгера 'foo.bar.baz'
    handlers: [h1, h2]

(Примечание: YAML используется здесь, потому что он немного более читаем, чем эквивалентная форма исходного кода Python для словаря.)

Идентификаторами для регистраторов являются имена регистраторов, которые использовались бы программно для получения ссылки на эти регистраторы, например, foo.bar.baz. Идентификаторы для форматировщиков и фильтров могут быть любыми строковыми значениями (такими как brief, precise выше) и являются временными – они имеют смысл только для обработки словаря конфигурации и используются для определения связей между объектами, и нигде не сохраняются после завершения вызова конфигурации.

Указанный выше фрагмент показывает, что к регистратору с именем foo.bar.baz должны быть прикреплены два обработчика, которые описываются идентификаторами обработчиков h1 и h2. Форматировщик для h1 – это тот, который описывается идентификатором brief, а форматировщик для h2 – тот, который описывается идентификатором precise.

Пользовательские объекты¶User-defined objects

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

Настраиваемые объекты описываются словарями, которые детализируют их конфигурацию. В некоторых местах система логирования сможет определить из контекста, как создать экземпляр объекта, но когда требуется создать экземпляр пользовательского объекта, система не будет знать, как это сделать. Для обеспечения полной гибкости при создании пользовательских объектов пользователь должен предоставить «фабрику» – вызываемый объект, который вызывается со словарём конфигурации и возвращает созданный экземпляр. Это обозначается абсолютным путём импорта к фабрике, доступным под специальным ключом '()'. Вот конкретный пример:

formatters:
  brief:
    format: '%(message)s'
  default:
    format: '%(asctime)s %(levelname)-8s %(name)-15s %(message)s'
    datefmt: '%Y-%m-%d %H:%M:%S'
  custom:
      (): my.package.customFormatterFactory
      bar: baz
      spam: 99.9
      answer: 42

Приведённый выше фрагмент YAML определяет три форматировщика. Первый, с идентификатором brief, является стандартным экземпляром logging.Formatter с указанной строкой формата. Второй, с идентификатором default, имеет более длинный формат, а также явно задаёт формат времени, и в результате будет создан экземпляр logging.Formatter, инициализированный этими двумя строками формата. В форме исходного кода Python под словари конфигурации форматировщиков brief и default выглядят так:

{
  'format' : '%(message)s'
}

и:

{
  'format' : '%(asctime)s %(levelname)-8s %(name)-15s %(message)s',
  'datefmt' : '%Y-%m-%d %H:%M:%S'
}

соответственно, и поскольку эти словари не содержат специального ключа '()', создание экземпляра выводится из контекста: в результате создаются стандартные экземпляры logging.Formatter. Подсловарь конфигурации для третьего форматировщика, с идентификатором custom, таков:

{
  '()' : 'my.package.customFormatterFactory',
  'bar' : 'baz',
  'spam' : 99.9,
  'answer' : 42
}

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

my.package.customFormatterFactory(bar='baz', spam=99.9, answer=42)

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

Вы также можете указать специальный ключ '.', значением которого является словарь, отображающий имена атрибутов в значения. Если такой ключ обнаружен, указанные атрибуты будут установлены на пользовательском объекте перед его возвратом. Таким образом, при следующей конфигурации:

{
  '()' : 'my.package.customFormatterFactory',
  'bar' : 'baz',
  'spam' : 99.9,
  'answer' : 42,
  '.' {
    'foo': 'bar',
    'baz': 'bozz'
  }
}

возвращаемый форматировщик будет иметь атрибут foo равный 'bar' и атрибут baz равный 'bozz'.

Порядок конфигурации обработчиков¶Handler configuration order

Обработчики настраиваются в алфавитном порядке их ключей, и настроенный обработчик заменяет словарь конфигурации в (рабочей копии) словаря handlers в схеме. Если используется конструкция вида cfg://handlers.foo, то изначально handlers['foo'] указывает на словарь конфигурации для обработчика с именем foo, а позже (после того как этот обработчик настроен) он указывает на экземпляр настроенного обработчика. Таким образом, cfg://handlers.foo может разрешаться либо в словарь, либо в экземпляр обработчика. В целом, рекомендуется давать имена обработчикам таким образом, чтобы зависимые обработчики настраивались _после_ обработчиков, от которых они зависят; это позволяет использовать что-то вроде cfg://handlers.foo при настройке обработчика, который зависит от обработчика foo. Если бы такой зависимый обработчик назывался bar, возникли бы проблемы, поскольку настройка bar была бы предпринята до настройки foo, и foo ещё не был бы настроен. Однако если бы зависимый обработчик назывался foobar, он был бы настроен после foo, в результате чего cfg://handlers.foo разрешился бы в настроенный обработчик foo, а не в его словарь конфигурации.

Доступ к внешним объектам¶Access to external objects

Бывают случаи, когда конфигурации требуется ссылаться на объекты внешние по отношению к конфигурации, например, sys.stderr. Если словарь конфигурации создаётся с помощью кода Python, это несложно, но проблема возникает, когда конфигурация задаётся через текстовый файл (например, JSON, YAML). В текстовом файле нет стандартного способа отличить sys.stderr от литеральной строки 'sys.stderr'. Чтобы облегчить это различие, система конфигурации ищет определённые специальные префиксы в строковых значениях и обрабатывает их особым образом. Например, если литеральная строка 'ext://sys.stderr' указана как значение в конфигурации, то префикс ext:// будет отброшен, а оставшаяся часть значения обработана с помощью стандартных механизмов импорта.

Обработка таких префиксов выполняется аналогично обработке протоколов: существует общий механизм поиска префиксов, соответствующих регулярному выражению ^(?P<prefix>[a-z]+)://(?P<suffix>.*)$, при котором, если префикс prefix распознан, часть suffix обрабатывается зависящим от префикса образом, и результат обработки заменяет строковое значение. Если префикс не распознан, строковое значение остаётся без изменений.

Доступ к внутренним объектам¶Access to internal objects

Помимо внешних объектов, иногда также возникает необходимость ссылаться на объекты в самой конфигурации. Это будет делаться неявно системой конфигурации для тех вещей, о которых она знает. Например, строковое значение 'DEBUG' для level в логгере или обработчике будет автоматически преобразовано в значение logging.DEBUG, а записи handlers, filters и formatter будут принимать идентификатор объекта и разрешаться в соответствующий целевой объект.

Однако необходим более общий механизм для пользовательских объектов, которые не известны модулю logging. Например, рассмотрим logging.handlers.MemoryHandler, который принимает аргумент target – другой обработчик для делегирования. Поскольку системе уже известен этот класс, то в конфигурации указанный target просто должен быть идентификатором объекта соответствующего целевого обработчика, и система разрешит его в обработчик по идентификатору. Однако если пользователь определяет my.package.MyHandler, у которого есть обработчик alternate, система конфигурации не будет знать, что alternate ссылается на обработчик. Чтобы учесть это, общая система разрешения позволяет пользователю указать:

handlers:
  file:
    # здесь задаётся конфигурация файлового обработчика

  custom:
    (): my.package.MyHandler
    alternate: cfg://handlers.file

Литеральная строка 'cfg://handlers.file' будет разрешаться аналогично строкам с префиксом ext://, но поиск будет вестись в самой конфигурации, а не в пространстве имён импорта. Этот механизм позволяет доступ по точке или по индексу, подобно тому, как это делается в str.format. Таким образом, для следующего фрагмента:

handlers:
  email:
    class: logging.handlers.SMTPHandler
    mailhost: localhost
    fromaddr: my_app@domain.tld
    toaddrs:
      - support_team@domain.tld
      - dev_team@domain.tld
    subject: Houston, we have a problem.

в конфигурации строка 'cfg://handlers' разрешается в словарь с ключом handlers, строка 'cfg://handlers.email разрешается в словарь с ключом email в словаре handlers, и так далее. Строка 'cfg://handlers.email.toaddrs[1] разрешается в 'dev_team@domain.tld', а строка 'cfg://handlers.email.toaddrs[0]' разрешается в значение 'support_team@domain.tld'. Значение subject может быть получено с помощью либо 'cfg://handlers.email.subject', либо (что эквивалентно) 'cfg://handlers.email[subject]'. Последняя форма требуется только в том случае, если ключ содержит пробелы или не алфавитно-цифровые символы. Если значение индекса состоит только из десятичных цифр, доступ будет предпринят с использованием соответствующего целочисленного значения, а при необходимости – строкового значения.

Для строки cfg://handlers.myhandler.mykey.123 результат будет config_dict['handlers']['myhandler']['mykey']['123']. Если строка указана как cfg://handlers.myhandler.mykey[123], система попытается получить значение из config_dict['handlers']['myhandler']['mykey'][123], а в случае неудачи вернётся к config_dict['handlers']['myhandler']['mykey']['123'].

Разрешение импорта и пользовательские импортёры¶Import resolution and custom importers

По умолчанию для импорта используется встроенная функция __import__(). Возможно, вы захотите заменить её собственным механизмом импорта: в таком случае можно заменить атрибут importer класса DictConfigurator или его суперкласса, BaseConfigurator. Однако нужно быть осторожным из-за того, как функции доступны из классов через дескрипторы. Если вы используете вызываемый объект Python для импорта и хотите определить его на уровне класса, а не экземпляра, необходимо обернуть его в staticmethod(). Например:

from importlib import import_module
from logging.config import BaseConfigurator

BaseConfigurator.importer = staticmethod(import_module)

Не нужно оборачивать в staticmethod(), если вы устанавливаете вызываемый объект импорта на экземпляре конфигуратора.