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

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

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

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

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

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

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

  • format

  • datefmt

  • style

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

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

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

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

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

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

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

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

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

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

    Изменено в версии 3.11: 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.

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

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

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

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

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

    Изменено в версии 3.11: filters может принимать экземпляры фильтров в дополнение к идентификаторам.

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

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

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

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

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

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

Постепенная настройка¶

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

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

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

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

Соединения с объектами¶

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

Так, например, рассмотрим следующий фрагмент кода 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)

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

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

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

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

Порядок настройки обработчика¶

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

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

Бывают случаи, когда конфигурация должна ссылаться на объекты, внешние по отношению к конфигурации, например sys.stderr. Если конфигурационный dict создан с использованием кода 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' преобразуется в dict с ключом handlers, строка 'cfg://handlers.email преобразуется в dict с ключом 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(), если вы устанавливаете вызываемый параметр импорта в экземпляре конфигуратора *.