Действующие лица¶

Конфигурация логгирования в Python состоит из четырех частей:

• Loggers(Логгеры)

• Handlers(Обработчики)

• Фильтры

• Formatters(Форматер)

AdminEmailHandler¶

Встроенный AdminEmailHandler заслуживает упоминания в контексте безопасности. Если включена опция include_html, отправляемое им электронное сообщение будет содержать полную обратную трассировку с именами и значениями локальных переменных на каждом уровне стека, а также значениями ваших настроек Django (другими словами, тот же уровень детализации, который отображается на веб-странице, когда DEBUG имеет значение True).

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

Примеры¶

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

Для начала вот небольшая конфигурация, которая позволит вам выводить все сообщения журнала на консоль:

import os

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
        },
    },
    "root": {
        "handlers": ["console"],
        "level": "WARNING",
    },
}

Это настраивает родительский корневой регистратор для отправки сообщений с уровнем WARNING и выше обработчику консоли. Установив уровень «INFO» или «DEBUG», вы можете отображать больше сообщений. Это может быть полезно во время разработки.

Далее мы можем добавить более детальное ведение журнала. Вот пример того, как заставить систему журналирования печатать больше сообщений только из Джанго с именем logger:

import os

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
        },
    },
    "root": {
        "handlers": ["console"],
        "level": "WARNING",
    },
    "loggers": {
        "django": {
            "handlers": ["console"],
            "level": os.getenv("DJANGO_LOG_LEVEL", "INFO"),
            "propagate": False,
        },
    },
}

По умолчанию эта конфигурация отправляет на консоль сообщения из логгера django уровня INFO или выше. Это тот же уровень, что и конфигурация ведения журнала по умолчанию в Django, за исключением того, что конфигурация по умолчанию отображает записи журнала только тогда, когда DEBUG=True. Django не регистрирует много таких сообщений уровня INFO. Однако с помощью этой конфигурации вы также можете установить переменную среды DJANGO_LOG_LEVEL=DEBUG, чтобы видеть все журналы отладки Django, которые очень подробны, поскольку включают в себя все запросы к базе данных.

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

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {
        "file": {
            "level": "DEBUG",
            "class": "logging.FileHandler",
            "filename": "/path/to/django/debug.log",
        },
    },
    "loggers": {
        "django": {
            "handlers": ["file"],
            "level": "DEBUG",
            "propagate": True,
        },
    },
}

При использовании этого примера убедитесь, что пользователь, от которого запускается Django приложение, имеет права на запись файла, указанного в 'filename'.

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

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "verbose": {
            "format": "{levelname} {asctime} {module} {process:d} {thread:d} {message}",
            "style": "{",
        },
        "simple": {
            "format": "{levelname} {message}",
            "style": "{",
        },
    },
    "filters": {
        "special": {
            "()": "project.logging.SpecialFilter",
            "foo": "bar",
        },
        "require_debug_true": {
            "()": "django.utils.log.RequireDebugTrue",
        },
    },
    "handlers": {
        "console": {
            "level": "INFO",
            "filters": ["require_debug_true"],
            "class": "logging.StreamHandler",
            "formatter": "simple",
        },
        "mail_admins": {
            "level": "ERROR",
            "class": "django.utils.log.AdminEmailHandler",
            "filters": ["special"],
        },
    },
    "loggers": {
        "django": {
            "handlers": ["console"],
            "propagate": True,
        },
        "django.request": {
            "handlers": ["mail_admins"],
            "level": "ERROR",
            "propagate": False,
        },
        "myproject.custom": {
            "handlers": ["console", "mail_admins"],
            "level": "INFO",
            "filters": ["special"],
        },
    },
}

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

• Указывает что конфигурация задана в формате „dictConfig версия 1“. На данный момент это единственная версия dictConfig формата.

• Определяет два форматера:

  • simple, просто возвращает уровень логгирования сообщения (например, DEBUG) и содержимое сообщения.

    Строка format является обычной строкой форматирования Python, описывающая детали, которые будут присутствовать в каждой строке журнала. Полный список переменных для форматирования вы можете найти в документации.

  • verbose, выведет уровень логгирования, сообщение, время, название процесса, потока и модуля, который создал сообщение.

• Определяет два фильтра:

  • project.logging.SpecialFilter с названием special. Если конструктор фильтра требует наличия дополнительных аргументов, вы можете указать их в словаре настройки фильтра. В этом случае будет передан аргумент foo со значением bar при создании экземпляра SpecialFilter.

  • django.utils.log.RequireDebugTrue – пропускает записи только в случае когда параметр конфигурации DEBUG равен True.

• Определяет два обработчика:

  • console, StreamHandler, который перенаправляет все сообщения уровня DEBUG (и выше) в stderr. Этот обработчик использует формат simple.

  • mail_admins, AdminEmailHandler, который отправляет по электронной почте любое сообщение ERROR (или выше) на сайт ADMINS. Этот обработчик использует специальный фильтр.

• Настраивает три логгера:

  • django, который перенаправляет все сообщения в обработчик console.

  • django.request, который передает все сообщения уровня ERROR в обработчик mail_admins. Также указывается, что логгер не должен передавать сообщения родительским логгерам. Это означает что сообщения переданные в django.request не будут обрабатываться логгером django.

  • myproject.custom, который передает все сообщения уровня INFO и выше прошедшие фильтр special в два обработчика – console и mail_admins. Это означает что все сообщения уровня INFO (или выше) будут отправлены в консоль, сообщения ERROR и CRITICAL будут отосланы через e-mail.

Собственная конфигурация логгирования¶

Если вы не хотите использовать формат dictConfig для настройки логгирования, вы можете определить собственный формат.

Параметр LOGGING_CONFIG определяет вызываемый объект, который будет использоваться для настройки регистраторов Django. По умолчанию он указывает на функцию Python logging.config.dictConfig(). Однако если вы хотите использовать другой процесс настройки, вы можете использовать любой другой вызываемый объект, который принимает один аргумент. Содержимое LOGGING будет предоставлено как значение этого аргумента при настройке ведения журнала.

Отключение настройки логгирования¶

Если вы вообще не хотите настраивать ведение журнала (или хотите настроить ведение журнала вручную, используя свой собственный подход), вы можете установить для LOGGING_CONFIG значение None. Это отключит процесс настройки Django ведения журнала по умолчанию.

Установка LOGGING_CONFIG в None только означает, что процесс автоматической настройки отключен, это не влияет на само журналирование. Если вы отключите процесс конфигурации, Django все равно будет вызывать методы журналирования, используя поведение логгеров, настроенное по умолчанию.

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

LOGGING_CONFIG = None

import logging.config

logging.config.dictConfig(...)

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