logging.config — Настройка логгирования

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

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

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

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

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

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

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

• 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(), если вы устанавливаете вызываемый импорт на экземпляре конфигуратора.