logging.config — Настройка логгера

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

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

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

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

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

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

  • format
  • datefmt
  • style
  • validate (с версии >=3.8)

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

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

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

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

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

  • 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.

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

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

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

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

    Изменено в версии 3.11: 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. Подсловарь конфигурации для третьего форматера с id custom имеет вид:

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

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

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

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