15.8. logging.config – Настройка логирования¶logging.config – Logging configuration

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

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

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

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

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

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

15.8.2.2. Инкрементальная настройка¶Incremental Configuration

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

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

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

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

15.8.2.3. Соединения объектов¶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.

15.8.2.4. Пользовательские объекты¶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)

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

15.8.2.5. Доступ к внешним объектам¶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 обрабатывается зависящим от префикса образом, и результат обработки заменяет строковое значение. Если префикс не распознан, строковое значение остаётся без изменений.

15.8.2.6. Доступ к внутренним объектам¶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'].

15.8.2.7. Разрешение импорта и пользовательские импортёры¶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(), если вы устанавливаете вызываемый объект импорта на экземпляре конфигуратора.