Ведение журнала¶

Состав игроков¶

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

• Логеры
• Обработчики
• Фильтры
• Форматировщики

Именование регистраторов¶

Вызов logging.getLogger() получает (при необходимости создает) экземпляр регистратора. Экземпляр регистратора идентифицируется именем. Это имя используется для идентификации регистратора в целях конфигурации.

По соглашению, имя регистратора обычно __name__, имя модуля Python, который содержит регистратор. Это позволяет вам фильтровать и обрабатывать вызовы регистрации на основе каждого модуля. Однако, если у вас есть другой способ организации сообщений протоколирования, вы можете указать любое имя, разделенное точками, для идентификации вашего регистратора:

# Get an instance of a specific named logger
logger = logging.getLogger('project.interesting.stuff')

Пунктирные пути имен регистраторов определяют иерархию. Логгер project.interesting считается родителем логгера project.interesting.stuff; логгер project является родителем логгера project.interesting.

Почему иерархия важна? Потому что логгеры могут быть настроены на распространение своих вызовов логирования на их родителей. Таким образом, вы можете определить один набор обработчиков в корне дерева логгеров и перехватить все вызовы протоколирования в поддереве логгеров. Логгер, определенный в пространстве имен project, будет перехватывать все сообщения, выдаваемые логгерами project.interesting и project.interesting.stuff.

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

Ведение журнала вызовов¶

Экземпляр регистратора содержит метод входа для каждого из уровней журнала по умолчанию:

• logger.debug()
• logger.info()
• logger.warning()
• logger.error()
• logger.critical()

Существуют два других способа ведения журнала:

• logger.log(): Вручную выдает сообщение журнала с определенным уровнем регистрации.
• logger.exception(): Создает сообщение регистрации уровня ERROR, обернув текущий кадр стека исключений.

Примеры:¶

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

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

import os

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

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

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

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, которые очень подробны, так как включают все запросы к базе данных.

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

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,
        },
    },
}

Если вы используете этот пример, не забудьте изменить путь 'filename' на место, доступное для записи пользователю, который запускает приложение Django.

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

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, описывающая детали, которые должны быть выведены в каждой строке журнала. Полный список деталей, которые могут быть выведены, можно найти в Formatter Objects.

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

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

  • project.logging.SpecialFilter, используя псевдоним special. Если для данного фильтра требуются дополнительные аргументы, они могут быть предоставлены как дополнительные ключи в словаре конфигурации фильтра. В этом случае аргументу foo будет присвоено значение bar при инстанцировании SpecialFilter.
  • django.utils.log.RequireDebugTrue, который передает записи, когда DEBUG становится True.

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

  • console, обработчик StreamHandler, который печатает любое сообщение INFO (или выше) в sys.stderr. Этот обработчик использует формат вывода simple.
  • mail_admins, обработчик AdminEmailHandler, который отправляет любое ERROR (или выше) сообщение на сайт ADMINS. Этот обработчик использует фильтр special.

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

  • django, который передает все сообщения обработчику console.
  • django.request, который передает все сообщения ERROR обработчику mail_admins. Кроме того, этот логгер помечен как не распространяющий сообщения. Это означает, что сообщения журнала, записанные в django.request, не будут обработаны регистратором django.
  • myproject.custom, который передает все сообщения уровня INFO или выше, которые также проходят фильтр special, двум обработчикам - console и mail_admins. Это означает, что все сообщения уровня INFO (или выше) будут выведены на консоль; ERROR и CRITICAL сообщения также будут выведены по электронной почте.

Пользовательская конфигурация протоколирования¶

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

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

Отключение конфигурации ведения журнала¶

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

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

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

LOGGING_CONFIG = None

import logging.config
logging.config.dictConfig(...)

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

Логеры¶

Django предоставляет несколько встроенных регистраторов.

'handlers': {
    'null': {
        'class': 'logging.NullHandler',
    },
},
'loggers': {
    'django.security.DisallowedHost': {
        'handlers': ['null'],
        'propagate': False,
    },
},

Обработчики¶

Django предоставляет один обработчик журналов в дополнение к тем, которые предоставляются модулем протоколирования Python.

class AdminEmailHandler(include_html=False, email_backend=None, reporter_class=None)[исходный код]¶

Этот обработчик отправляет письмо на сайт ADMINS для каждого полученного им сообщения журнала.

Если запись журнала содержит атрибут request, в письмо будет включена полная информация о запросе. Тема письма будет включать фразу «internal IP», если IP-адрес клиента находится в настройках INTERNAL_IPS; если нет, она будет включать «EXTERNAL IP».

Если запись журнала содержит информацию о трассировке стека, эта трассировка стека будет включена в письмо.

Аргумент include_html в AdminEmailHandler используется для управления тем, включает ли письмо с обратным отслеживанием HTML-вложение, содержащее полное содержимое отладочной веб-страницы, которая была бы создана, если бы DEBUG было True. Чтобы задать это значение в вашей конфигурации, включите его в определение обработчика для django.utils.log.AdminEmailHandler, например, так:

'handlers': {
    'mail_admins': {
        'level': 'ERROR',
        'class': 'django.utils.log.AdminEmailHandler',
        'include_html': True,
    }
},

Обратите внимание, что эта HTML-версия письма содержит полный отслеживание, с именами и значениями локальных переменных на каждом уровне стека, плюс значения ваших настроек Django. Эта информация потенциально очень конфиденциальна, и вы можете не захотеть отправлять ее по электронной почте. Рассмотрите возможность использования чего-то вроде Sentry, чтобы получить лучшее из двух миров - богатую информацию полного отслеживания и безопасность не отправки информации по электронной почте. Вы также можете явно указать определенную конфиденциальную информацию, которая будет отфильтрована из отчетов об ошибках - узнайте больше о Filtering error reports.

Установив аргумент email_backend в AdminEmailHandler, можно переопределить email backend, используемый обработчиком, следующим образом:

'handlers': {
    'mail_admins': {
        'level': 'ERROR',
        'class': 'django.utils.log.AdminEmailHandler',
        'email_backend': 'django.core.mail.backends.filebased.EmailBackend',
    }
},

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

Аргумент reporter_class AdminEmailHandler позволяет предоставить подкласс django.views.debug.ExceptionReporter для настройки текста трассировки, отправляемого в теле письма. Вы указываете строковый путь импорта к классу, который вы хотите использовать, например, так:

'handlers': {
    'mail_admins': {
        'level': 'ERROR',
        'class': 'django.utils.log.AdminEmailHandler',
        'include_html': True,
        'reporter_class': 'somepackage.error_reporter.CustomErrorReporter'
    }
},

send_mail(subject, message, *args, **kwargs)[исходный код]¶

Отправляет электронные письма пользователям-администраторам. Чтобы настроить это поведение, вы можете использовать подкласс класса AdminEmailHandler и переопределить этот метод.

Фильтры¶

Django предоставляет некоторые фильтры журналов в дополнение к тем, которые предоставляет модуль протоколирования Python.

class CallbackFilter(callback)[исходный код]¶

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

Например, чтобы отфильтровать UnreadablePostError (появляется, когда пользователь отменяет загрузку) из писем администратора, вы создадите функцию фильтрации:

from django.http import UnreadablePostError

def skip_unreadable_post(record):
    if record.exc_info:
        exc_type, exc_value = record.exc_info[:2]
        if isinstance(exc_value, UnreadablePostError):
            return False
    return True

а затем добавьте его в конфигурацию протоколирования:

'filters': {
    'skip_unreadable_posts': {
        '()': 'django.utils.log.CallbackFilter',
        'callback': skip_unreadable_post,
    }
},
'handlers': {
    'mail_admins': {
        'level': 'ERROR',
        'filters': ['skip_unreadable_posts'],
        'class': 'django.utils.log.AdminEmailHandler'
    }
},

class RequireDebugFalse[исходный код]¶

Этот фильтр будет пропускать записи только в том случае, если settings.DEBUG имеет значение False.

Этот фильтр используется следующим образом в конфигурации LOGGING по умолчанию, чтобы гарантировать, что AdminEmailHandler отправляет письма с ошибками администраторам только тогда, когда DEBUG является False:

'filters': {
    'require_debug_false': {
        '()': 'django.utils.log.RequireDebugFalse',
    }
},
'handlers': {
    'mail_admins': {
        'level': 'ERROR',
        'filters': ['require_debug_false'],
        'class': 'django.utils.log.AdminEmailHandler'
    }
},

class RequireDebugTrue[исходный код]¶

Этот фильтр аналогичен RequireDebugFalse, за исключением того, что записи передаются только тогда, когда DEBUG и True.