logging.config — Конфигурация ведения журнала¶

Детали схемы словаря¶

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

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

Все остальные ключи необязательны, но если они присутствуют, то интерпретируются так, как описано ниже. Во всех описанных ниже случаях, когда упоминается „configuring dict“, он будет проверяться на наличие специального ключа '()', чтобы узнать, требуется ли пользовательский инстанс. Если да, то для создания экземпляра используется механизм, описанный ниже в Объекты, определяемые пользователем; в противном случае контекст используется для определения того, что нужно инстанцировать.

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

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

  • format

  • datefmt

  • style

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

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

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

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

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

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

  • 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
  

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

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

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

  • 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 определены три форматера. Первый, с id brief, является стандартным экземпляром logging.Formatter с указанной строкой формата. Второй, с id 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
}

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