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

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

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

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

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

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

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

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

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

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

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

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

{
  '()' : '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. Если словарь конфигурации создаётся с помощью кода 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() использовать не нужно.