logging.config — Настройка ведения журнала

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

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

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

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

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

  В словаре конфигурации ищутся ключи format и datefmt (с значениями по умолчанию None) и они используются для построения экземпляра Formatter.

  Изменено в версии 3.8: в раздел formatters словаря конфигурации может быть добавлен ключ validate (по умолчанию True) для проверки формата.

• 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, конфигурация обрабатывается, как описано в разделе Инкрементальная конфигурация.

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

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

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

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

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

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

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

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

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

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

formatters:
  brief:
    # configuration for formatter with id 'brief' goes here
  precise:
    # configuration for formatter with id 'precise' goes here
handlers:
  h1: #This is an id
   # configuration of handler with id 'h1' goes here
   formatter: brief
  h2: #This is another id
   # configuration of handler with id 'h2' goes here
   formatter: precise
loggers:
  foo.bar.baz:
    # other configuration for logger 'foo.bar.baz'
    handlers: [h1, h2]

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

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

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

Пользовательские объекты

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

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

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)

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

Доступ к внешним объектам

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

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

Доступ к внутренним объектам

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

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

handlers:
  file:
    # configuration of file handler goes here

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

from importlib import import_module
from logging.config import BaseConfigurator

BaseConfigurator.importer = staticmethod(import_module)

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