15.6. logging – средство логирования для Python¶logging – Logging facility for Python

15.6.1.1. Простые примеры¶Simple examples

Большинство приложений, вероятно, захотят вести логирование в файл, поэтому начнём с этого случая. С помощью функции basicConfig() можно настроить обработчик по умолчанию так, чтобы отладочные сообщения записывались в файл (в примере предполагается, что у вас есть соответствующие разрешения для создания файла с именем example.log в текущем каталоге):

import logging
LOG_FILENAME = 'example.log'
logging.basicConfig(filename=LOG_FILENAME,level=logging.DEBUG)

logging.debug('This message should go to the log file')

Теперь, если открыть файл и посмотреть, что в нём, мы должны обнаружить сообщение журнала:

DEBUG:root:This message should go to the log file

Если запускать скрипт повторно, новые сообщения журнала будут добавляться в файл. Чтобы каждый раз создавать новый файл, можно передать аргумент filemode в basicConfig() со значением 'w'. Однако вместо того чтобы управлять размером файла вручную, проще использовать RotatingFileHandler:

import glob
import logging
import logging.handlers

LOG_FILENAME = 'logging_rotatingfile_example.out'

# Настроить конкретный регистратор с нужным уровнем вывода
my_logger = logging.getLogger('MyLogger')
my_logger.setLevel(logging.DEBUG)

# Добавить обработчик сообщений журнала в регистратор
handler = logging.handlers.RotatingFileHandler(
              LOG_FILENAME, maxBytes=20, backupCount=5)

my_logger.addHandler(handler)

# Записать несколько сообщений
for i in range(20):
    my_logger.debug('i = %d' % i)

# Посмотреть, какие файлы созданы
logfiles = glob.glob('%s*' % LOG_FILENAME)

for filename in logfiles:
    print(filename)

В результате должно получиться 6 отдельных файлов, каждый из которых содержит часть истории журнала приложения:

logging_rotatingfile_example.out
logging_rotatingfile_example.out.1
logging_rotatingfile_example.out.2
logging_rotatingfile_example.out.3
logging_rotatingfile_example.out.4
logging_rotatingfile_example.out.5

Самый текущий файл всегда называется logging_rotatingfile_example.out, и каждый раз, когда он достигает предельного размера, он переименовывается с суффиксом .1. Каждый из существующих резервных файлов переименовывается для увеличения суффикса (.1 становится .2 и т.д.), а файл .6 удаляется.

Очевидно, в этом примере максимальный размер файла установлен чрезвычайно малым для наглядности. Следует установить maxBytes в подходящее значение.

Ещё одна полезная возможность API логирования – создавать разные сообщения на разных уровнях логирования. Это позволяет, например, наполнить код отладочными сообщениями, но снизить уровень логирования так, чтобы в рабочей системе эти сообщения не записывались. Уровни по умолчанию: CRITICAL, ERROR, WARNING, INFO, DEBUG и NOTSET.

Логгер, обработчик и вызов сообщения – каждый задаёт свой уровень. Сообщение выводится только в том случае, если обработчик и логгер настроены на вывод сообщений этого уровня или ниже. Например, если сообщение имеет уровень CRITICAL, а логгер настроен на ERROR, сообщение будет выведено. Если сообщение имеет уровень WARNING, а логгер настроен на вывод только ERROR, сообщение не будет выведено:

import logging
import sys

LEVELS = {'debug': logging.DEBUG,
          'info': logging.INFO,
          'warning': logging.WARNING,
          'error': logging.ERROR,
          'critical': logging.CRITICAL}

if len(sys.argv) > 1:
    level_name = sys.argv[1]
    level = LEVELS.get(level_name, logging.NOTSET)
    logging.basicConfig(level=level)

logging.debug('This is a debug message')
logging.info('This is an info message')
logging.warning('This is a warning message')
logging.error('This is an error message')
logging.critical('This is a critical error message')

Запустите скрипт с аргументом, например, ‘debug’ или ‘warning’, чтобы увидеть, какие сообщения отображаются на разных уровнях:

$ python logging_level_example.py debug
DEBUG:root:This is a debug message
INFO:root:This is an info message
WARNING:root:This is a warning message
ERROR:root:This is an error message
CRITICAL:root:This is a critical error message

$ python logging_level_example.py info
INFO:root:This is an info message
WARNING:root:This is a warning message
ERROR:root:This is an error message
CRITICAL:root:This is a critical error message

Вы заметите, что во всех этих сообщениях журнала присутствует root. Модуль logging поддерживает иерархию логгеров с разными именами. Простой способ понять, откуда пришло конкретное сообщение, – использовать отдельный объект логгера для каждого модуля. Каждый новый логгер «наследует» конфигурацию своего родителя, а сообщения, отправленные логгеру, включают имя этого логгера. При желании каждый логгер можно настроить по-разному, чтобы сообщения от разных модулей обрабатывались различными способами. Рассмотрим простой пример логирования из разных модулей, чтобы легко было отследить источник сообщения:

import logging

logging.basicConfig(level=logging.WARNING)

logger1 = logging.getLogger('package1.module1')
logger2 = logging.getLogger('package2.module2')

logger1.warning('This message comes from one module')
logger2.warning('And this message comes from another module')

И вывод:

$ python logging_modules_example.py
WARNING:package1.module1:This message comes from one module
WARNING:package2.module2:And this message comes from another module

Существует гораздо больше возможностей для настройки логирования, включая разные варианты форматирования сообщений, доставку сообщений в несколько мест и изменение конфигурации долго работающего приложения на лету через сокетный интерфейс. Все эти возможности подробно описаны в документации библиотечного модуля.

15.6.1.2. Логгеры¶Loggers

Библиотека logging использует модульный подход и предлагает несколько категорий компонентов: логгеры, обработчики, фильтры и форматировщики. Логгеры предоставляют интерфейс, который напрямую используется кодом приложения. Обработчики отправляют записи журнала в соответствующее место назначения. Фильтры предоставляют более тонкое средство для определения того, какие записи журнала следует передать обработчику. Форматировщики задают структуру итоговой записи журнала.

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

Наиболее часто используемые методы объектов логгера делятся на две категории: настройка и отправка сообщений.

• Logger.setLevel() задаёт наименьшую степень важности сообщения, которое будет обрабатывать логгер; при этом debug – это наименьший встроенный уровень важности, а critical – наибольший. Например, если уровень важности установлен в info, логгер будет обрабатывать только сообщения info, warning, error и critical, игнорируя сообщения debug.
• Logger.addFilter() и Logger.removeFilter() добавляют и удаляют объекты фильтров из объекта логгера. В данном учебном пособии фильтры не рассматриваются.

После настройки объекта регистратора следующие методы создают сообщения журнала:

• Logger.debug(), Logger.info(), Logger.warning(), Logger.error() и Logger.critical() создают записи лога с сообщением и уровнем, соответствующими их именам методов. Сообщение – это строка формата, которая может содержать стандартный синтаксис подстановки строк %s, %d, %f и так далее. Остальные аргументы – список объектов, соответствующих полям подстановки в сообщении. Что касается **kwargs, методы логирования учитывают только ключевое слово exc_info и используют его для определения, нужно ли записывать информацию об исключении.
• Logger.exception() создает сообщение лога, аналогичное Logger.error(). Отличие в том, что Logger.exception() выводит вместе с ним трассировку стека. Вызывайте этот метод только из обработчика исключений.
• Logger.log() принимает уровень лога в качестве явного аргумента. Это немного более многословно для записи сообщений, чем использование удобных методов уровня лога, перечисленных выше, но именно так производится логирование на пользовательских уровнях лога.

getLogger() возвращает ссылку на экземпляр логгера с указанным именем, если оно задано, или root в противном случае. Имена представляют собой иерархические структуры, разделённые точками. При многократных вызовах getLogger() с одним и тем же именем возвращается ссылка на один и тот же объект логгера. Логгеры, находящиеся ниже в иерархическом списке, являются дочерними по отношению к логгерам, находящимся выше. Например, для логгера с именем foo логгеры с именами foo.bar, foo.bar.baz и foo.bam являются потомками foo. Дочерние логгеры передают сообщения вверх обработчикам, связанным с их логгерами-предками. Благодаря этому нет необходимости определять и настраивать обработчики для всех логгеров, используемых приложением. Достаточно настроить обработчики для логгера верхнего уровня и создавать дочерние логгеры по мере необходимости.

15.6.1.3. Обработчики¶Handlers

Объекты Handler отвечают за отправку соответствующих сообщений журнала (на основе их важности) в указанное место назначения. Объекты логгера могут добавлять к себе ноль или более объектов обработчиков с помощью метода addHandler(). В качестве примера: приложение может захотеть отправлять все сообщения в файл журнала, все сообщения уровня error и выше – в stdout, а все сообщения уровня critical – на адрес электронной почты. Для этого требуется три отдельных обработчика, каждый из которых отвечает за отправку сообщений определённого уровня важности в определённое место.

Стандартная библиотека включает довольно много типов обработчиков; в данном учебном пособии используются только StreamHandler и FileHandler.

В обработчике очень мало методов, которые должны беспокоить разработчиков приложений. Единственные методы обработчика, актуальные для разработчиков, использующих встроенные объекты-обработчики (то есть не создающих собственные обработчики), – это следующие методы настройки:

• Метод Handler.setLevel(), как и у объектов логгера, задаёт минимальный уровень серьезности, который будет отправлен в соответствующее место назначения. Зачем нужны два метода setLevel()? Уровень, установленный в логгере, определяет, сообщения какой серьезности он будет передавать своим обработчикам. Уровень, установленный в каждом обработчике, определяет, какие сообщения этот обработчик будет отправлять дальше.
• setFormatter() выбирает объект Formatter для использования этим обработчиком.
• addFilter() и removeFilter() соответственно добавляют и удаляют объекты фильтров у обработчиков.

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

15.6.1.4. Форматировщики¶Formatters

Объекты Formatter настраивают окончательный порядок, структуру и содержимое сообщения журнала. В отличие от базового класса logging.Handler, код приложения может создавать экземпляры классов форматировщиков, хотя при необходимости особого поведения можно создать подкласс форматировщика. Конструктор принимает два необязательных аргумента: строку формата сообщения и строку формата даты. Если строка формата сообщения не задана, по умолчанию используется исходное сообщение. Если строка формата даты не задана, используется следующий формат даты по умолчанию:

%Y-%m-%d %H:%M:%S

с добавленными в конце миллисекундами.

Строка формата сообщения использует подстановку строк в стиле %(<dictionary key>)s; возможные ключи описаны в разделе Объекты Formatter.

Следующая строка формата сообщения будет записывать время в удобочитаемом формате, уровень серьёзности сообщения и содержимое сообщения в указанном порядке:

"%(asctime)s - %(levelname)s - %(message)s"

Форматтеры используют настраиваемую пользователем функцию для преобразования времени создания записи в кортеж. По умолчанию используется time.localtime(); чтобы изменить это для конкретного экземпляра форматтера, установите атрибут converter экземпляра на функцию с той же сигнатурой, что и time.localtime() или time.gmtime(). Чтобы изменить это для всех форматтеров, например, если вы хотите, чтобы все время логирования отображалось в GMT, установите атрибут converter в классе Formatter (на time.gmtime для отображения в GMT).

15.6.1.5. Настройка логирования¶Configuring Logging

Программисты могут настраивать логирование двумя способами: явно создавать логгеры, обработчики и форматтеры в главном модуле с помощью перечисленных выше методов настройки (на Python) или создавая конфигурационный файл логирования. Следующий код – пример настройки очень простого логгера, обработчика консоли и простого форматтера в модуле Python:

import logging

# создать логгер
logger = logging.getLogger("simple_example")
logger.setLevel(logging.DEBUG)
# создать обработчик консоли и установить уровень DEBUG
ch = logging.StreamHandler()
ch.setLevel(logging.DEBUG)
# создать форматтер
formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
# добавить форматтер в ch
ch.setFormatter(formatter)
# добавить ch в логгер
logger.addHandler(ch)

# код "application"
logger.debug("debug message")
logger.info("info message")
logger.warn("warn message")
logger.error("error message")
logger.critical("critical message")

Запуск этого модуля из командной строки выдает следующий результат:

$ python simple_logging_module.py
2005-03-19 15:10:26,618 - simple_example - DEBUG - debug message
2005-03-19 15:10:26,620 - simple_example - INFO - info message
2005-03-19 15:10:26,695 - simple_example - WARNING - warn message
2005-03-19 15:10:26,697 - simple_example - ERROR - error message
2005-03-19 15:10:26,773 - simple_example - CRITICAL - critical message

Следующий модуль Python создает логгер, обработчик и форматтер, почти идентичные приведенным в примере выше, с единственным отличием – имена объектов.

import logging
import logging.config

logging.config.fileConfig("logging.conf")

# создать логгер
logger = logging.getLogger("simpleExample")

# код "application"
logger.debug("debug message")
logger.info("info message")
logger.warn("warn message")
logger.error("error message")
logger.critical("critical message")

Вот файл logging.conf:

[loggers]
keys=root,simpleExample

[handlers]
keys=consoleHandler

[formatters]
keys=simpleFormatter

[logger_root]
level=DEBUG
handlers=consoleHandler

[logger_simpleExample]
level=DEBUG
handlers=consoleHandler
qualname=simpleExample
propagate=0

[handler_consoleHandler]
class=StreamHandler
level=DEBUG
formatter=simpleFormatter
args=(sys.stdout,)

[formatter_simpleFormatter]
format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
datefmt=

Результат почти идентичен примеру без файла конфигурации:

$ python simple_logging_config.py
2005-03-19 15:38:55,977 - simpleExample - DEBUG - debug message
2005-03-19 15:38:55,979 - simpleExample - INFO - info message
2005-03-19 15:38:56,054 - simpleExample - WARNING - warn message
2005-03-19 15:38:56,055 - simpleExample - ERROR - error message
2005-03-19 15:38:56,130 - simpleExample - CRITICAL - critical message

Видно, что подход с файлом конфигурации имеет несколько преимуществ перед подходом с кодом Python: в первую очередь разделение конфигурации и кода, а также возможность для не-программистов легко изменять параметры журналирования.

15.6.1.6. Настройка логирования для библиотеки¶Configuring Logging for a Library

При разработке библиотеки, которая использует логирование, необходимо уделить внимание её настройке. Если использующее приложение не использует логирование, а код библиотеки вызывает функции логирования, то в консоль выводится одноразовое сообщение “No handlers could be found for logger X.Y.Z”. Это сообщение предназначено для выявления ошибок в настройке логирования, но может сбить с толку разработчика приложения, который не знает о логировании в библиотеке.

Помимо документирования того, как библиотека использует логирование, хороший способ настроить логирование библиотеки так, чтобы не появлялось ложное сообщение – добавить обработчик, который ничего не делает. Это предотвращает вывод сообщения, поскольку обработчик будет найден, но не производит никакого вывода. Если пользователь библиотеки настраивает логирование для приложения, то, предположительно, эта конфигурация добавит некоторые обработчики, и если уровни настроены правильно, то вызовы логирования в коде библиотеки будут отправлять вывод этим обработчикам, как обычно.

Обработчик, который ничего не делает, можно просто определить следующим образом:

import logging

class NullHandler(logging.Handler):
    def emit(self, record):
        pass

Экземпляр этого обработчика следует добавить к корневому логгеру пространства имён логирования, используемого библиотекой. Если всё логирование библиотеки foo осуществляется с помощью логгеров с именами вида “foo.x.y”, то код:

import logging

h = NullHandler()
logging.getLogger("foo").addHandler(h)

должен дать желаемый эффект. Если организация выпускает несколько библиотек, то имя логгера можно указать как “orgname.foo” вместо просто “foo”.

Новое в версии 3.1: Класс NullHandler.

15.6.9.1. Использование LoggerAdapter для передачи контекстной информации¶Using LoggerAdapters to impart contextual information

Простой способ передавать контекстную информацию для вывода вместе с событием логирования – использовать класс LoggerAdapter. Этот класс устроен так, что выглядит как Logger, поэтому можно вызывать debug(), info(), warning(), error(), exception(), critical() и log(). Сигнатуры этих методов совпадают с их аналогами в Logger, так что экземпляры обоих типов можно использовать взаимозаменяемо.

При создании экземпляра LoggerAdapter ему передаются экземпляр Logger и объект, подобный словарю, содержащий контекстную информацию. При вызове любого из методов логирования у экземпляра LoggerAdapter он делегирует вызов нижележащему экземпляру Logger, переданному в его конструктор, и обеспечивает передачу контекстной информации в делегированном вызове. Вот фрагмент кода LoggerAdapter:

def debug(self, msg, *args, **kwargs):
    """
    Передаёт вызов отладки нижележащему регистратору после добавления
    контекстной информации из данного экземпляра адаптера.
    """
    msg, kwargs = self.process(msg, kwargs)
    self.logger.debug(msg, *args, **kwargs)

Метод process() класса LoggerAdapter – это место, где контекстная информация добавляется в вывод логирования. Ему передаются сообщение и именованные аргументы вызова логирования, и он возвращает (возможно) изменённые версии этих данных для использования в вызове нижележащего логгера. В реализации по умолчанию этот метод оставляет сообщение без изменений, но добавляет ключ «extra» в именованные аргументы, значением которого является объект, подобный словарю, переданный в конструктор. Разумеется, если в вызове адаптера уже был передан именованный аргумент «extra», он будет молча перезаписан.

Преимущество использования «extra» в том, что значения из объекта, подобного словарю, сливаются в LogRecord.__dict__, что позволяет использовать настроенные строки с экземплярами Formatter, которым известны ключи этого объекта. Если нужен другой подход, например, требуется добавить контекстную информацию в начало или конец строки сообщения, достаточно создать подкласс LoggerAdapter и переопределить process(), чтобы он делал то, что нужно. Вот пример скрипта, использующего этот класс, который также демонстрирует, какое поведение, подобное словарю, требуется от произвольного «dict-like» объекта для использования в конструкторе:

import logging

class ConnInfo:
    """
    Пример класса, который показывает, как произвольный класс можно использовать в качестве
    хранилища контекстной информации 'extra', передаваемого LoggerAdapter.
    """

    def __getitem__(self, name):
        """
        Чтобы этот экземпляр выглядел как словарь.
        """
        from random import choice
        if name == "ip":
            result = choice(["127.0.0.1", "192.168.0.1"])
        elif name == "user":
            result = choice(["jim", "fred", "sheila"])
        else:
            result = self.__dict__.get(name, "?")
        return result

    def __iter__(self):
        """
        Чтобы разрешить итерацию по ключам, которые будут объединены в
        словарь LogRecord перед форматированием и выводом.
        """
        keys = ["ip", "user"]
        keys.extend(self.__dict__.keys())
        return keys.__iter__()

if __name__ == "__main__":
    from random import choice
    levels = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, logging.CRITICAL)
    a1 = logging.LoggerAdapter(logging.getLogger("a.b.c"),
                               { "ip" : "123.231.231.123", "user" : "sheila" })
    logging.basicConfig(level=logging.DEBUG,
                        format="%(asctime)-15s %(name)-5s %(levelname)-8s IP: %(ip)-15s User: %(user)-8s %(message)s")
    a1.debug("A debug message")
    a1.info("An info message with %s", "some parameters")
    a2 = logging.LoggerAdapter(logging.getLogger("d.e.f"), ConnInfo())
    for x in range(10):
        lvl = choice(levels)
        lvlname = logging.getLevelName(lvl)
        a2.log(lvl, "A message at %s level with %d %s", lvlname, 2, "parameters")

При запуске этого скрипта вывод должен выглядеть примерно так:

2008-01-18 14:49:54,023 a.b.c DEBUG    IP: 123.231.231.123 User: sheila   A debug message
2008-01-18 14:49:54,023 a.b.c INFO     IP: 123.231.231.123 User: sheila   An info message with some parameters
2008-01-18 14:49:54,023 d.e.f CRITICAL IP: 192.168.0.1     User: jim      A message at CRITICAL level with 2 parameters
2008-01-18 14:49:54,033 d.e.f INFO     IP: 192.168.0.1     User: jim      A message at INFO level with 2 parameters
2008-01-18 14:49:54,033 d.e.f WARNING  IP: 192.168.0.1     User: sheila   A message at WARNING level with 2 parameters
2008-01-18 14:49:54,033 d.e.f ERROR    IP: 127.0.0.1       User: fred     A message at ERROR level with 2 parameters
2008-01-18 14:49:54,033 d.e.f ERROR    IP: 127.0.0.1       User: sheila   A message at ERROR level with 2 parameters
2008-01-18 14:49:54,033 d.e.f WARNING  IP: 192.168.0.1     User: sheila   A message at WARNING level with 2 parameters
2008-01-18 14:49:54,033 d.e.f WARNING  IP: 192.168.0.1     User: jim      A message at WARNING level with 2 parameters
2008-01-18 14:49:54,033 d.e.f INFO     IP: 192.168.0.1     User: fred     A message at INFO level with 2 parameters
2008-01-18 14:49:54,033 d.e.f WARNING  IP: 192.168.0.1     User: sheila   A message at WARNING level with 2 parameters
2008-01-18 14:49:54,033 d.e.f WARNING  IP: 127.0.0.1       User: jim      A message at WARNING level with 2 parameters

15.6.9.2. Использование фильтров для передачи контекстной информации¶Using Filters to impart contextual information

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

Например, в веб-приложении обрабатываемый запрос (или, по крайней мере, его интересные части) может храниться в переменной threadlocal (threading.local), а затем извлекаться из Filter для добавления, скажем, информации из запроса – например, удаленного IP-адреса и имени пользователя – в LogRecord, используя имена атрибутов 'ip' и 'user', как в примере с LoggerAdapter выше. В этом случае можно использовать ту же строку формата для получения аналогичного вывода, показанного выше. Вот пример скрипта:

import logging
from random import choice

class ContextFilter(logging.Filter):
    """
    Это фильтр, который внедряет контекстную информацию в журнал.

    Вместо использования реальной контекстной информации в данном примере используются случайные
    данные.
    """

    USERS = ['jim', 'fred', 'sheila']
    IPS = ['123.231.231.123', '127.0.0.1', '192.168.0.1']

    def filter(self, record):

        record.ip = choice(ContextFilter.IPS)
        record.user = choice(ContextFilter.USERS)
        return True

if __name__ == "__main__":
   levels = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, logging.CRITICAL)
   a1 = logging.LoggerAdapter(logging.getLogger("a.b.c"),
                              { "ip" : "123.231.231.123", "user" : "sheila" })
   logging.basicConfig(level=logging.DEBUG,
                       format="%(asctime)-15s %(name)-5s %(levelname)-8s IP: %(ip)-15s User: %(user)-8s %(message)s")
   a1 = logging.getLogger("a.b.c")
   a2 = logging.getLogger("d.e.f")

   f = ContextFilter()
   a1.addFilter(f)
   a2.addFilter(f)
   a1.debug("A debug message")
   a1.info("An info message with %s", "some parameters")
   for x in range(10):
       lvl = choice(levels)
       lvlname = logging.getLevelName(lvl)
       a2.log(lvl, "A message at %s level with %d %s", lvlname, 2, "parameters")

который при запуске выдаёт примерно следующее:

2010-09-06 22:38:15,292 a.b.c DEBUG    IP: 123.231.231.123 User: fred     A debug message
2010-09-06 22:38:15,300 a.b.c INFO     IP: 192.168.0.1     User: sheila   An info message with some parameters
2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 127.0.0.1       User: sheila   A message at CRITICAL level with 2 parameters
2010-09-06 22:38:15,300 d.e.f ERROR    IP: 127.0.0.1       User: jim      A message at ERROR level with 2 parameters
2010-09-06 22:38:15,300 d.e.f DEBUG    IP: 127.0.0.1       User: sheila   A message at DEBUG level with 2 parameters
2010-09-06 22:38:15,300 d.e.f ERROR    IP: 123.231.231.123 User: fred     A message at ERROR level with 2 parameters
2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 192.168.0.1     User: jim      A message at CRITICAL level with 2 parameters
2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 127.0.0.1       User: sheila   A message at CRITICAL level with 2 parameters
2010-09-06 22:38:15,300 d.e.f DEBUG    IP: 192.168.0.1     User: jim      A message at DEBUG level with 2 parameters
2010-09-06 22:38:15,301 d.e.f ERROR    IP: 127.0.0.1       User: sheila   A message at ERROR level with 2 parameters
2010-09-06 22:38:15,301 d.e.f DEBUG    IP: 123.231.231.123 User: fred     A message at DEBUG level with 2 parameters
2010-09-06 22:38:15,301 d.e.f INFO     IP: 123.231.231.123 User: fred     A message at INFO level with 2 parameters

15.6.14.1. StreamHandler¶

Класс StreamHandler, находящийся в основном пакете logging, направляет вывод логирования в потоки, такие как sys.stdout, sys.stderr или любой объект, похожий на файл (точнее, любой объект, поддерживающий методы write() и flush()).

class logging.StreamHandler(stream=None)¶

Возвращает новый экземпляр класса StreamHandler. Если указан параметр поток данных, экземпляр использует его для вывода логирования; в противном случае используется sys.stderr.

emit(record)¶

Если задан форматтер, он используется для форматирования записи. Затем запись записывается в поток с завершающим символом новой строки. Если присутствует информация об исключении, она форматируется с помощью traceback.print_exception() и добавляется в поток.

flush()¶

Сбрасывает поток данных, вызывая его метод flush(). Обратите внимание, что метод close() наследуется от Handler и поэтому не выводит ничего, так что иногда может потребоваться явный вызов flush().

15.6.14.2. FileHandler¶

Класс FileHandler, находящийся в основном пакете logging, направляет вывод логирования в файл на диске. Он наследует функциональность вывода от StreamHandler.

class logging.FileHandler(filename, mode='a', encoding=None, delay=0)¶

Возвращает новый экземпляр класса FileHandler. Указанный файл открывается и используется как поток для логирования. Если mode не указан, используется 'a'. Если encoding не равен None, файл открывается с указанной кодировкой. Если delay равен true, открытие файла откладывается до первого вызова emit(). По умолчанию файл растёт бесконечно.

close()¶

Закрывает файл.

emit(record)¶

Выводит запись в файл.

15.6.14.3. NullHandler¶

Новое в версии 3.1.

Класс NullHandler, находящийся в основном пакете logging, не выполняет никакого форматирования или вывода. По сути, это обработчик-пустышка, предназначенный для разработчиков библиотек.

class logging.NullHandler¶

Возвращает новый экземпляр класса NullHandler.

emit(record)¶

Этот метод ничего не делает.

Смотрите Настройка логирования для библиотеки для получения дополнительной информации об использовании NullHandler.

15.6.14.4. WatchedFileHandler¶

Класс WatchedFileHandler, находящийся в модуле logging.handlers, представляет собой FileHandler, который следит за файлом, в который ведётся логирование. Если файл изменяется, он закрывается и открывается заново по тому же имени файла.

Файл может измениться из-за использования таких программ, как newsyslog и logrotate, которые выполняют ротацию файлов журнала. Этот обработчик, предназначенный для использования в Unix/Linux, следит, не изменился ли файл с момента последнего вызова emit. (Считается, что файл изменился, если изменились его устройство или inode.) Если файл изменился, старый поток файла закрывается, а файл открывается для получения нового потока.

Этот обработчик не подходит для использования в Windows, поскольку в Windows открытые файлы журналов нельзя перемещать или переименовывать – система логирования открывает файлы с эксклюзивными блокировками, – поэтому в таком обработчике нет необходимости. Кроме того, ST_INO не поддерживается в Windows; stat() всегда возвращает ноль для этого значения.

class logging.handlers.WatchedFileHandler(filename[, mode[, encoding[, delay]]])¶

Возвращает новый экземпляр класса WatchedFileHandler. Указанный файл открывается и используется как поток для логирования. Если mode не указан, используется 'a'. Если encoding не равен None, файл открывается с указанной кодировкой. Если delay равен true, открытие файла откладывается до первого вызова emit(). По умолчанию файл растёт бесконечно.

emit(record)¶

Выводит запись в файл, но сначала проверяет, изменился ли файл. Если изменился, существующий поток сбрасывается и закрывается, а файл открывается заново, после чего запись выводится в файл.

15.6.14.5. RotatingFileHandler¶

Класс RotatingFileHandler, находящийся в модуле logging.handlers, поддерживает ротацию файлов журналов на диске.

class logging.handlers.RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=0)¶

Возвращает новый экземпляр класса RotatingFileHandler. Указанный файл открывается и используется как поток для журналирования. Если mode не указан, используется 'a'. Если encoding не равен None, файл открывается с указанной кодировкой. Если delay равен истине, открытие файла откладывается до первого вызова emit(). По умолчанию файл растёт бесконечно.

С помощью параметров maxBytes и backupCount можно настроить ротацию файла при достижении заданного размера. Когда размер собирается быть превышен, файл закрывается и новый файл молча открывается для записи. Ротация происходит всякий раз, когда текущий файл журнала достигает длины, близкой к maxBytes; если maxBytes равен нулю, ротация не происходит. Если backupCount не равен нулю, система сохраняет старые файлы журналов, добавляя к имени файла расширения «.1», «.2» и т.д. Например, при backupCount равном 5 и исходном имени файла app.log вы получите app.log, app.log.1, app.log.2, вплоть до app.log.5. Файл, в который ведется запись, всегда app.log. Когда этот файл заполняется, он закрывается и переименовывается в app.log.1, а если существуют файлы app.log.1, app.log.2 и т.д., то они переименовываются соответственно в app.log.2, app.log.3 и так далее.

doRollover()¶

Выполняет ротацию, как описано выше.

emit(record)¶

Записывает запись (record) в файл, выполняя при необходимости ротацию, как описано ранее.

15.6.14.6. TimedRotatingFileHandler¶

Класс TimedRotatingFileHandler, находящийся в модуле logging.handlers, поддерживает ротацию файлов журналов на диске через заданные промежутки времени.

class logging.handlers.TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=0, utc=False)¶

Возвращает новый экземпляр класса TimedRotatingFileHandler. Указанный файл открывается и используется как поток для журналирования. При ротации также устанавливается суффикс имени файла. Ротация происходит на основе произведения when и interval.

Параметр when указывает тип interval. Список возможных значений приведён ниже. Обратите внимание, что регистр не учитывается.

Значение	Тип интервала
'S'	Секунды
'M'	Минуты
'H'	Часы
'D'	Дни
'W'	День недели (0 = понедельник)
'midnight'	Переключение в полночь

Система будет сохранять старые файлы журнала, добавляя расширения к имени файла. Расширения основаны на дате и времени, с использованием формата strftime %Y-%m-%d_%H-%M-%S или его начальной части, в зависимости от интервала ротации.

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

Если аргумент utc равен true, используется время в UTC; в противном случае используется местное время.

Если backupCount не равен нулю, сохраняется не более backupCount файлов; если при ротации должно быть создано больше файлов, самый старый удаляется. Логика удаления использует интервал для определения того, какие файлы нужно удалить, поэтому изменение интервала может привести к тому, что старые файлы останутся.

Если delay равен true, открытие файла откладывается до первого вызова emit().

doRollover()¶

Выполняет ротацию, как описано выше.

emit(record)¶

Выводит запись в файл, обеспечивая ротацию, как описано выше.

15.6.14.7. SocketHandler¶

Класс SocketHandler, расположенный в модуле logging.handlers, отправляет вывод журнала на сетевой сокет. Базовый класс использует TCP-сокет.

class logging.handlers.SocketHandler(host, port)¶

Возвращает новый экземпляр класса SocketHandler, предназначенного для взаимодействия с удаленной машиной, адрес которой задается host и port.

close()¶

Закрывает сокет.

emit()¶

Сериализует словарь атрибутов записи и записывает его в сокет в бинарном формате. Если при работе с сокетом возникает ошибка, пакет молча отбрасывается. Если соединение было ранее потеряно, оно восстанавливается. Для десериализации записи на принимающей стороне в LogRecord используйте функцию makeLogRecord().

handleError()¶

Обрабатывает ошибку, возникшую во время emit(). Наиболее вероятная причина – потеря соединения. Закрывает сокет, чтобы можно было повторить попытку при следующем событии.

makeSocket()¶

Это фабричный метод, позволяющий подклассам определять точный тип сокета, который они хотят. Реализация по умолчанию создает TCP-сокет (socket.SOCK_STREAM).

makePickle(record)¶

Сериализует словарь атрибутов записи в двоичном формате с префиксом длины и возвращает его готовым к передаче через сокет.

Обратите внимание, что модуль pickle не является полностью безопасным. Если вас беспокоит безопасность, вы можете переопределить этот метод, чтобы реализовать более надёжный механизм. Например, можно подписывать данные с помощью HMAC и проверять подпись на принимающей стороне, либо отключить десериализацию глобальных объектов на принимающей стороне.

send(packet)¶

Отправляет сериализованную с помощью pickle строку packet в сокет. Эта функция допускает частичную отправку, которая может произойти, когда сеть занята.

15.6.14.8. DatagramHandler¶

Класс DatagramHandler, расположенный в модуле logging.handlers , наследуется от SocketHandler для поддержки отправки сообщений журнала через UDP-сокеты.

class logging.handlers.DatagramHandler(host, port)¶

Возвращает новый экземпляр класса DatagramHandler, предназначенного для взаимодействия с удаленной машиной, адрес которой задается host и port.

emit()¶

Сериализует словарь атрибутов записи и записывает его в сокет в бинарном формате. Если при работе с сокетом возникает ошибка, пакет молча отбрасывается. Для десериализации записи на принимающей стороне в LogRecord используйте функцию makeLogRecord().

makeSocket()¶

Фабричный метод SocketHandler здесь переопределен для создания UDP-сокета (socket.SOCK_DGRAM).

send(s)¶

Отправляет сериализованную с помощью pickle строку в сокет.

15.6.14.9. SysLogHandler¶

Класс SysLogHandler, расположенный в модуле logging.handlers, поддерживает отправку сообщений журнала в удаленный или локальный системный журнал Unix.

class logging.handlers.SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER)¶

Возвращает новый экземпляр класса SysLogHandler, предназначенный для связи с удаленной Unix-машиной, адрес которой задается параметром address в виде кортежа (host, port). Если address не указан, используется ('localhost', 514). Адрес используется для открытия UDP-сокета. Альтернативой кортежу (host, port) является указание адреса в виде строки, например “/dev/log”. В этом случае для отправки сообщения в syslog используется сокет домена Unix. Если facility не указан, используется LOG_USER.

close()¶

Закрывает сокет, подключённый к удалённому узлу.

emit(record)¶

Запись форматируется и отправляется на сервер syslog. Если присутствует информация об исключении, она не отправляется на сервер.

encodePriority(facility, priority)¶

Кодирует средство и приоритет в целое число. Можно передавать строки или целые числа – если передаются строки, внутренние словари сопоставлений используются для преобразования их в целые числа.

Символические значения LOG_ определены в SysLogHandler и соответствуют значениям, определённым в заголовочном файле sys/syslog.h.

Приоритеты

Имя (строка)	Символическое значение
alert	LOG_ALERT
crit или critical	LOG_CRIT
отладка	LOG_DEBUG
аварийная или паника	LOG_EMERG
ошибка или ошибка	LOG_ERR
информация	LOG_INFO
уведомление	LOG_NOTICE
предупреждение или предупреждение	LOG_WARNING

Средства

Имя (строка)	Символическое значение
аутентификация	LOG_AUTH
authpriv	LOG_AUTHPRIV
cron	LOG_CRON
демон	LOG_DAEMON
ftp	LOG_FTP
ядро	LOG_KERN
lpr	LOG_LPR
почта	LOG_MAIL
новости	LOG_NEWS
syslog	LOG_SYSLOG
user	LOG_USER
uucp	LOG_UUCP
local0	LOG_LOCAL0
local1	LOG_LOCAL1
local2	LOG_LOCAL2
local3	LOG_LOCAL3
local4	LOG_LOCAL4
local5	LOG_LOCAL5
local6	LOG_LOCAL6
local7	LOG_LOCAL7

mapPriority(levelname)¶

Сопоставляет имя уровня журналирования с именем приоритета syslog. Возможно, потребуется переопределить его, если используются пользовательские уровни или стандартный алгоритм не подходит для ваших нужд. Стандартный алгоритм сопоставляет DEBUG, INFO, WARNING, ERROR и CRITICAL с соответствующими именами syslog, а все остальные имена уровней – с «warning».

15.6.14.10. NTEventLogHandler¶

Класс NTEventLogHandler, находящийся в модуле logging.handlers, поддерживает отправку сообщений журналирования в журнал событий локальной Windows NT, Windows 2000 или Windows XP. Перед использованием необходимо установить расширения Win32 от Марка Хэммонда для Python.

class logging.handlers.NTEventLogHandler(appname, dllname=None, logtype='Application')¶

Возвращает новый экземпляр класса NTEventLogHandler. Параметр appname используется для определения имени приложения, отображаемого в журнале событий. С использованием этого имени создается соответствующая запись реестра. Параметр dllname должен содержать полный путь к .dll или .exe-файлу с определениями сообщений для хранения в журнале (если не указан, используется 'win32service.pyd' – он устанавливается вместе с расширениями Win32 и содержит несколько базовых определений сообщений-заполнителей. Обратите внимание, что использование этих заполнителей приведет к увеличению размера журнала, так как весь источник сообщений хранится в журнале. Если нужны более компактные журналы, следует передать имя собственного .dll или .exe, содержащего нужные определения сообщений). Параметр logtype может быть одним из 'Application', 'System' или 'Security', по умолчанию 'Application'.

close()¶

На этом этапе можно удалить имя приложения из реестра как источник записей журнала событий. Однако после этого события не будут отображаться в средстве просмотра журнала событий так, как предполагалось – для получения имени .dll требуется доступ к реестру. Текущая версия этого не делает.

emit(record)¶

Определяет идентификатор сообщения, категорию и тип события, а затем записывает сообщение в журнал событий NT.

getEventCategory(record)¶

Возвращает категорию события для записи. Переопределите этот метод, чтобы указать собственные категории. Данная версия возвращает 0.

getEventType(record)¶

Возвращает тип события для записи. Переопределите этот метод, если нужно задать собственные типы. В данной версии используется сопоставление через атрибут typemap обработчика, который устанавливается в __init__() в виде словаря, содержащего сопоставления для DEBUG, INFO, WARNING, ERROR и CRITICAL. При использовании собственных уровней потребуется либо переопределить этот метод, либо поместить подходящий словарь в атрибут typemap обработчика.

getMessageID(record)¶

Возвращает идентификатор сообщения для записи. При использовании собственных сообщений можно передать в логгер идентификатор msg вместо строки форматирования. Затем здесь можно выполнить поиск по словарю для получения идентификатора сообщения. Данная версия возвращает 1 – базовый идентификатор сообщения в win32service.pyd.

15.6.14.11. SMTPHandler¶

Класс SMTPHandler, находящийся в модуле logging.handlers, поддерживает отправку сообщений журналирования на адрес электронной почты через SMTP.

class logging.handlers.SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None)¶

Возвращает новый экземпляр класса SMTPHandler. Экземпляр инициализируется адресами отправителя, получателя и темой письма. Параметр toaddrs должен быть списком строк. Для указания нестандартного порта SMTP используется кортеж (host, port) в аргументе mailhost. Если передана строка, используется стандартный порт SMTP. Если SMTP-сервер требует аутентификации, можно указать кортеж (username, password) в аргументе credentials.

emit(record)¶

Форматирует запись и отправляет её указанным получателям.

getSubject(record)¶

Чтобы задать тему письма, зависящую от записи, переопределите этот метод.

15.6.14.12. MemoryHandler¶

Класс MemoryHandler, находящийся в модуле logging.handlers, поддерживает буферизацию записей журналирования в памяти с периодической отправкой их в обработчик target. Сброс происходит, когда буфер полон или когда появляется событие определённой важности или выше.

MemoryHandler является подклассом более общего BufferingHandler, который является абстрактным классом. Он буферизирует записи журналирования в памяти. Каждый раз, когда запись добавляется в буфер, вызывается shouldFlush() для проверки необходимости сброса буфера. Если сброс нужен, то flush() должен выполнить необходимые действия.

class logging.handlers.BufferingHandler(capacity)¶

Инициализирует обработчик буфером указанной ёмкости.

emit(record)¶

Добавляет запись в буфер. Если shouldFlush() возвращает true, вызывает flush() для обработки буфера.

flush()¶

Вы можете переопределить этот метод, чтобы задать собственное поведение при сбросе. Текущая версия просто очищает буфер.

shouldFlush(record)¶

Возвращает true, если буфер заполнен до ёмкости. Этот метод можно переопределить для реализации собственных стратегий сброса.

class logging.handlers.MemoryHandler(capacity, flushLevel=ERROR, target=None)¶

Возвращает новый экземпляр класса MemoryHandler. Экземпляр инициализируется с размером буфера capacity. Если flushLevel не указан, используется ERROR. Если target не указан, перед тем как обработчик начнёт работать, цель нужно задать с помощью setTarget().

close()¶

Вызывает flush(), устанавливает цель в None и очищает буфер.

flush()¶

Для MemoryHandler сброс означает просто отправку буферизированных записей целевому обработчику, если он есть. Переопределите, если требуется иное поведение.

setTarget(target)¶

Устанавливает целевой обработчик для данного обработчика.

shouldFlush(record)¶

Проверяет, заполнен ли буфер или поступила запись уровня flushLevel или выше.

15.6.14.13. HTTPHandler¶

Класс HTTPHandler, расположенный в модуле logging.handlers, поддерживает отправку сообщений журнала на веб-сервер, используя семантику GET или POST.

class logging.handlers.HTTPHandler(host, url, method='GET')¶

Возвращает новый экземпляр класса HTTPHandler. Экземпляр инициализируется адресом хоста, URL и HTTP-методом. host может быть в формате host:port, если требуется указать определённый номер порта. Если method не указан, используется GET.

emit(record)¶

Отправляет запись на веб-сервер в виде словаря в процентной кодировке.

15.6.20.1. Функции конфигурации¶Configuration functions

Следующие функции настраивают модуль логирования. Они находятся в модуле logging.config. Их использование необязательно – настроить модуль логирования можно как с помощью этих функций, так и напрямую через основной API (определённый в самом logging) и определением обработчиков, объявленных либо в logging, либо в logging.handlers.

logging.fileConfig(fname, defaults=None, disable_existing_loggers=True)¶

Читает конфигурацию логирования из файла формата configparser с именем fname. Эту функцию можно вызывать несколько раз из приложения, что позволяет конечному пользователю выбирать из различных готовых конфигураций (если разработчик предоставляет механизм для отображения вариантов и загрузки выбранной конфигурации). Значения по умолчанию, передаваемые в ConfigParser, можно указать в аргументе defaults.

Если disable_existing_loggers равен True, все существующие логгеры, которые не являются дочерними по отношению к именованным логгерам, будут отключены.

logging.listen(port=DEFAULT_LOGGING_CONFIG_PORT)¶

Запускает сокет-сервер на указанном порту и ожидает новые конфигурации. Если порт не указан, используется значение по умолчанию модуля DEFAULT_LOGGING_CONFIG_PORT. Конфигурации логирования отправляются в виде файла, пригодного для обработки функцией fileConfig(). Возвращает экземпляр поток, на котором можно вызвать start() для запуска сервера и к которому при необходимости можно применить join(). Чтобы остановить сервер, вызовите stopListening().

Чтобы отправить конфигурацию в сокет, прочитайте файл конфигурации и отправьте его в сокет в виде строки байтов, перед которой идёт четырёхбайтовая длина, упакованная в двоичном виде с помощью struct.pack('>L', n).

logging.stopListening()¶

Останавливает сервер прослушивания, созданный вызовом listen(). Обычно вызывается перед вызовом join() на возвращаемом значении listen().

15.6.20.2. Формат файла конфигурации¶Configuration file format

The configuration file format understood by fileConfig() is based on configparser functionality. The file must contain sections called [loggers], [handlers] and [formatters] which identify by name the entities of each type which are defined in the file. For each such entity, there is a separate section which identifies how that entity is configured. Thus, for a logger named log01 in the [loggers] section, the relevant configuration details are held in a section [logger_log01]. Similarly, a handler called hand01 in the [handlers] section will have its configuration held in a section called [handler_hand01], while a formatter called form01 in the [formatters] section will have its configuration specified in a section called [formatter_form01]. The root logger configuration must be specified in a section called [logger_root].

Примеры таких разделов в файле приведены ниже.

[loggers]
keys=root,log02,log03,log04,log05,log06,log07

[handlers]
keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09

[formatters]
keys=form01,form02,form03,form04,form05,form06,form07,form08,form09

Корневой регистратор должен указывать уровень и список обработчиков. Пример раздела корневого регистратора приведен ниже.

[logger_root]
level=NOTSET
handlers=hand01

The level entry can be one of DEBUG, INFO, WARNING, ERROR, CRITICAL or NOTSET. For the root logger only, NOTSET means that all messages will be logged. Level values are eval()uated in the context of the logging package’s namespace.

The handlers entry is a comma-separated list of handler names, which must appear in the [handlers] section. These names must appear in the [handlers] section and have corresponding sections in the configuration file.

Для регистраторов, отличных от корневого, требуется некоторая дополнительная информация. Это проиллюстрировано следующим примером.

[logger_parser]
level=DEBUG
handlers=hand01
propagate=1
qualname=compiler.parser

The level and handlers entries are interpreted as for the root logger, except that if a non-root logger’s level is specified as NOTSET, the system consults loggers higher up the hierarchy to determine the effective level of the logger. The propagate entry is set to 1 to indicate that messages must propagate to handlers higher up the logger hierarchy from this logger, or 0 to indicate that messages are not propagated to handlers up the hierarchy. The qualname entry is the hierarchical channel name of the logger, that is to say the name used by the application to get the logger.

Разделы, которые задают конфигурацию обработчика, иллюстрируются следующим примером.

[handler_hand01]
class=StreamHandler
level=NOTSET
formatter=form01
args=(sys.stdout,)

Запись class указывает класс обработчика (определяемый с помощью eval() в пространстве имён пакета logging). Значение level интерпретируется так же, как для логгеров, а NOTSET означает «логировать всё».

The formatter entry indicates the key name of the formatter for this handler. If blank, a default formatter (logging._defaultFormatter) is used. If a name is specified, it must appear in the [formatters] section and have a corresponding section in the configuration file.

Запись args при вычислении eval() в контексте пространства имён пакета logging представляет собой список аргументов для конструктора класса обработчика. Обратитесь к конструкторам соответствующих обработчиков или к примерам ниже, чтобы узнать, как формируются типичные записи.

[handler_hand02]
class=FileHandler
level=DEBUG
formatter=form02
args=('python.log', 'w')

[handler_hand03]
class=handlers.SocketHandler
level=INFO
formatter=form03
args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)

[handler_hand04]
class=handlers.DatagramHandler
level=WARN
formatter=form04
args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)

[handler_hand05]
class=handlers.SysLogHandler
level=ERROR
formatter=form05
args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)

[handler_hand06]
class=handlers.NTEventLogHandler
level=CRITICAL
formatter=form06
args=('Python Application', '', 'Application')

[handler_hand07]
class=handlers.SMTPHandler
level=WARN
formatter=form07
args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')

[handler_hand08]
class=handlers.MemoryHandler
level=NOTSET
formatter=form08
target=
args=(10, ERROR)

[handler_hand09]
class=handlers.HTTPHandler
level=NOTSET
formatter=form09
args=('localhost:9022', '/log', 'GET')

Разделы, которые задают конфигурацию форматировщика, обычно выглядят следующим образом.

[formatter_form01]
format=F1 %(asctime)s %(levelname)s %(message)s
datefmt=
class=logging.Formatter

Запись format – это общая строка формата, а запись datefmt – это строка формата даты/времени, совместимая с strftime(). Если она пуста, пакет подставляет дату/время в формате ISO8601, что почти эквивалентно указанию строки формата даты "%Y-%m-%d %H:%M:%S". Формат ISO8601 также задаёт миллисекунды, которые добавляются к результату использования указанной выше строки формата через запятую. Пример времени в формате ISO8601: 2003-01-23 00:29:50,411.

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

15.6.20.3. Пример сервера конфигурации¶Configuration server example

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

import logging
import logging.config
import time
import os

# Прочитать начальный конфигурационный файл.
logging.config.fileConfig("logging.conf")

# Создать и запустить слушатель на порту 9999.
t = logging.config.listen(9999)
t.start()

logger = logging.getLogger("simpleExample")

try:
    # Прокрутить вызовы логирования, чтобы увидеть разницу.
    # Создавать новые конфигурации до нажатия Ctrl+C.
    while True:
        logger.debug("debug message")
        logger.info("info message")
        logger.warn("warn message")
        logger.error("error message")
        logger.critical("critical message")
        time.sleep(5)
except KeyboardInterrupt:
    # очистка
    logging.config.stopListening()
    t.join()

А вот скрипт, который принимает имя файла и отправляет этот файл на сервер, предварив его двоично-закодированной длиной, в качестве новой конфигурации журналирования:

#!/usr/bin/env python
import socket, sys, struct

data_to_send = open(sys.argv[1], "r").read()

HOST = 'localhost'
PORT = 9999
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
print("connecting...")
s.connect((HOST, PORT))
print("sending config...")
s.send(struct.pack(">L", len(data_to_send)))
s.send(data_to_send)
s.close()
print("complete")

15.6.21.1. Несколько обработчиков и форматировщиков¶Multiple handlers and formatters

Логгеры – это обычные объекты Python. У метода addHandler() нет минимального или максимального ограничения на количество добавляемых обработчиков. Иногда бывает полезно, чтобы приложение записывало все сообщения всех уровней в текстовый файл и одновременно выводило ошибки и выше на консоль. Чтобы это настроить, достаточно сконфигурировать соответствующие обработчики. Вызовы логирования в коде приложения останутся без изменений. Вот небольшая модификация предыдущего простого примера конфигурации на основе модуля:

import logging

logger = logging.getLogger("simple_example")
logger.setLevel(logging.DEBUG)
# создать файловый обработчик, записывающий даже отладочные сообщения
fh = logging.FileHandler("spam.log")
fh.setLevel(logging.DEBUG)
# создать консольный обработчик с более высоким уровнем логирования
ch = logging.StreamHandler()
ch.setLevel(logging.ERROR)
# создать форматтер и добавить его к обработчикам
formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
ch.setFormatter(formatter)
fh.setFormatter(formatter)
# добавить обработчики в логгер
logger.addHandler(ch)
logger.addHandler(fh)

# код "application"
logger.debug("debug message")
logger.info("info message")
logger.warn("warn message")
logger.error("error message")
logger.critical("critical message")

Обратите внимание, что код «приложения» безразличен к наличию нескольких обработчиков. Всё, что изменилось – это добавление и настройка нового обработчика с именем fh.

Возможность создавать новые обработчики с фильтрами более высокого или низкого уровня серьезности может быть очень полезна при написании и тестировании приложения. Вместо использования множества операторов print для отладки используйте logger.debug: в отличие от операторов print, которые вам придется удалить или закомментировать позже, операторы logger.debug могут оставаться в исходном коде и оставаться неактивными до тех пор, пока они снова не понадобятся. В этом случае единственное, что нужно сделать, – изменить уровень серьезности логгера и/или обработчика на debug.

15.6.21.2. Использование логирования в нескольких модулях¶Using logging in multiple modules

Выше упоминалось, что многократные вызовы logging.getLogger('someLogger') возвращают ссылку на один и тот же объект логгера. Это верно не только в пределах одного модуля, но и между модулями, пока они находятся в одном процессе интерпретатора Python. Это справедливо для ссылок на один и тот же объект; кроме того, код приложения может определить и настроить родительский логгер в одном модуле и создать (но не настраивать) дочерний логгер в другом модуле, и все вызовы логгера к дочернему будут передаваться родительскому. Вот пример главного модуля:

import logging
import auxiliary_module

# создать логгер с именем "spam_application"
logger = logging.getLogger("spam_application")
logger.setLevel(logging.DEBUG)
# создать файловый обработчик, записывающий даже отладочные сообщения
fh = logging.FileHandler("spam.log")
fh.setLevel(logging.DEBUG)
# создать консольный обработчик с более высоким уровнем логирования
ch = logging.StreamHandler()
ch.setLevel(logging.ERROR)
# создать форматтер и добавить его к обработчикам
formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
fh.setFormatter(formatter)
ch.setFormatter(formatter)
# добавить обработчики к логгеру
logger.addHandler(fh)
logger.addHandler(ch)

logger.info("creating an instance of auxiliary_module.Auxiliary")
a = auxiliary_module.Auxiliary()
logger.info("created an instance of auxiliary_module.Auxiliary")
logger.info("calling auxiliary_module.Auxiliary.do_something")
a.do_something()
logger.info("finished auxiliary_module.Auxiliary.do_something")
logger.info("calling auxiliary_module.some_function()")
auxiliary_module.some_function()
logger.info("done with auxiliary_module.some_function()")

А вот вспомогательный модуль:

import logging

# создать логгер
module_logger = logging.getLogger("spam_application.auxiliary")

class Auxiliary:
    def __init__(self):
        self.logger = logging.getLogger("spam_application.auxiliary.Auxiliary")
        self.logger.info("creating an instance of Auxiliary")
    def do_something(self):
        self.logger.info("doing something")
        a = 1 + 1
        self.logger.info("done doing something")

def some_function():
    module_logger.info("received a call to \"some_function\"")

Вывод выглядит так:

2005-03-23 23:47:11,663 - spam_application - INFO -
   creating an instance of auxiliary_module.Auxiliary
2005-03-23 23:47:11,665 - spam_application.auxiliary.Auxiliary - INFO -
   creating an instance of Auxiliary
2005-03-23 23:47:11,665 - spam_application - INFO -
   created an instance of auxiliary_module.Auxiliary
2005-03-23 23:47:11,668 - spam_application - INFO -
   calling auxiliary_module.Auxiliary.do_something
2005-03-23 23:47:11,668 - spam_application.auxiliary.Auxiliary - INFO -
   doing something
2005-03-23 23:47:11,669 - spam_application.auxiliary.Auxiliary - INFO -
   done doing something
2005-03-23 23:47:11,670 - spam_application - INFO -
   finished auxiliary_module.Auxiliary.do_something
2005-03-23 23:47:11,671 - spam_application - INFO -
   calling auxiliary_module.some_function()
2005-03-23 23:47:11,672 - spam_application.auxiliary - INFO -
   received a call to "some_function"
2005-03-23 23:47:11,673 - spam_application - INFO -
   done with auxiliary_module.some_function()