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

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

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

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

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

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

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

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

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

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

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

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

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

  • 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 объекта.

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

  • 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.put_nowait и Queue.get. Например, это может быть фактический экземпляр queue.Queue или его подкласс, или прокси, полученный с помощью multiprocessing.managers.SyncManager.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.