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.

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

Связи между объектами

Схема описывает набор объектов журналирования — регистраторов, обработчиков, форматировщиков и фильтров, — связанных друг с другом в граф объектов. Поэтому схема должна представлять связи между объектами. Например, предположим, что после настройки к определённому регистратору подключён определённый обработчик. В рамках этого обсуждения можно считать регистратор источником, а обработчик — получателем связи между ними. Разумеется, в настроенных объектах это представлено ссылкой на обработчик, хранящейся в регистраторе. В словаре конфигурации каждому объекту-получателю присваивается однозначно идентифицирующий его идентификатор, а затем этот идентификатор используется в конфигурации объекта-источника, чтобы указать на наличие связи с объектом-получателем, имеющим такой идентификатор.

Например, рассмотрим следующий фрагмент 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.