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

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

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

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

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

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

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

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

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

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

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

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

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

  • 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 - соответствующее значение будет словарем, в котором каждый ключ — это имя логикатора, а каждое значение — это словарь, описывающий, как настроить соответствующий экземпляр Logger.

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

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

Настройка QueueHandler и QueueListener

Если вы хотите настроить QueueHandler, имея в виду, что это обычно используется совместно с QueueListener, вы можете настроить их вместе. После настройки экземпляр QueueListener будет доступен как атрибут listener созданного обработчика, а тот, в свою очередь, будет доступен вам с помощью getHandlerByName() и указанием имени, которое вы использовали для QueueHandler в вашей конфигурации. Схема словаря для настройки пары показана в примере YAML-фрагмента ниже.

handlers:
  qhand:
    class: logging.handlers.QueueHandler
    queue: my.module.queue_factory
    listener: my.package.CustomListener
    handlers:
      - hand_name_1
      - hand_name_2
      ...

Ключи queue и listener необязательны.

Если ключ queue присутствует, соответствующее значение может быть одним из следующих:

• Объект, реализующий общедоступный API queue.Queue. Например, это может быть фактический экземпляр queue.Queue или его подкласс, или прокси, полученный с помощью multiprocessing.managers.SyncManager.Queue().

  Это, конечно, возможно только если вы создаёте или изменяете словарь конфигурации в коде.

• Строка, которая разрешается в вызываемый объект, который, при вызове без аргументов, возвращает экземпляр queue.Queue для использования. Этот вызываемый объект может быть подклассом queue.Queue или функцией, возвращающей подходящий экземпляр очереди, например, my.module.queue_factory().
• Словарь с ключом '()', который создаётся обычным образом, как описано в Пользовательские объекты. Результатом этого создания должен быть экземпляр queue.Queue.

Если ключ queue отсутствует, создаётся и используется стандартный неограниченный экземпляр queue.Queue.

Если ключ listener присутствует, соответствующее значение может быть одним из следующих:

• Подкласс logging.handlers.QueueListener. Это, конечно, возможно только если вы создаёте или изменяете словарь конфигурации в коде.
• Строка, которая разрешается в класс, являющийся подклассом QueueListener, например, 'my.package.CustomListener'.
• Словарь с ключом '()', который создаётся обычным способом, как описано в Пользовательские объекты. Результатом этого создания должен быть вызываемый объект с той же сигнатурой, что и инициализатор QueueListener.

Если ключ listener отсутствует, используется logging.handlers.QueueListener.

Значения под ключом handlers — это имена других обработчиков в конфигурации (не показанных в приведенном выше фрагменте), которые будут переданы слушателю очереди.

Любые пользовательские классы обработчиков и слушателей очереди должны быть определены с теми же сигнатурами инициализации, что и QueueHandler и QueueListener.