Logging.debug: примеры (PYTHON)

Простые примеры использования

Базовый вызов

import logging
logging.basicConfig(level=logging.DEBUG)
logging.debug('Запуск процесса обработки данных.')

DEBUG:root:Запуск процесса обработки данных.

Форматирование сообщения

import logging
logging.basicConfig(level=logging.DEBUG)
user = 'Иван'
items = 5
logging.debug('Пользователь %s заказал %d товаров.', user, items)

DEBUG:root:Пользователь Иван заказал 5 товаров.

Использование f-строки

import logging
logging.basicConfig(level=logging.DEBUG)
temp = 36.6
logging.debug(f'Текущее значение температуры: {temp}')

DEBUG:root:Текущее значение температуры: 36.6

Логирование информации об исключении

import logging
logging.basicConfig(level=logging.DEBUG)
try:
    x = 1 / 0
except ZeroDivisionError:
    logging.debug('Произошла ошибка деления', exc_info=True)

DEBUG:root:Произошла ошибка деления
Traceback (most recent call last):
  File "", line 2, in 
ZeroDivisionError: division by zero

Похожие функции в Python

Модуль logging предоставляет функции для других уровней логирования:

• logging.info(): Для регистрации информационных сообщений о нормальной работе приложения (уровень INFO).
• logging.warning(): Для предупреждений о нештатных, но некритичных ситуациях (уровень WARNING).
• logging.error(): Для сообщений об ошибках, которые повлияли на выполнение конкретной операции (уровень ERROR).
• logging.critical(): Для критических ошибок, после которых программа может не работать (уровень CRITICAL).

Функцию debug() предпочтительнее использовать для деталей, необходимых при отладке. В production-средах уровень логгера часто устанавливают на INFO или выше, что скрывает отладочные сообщения и снижает нагрузку. Для информирования о ходе работы используют info(), а для проблем - warning() и error().

Типичные ошибки

Сообщения не выводятся из-за уровня логирования

import logging
# Уровень по умолчанию - WARNING
logging.debug('Это сообщение не появится.')

(Вывода нет)

Решение: установить уровень DEBUG через logging.basicConfig(level=logging.DEBUG).

Несоответствие числа аргументов форматирования

import logging
logging.basicConfig(level=logging.DEBUG)
logging.debug('Значения: %s и %s', 'первое')

--- Логирование вызовет исключение TypeError ---
# TypeError: not enough arguments for format string

Использование неправильного синтаксиса форматирования

import logging
logging.basicConfig(level=logging.DEBUG)
logging.debug('Сумма: %d', 'не_число')

--- Может привести к исключению во время логирования ---
# TypeError: %d format: a number is required, not str

Попытка логирования изменяемых объектов напрямую

import logging
logging.basicConfig(level=logging.DEBUG)
data_list = []
logging.debug('Список: %s', data_list)
data_list.append('секрет')
# В логе будет старое значение списка, если само сообщение формируется лениво.

Для сложных объектов лучше использовать явное преобразование в строку или логгировать репрезентацию (repr(obj)).

Изменения в последних версиях

• Python 3.8: Добавлен параметр stacklevel. Он позволяет указать, сколько уровней стека нужно подняться для корректного определения имени файла, функции и номера строки в записи лога. Это полезно при создании функций-оберток для логирования.
• Python 3.9: Повышение производительности за счет оптимизации внутреннего кода модуля logging, что косвенно влияет и на работу debug().
• Python 3.11: Добавлена поддержка групп исключений (ExceptionGroup) в параметре exc_info.

Расширенные примеры

Логирование с пользовательскими атрибутами (extra)

import logging

FORMAT = '%(asctime)s - %(levelname)s - %(user)s - %(message)s'
logging.basicConfig(level=logging.DEBUG, format=FORMAT)

logging.debug('Попытка входа', extra={'user': 'user123'})

2023-10-26 15:30:00,123 - DEBUG - user123 - Попытка входа

Использование stacklevel

import logging
logging.basicConfig(level=logging.DEBUG, format='%(filename)s:%(lineno)d - %(message)s')

def helper():
    logging.debug('Сообщение из helper', stacklevel=2)

def main():
    helper() # Без stacklevel в логе будет указана строка внутри helper

main()

example.py:10 - Сообщение из helper
# (Указывает на строку вызова helper() в main, а не на строку внутри helper)

Логирование в файл с фильтрацией по уровню

import logging

logger = logging.getLogger('my_app')
logger.setLevel(logging.DEBUG)

file_handler = logging.FileHandler('app_debug.log')
file_handler.setLevel(logging.DEBUG) # В файл идут только DEBUG и выше
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
file_handler.setFormatter(formatter)
logger.addHandler(file_handler)

logger.debug('Детальная отладочная информация для файла.')

# Содержимое файла app_debug.log:
# 2023-10-26 15:30:00,456 - my_app - DEBUG - Детальная отладочная информация для файла.

Логирование в структурированном формате (JSON)

import logging
import json

class JsonFormatter(logging.Formatter):
    def format(self, record):
        log_record = {
            'time': self.formatTime(record),
            'level': record.levelname,
            'message': record.getMessage(),
            'module': record.module
        }
        if record.exc_info:
            log_record['exception'] = self.formatException(record.exc_info)
        return json.dumps(log_record)

logger = logging.getLogger('json_logger')
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler()
handler.setFormatter(JsonFormatter())
logger.addHandler(handler)

logger.debug('Структурированное отладочное событие.', extra={'module': 'auth'})

{"time": "15:30:00", "level": "DEBUG", "message": "Структурированное отладочное событие.", "module": "auth"}

Условное логирование для повышения производительности

import logging
logger = logging.getLogger('perf_sensitive')
logger.setLevel(logging.INFO) # DEBUG сообщения по умолчанию не выводятся

if logger.isEnabledFor(logging.DEBUG):
    # Дорогостоящая операция выполняется только при активном уровне DEBUG
    expensive_data = some_heavy_calculation()
    logger.debug('Результат тяжелого расчета: %s', expensive_data)

Аналоги в других языках программирования

JavaScript (Node.js)

const debug = require('debug')('app');
debug('Отладочное сообщение');
// Требует установки пакета 'debug' и включения переменной среды DEBUG=app

Java (библиотека log4j или SLF4J)

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

Logger logger = LoggerFactory.getLogger(MyClass.class);
logger.debug("Отладочное сообщение с параметром: {}", value);

PHP (Monolog)

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$log = new Logger('name');
$log->pushHandler(new StreamHandler('path/to/your.log', Logger::DEBUG));
$log->debug('Отладочное сообщение');

C# (NLog или log4net)

using NLog;

Logger logger = LogManager.GetCurrentClassLogger();
logger.Debug("Отладочное сообщение {Value}", someValue);

Go (стандартная библиотека log)

import "log"

func main() {
    log.SetFlags(log.Ldate | log.Ltime | log.Lshortfile)
    log.Println("[DEBUG]", "Отладочное сообщение")
    // Уровни обычно реализуются вручную или сторонними библиотеками (slog, logrus).
}

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