babaev-an / ANB Python Components
CI/CD
Реестр контейнеров и пакетов

class_desc/protocols/i_log_formatter.md

Интерфейс ILogFormatter

Интерфейс ILogFormatter определяет контракт для классов, отвечающих за форматирование сообщений системы журналирования. Он позволяет:

  • унифицировать вывод логов в рамках приложения;
  • легко заменять формат вывода без изменения основной логики логирования;
  • поддерживать разные форматы вывода (текстовый, JSON и т.д.) параллельно.

Основная информация

  • Имя файла: anb_python_components/protocols/i_log_formatter.py
  • Автор: Александр Бабаев
  • Версия: 1.0.0
  • Дата начала поддержки: с версии 1.5.0

Метод интерфейса

format_message

Форматирует сообщение по заданному правилу.

Сигнатура:

def format_message (self, level: int, message: str, context: dict | None = None) -> str:
    pass

Параметры:

Параметры Тип Описание
level int Уровень сообщения (например, DEBUG, INFO, WARNING, ERROR). Используется для категоризации и фильтрации логов, может влиять на визуальное оформление (цвет, префикс)
message str Основной текст сообщения лога. Должен быть читаемым и информативным, описывающим событие или ошибку
context dict[str, Any]|None Необязательный словарь с дополнительной контекстной информацией (например, идентификатор пользователя, время операции, параметры запроса). Если контекст не указан, значение равно None

Возвращаемое значение: str: Отформатированная строка, готовая к выводу в поток логов (файл, консоль, сеть и т.д.). Формат строки определяется реализацией протокола. Примеры:

Простой текст: [2024-04-12 10:00:00] ERROR: Не удалось подключиться к БД
JSON: {"timestamp": "2024-04-12T10:00:00", "level": "ERROR", "message": "Не удалось подключиться", "context": {"
db_host": "localhost"}}

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

Пример 1: Простая реализация (текстовый формат)

from datetime import datetime

class SimpleLogFormatter:
    
    def format_message (self, level: int, message: str, context: dict | None = None) -> str:
        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
        
        match level:
            case 0:
                level_name = 'ОТЛАДКА'
            case 10:
                level_name = 'ИНФОРМАЦИЯ'
            case 11:
                level_name = 'УСПЕХ',
            case 20:
                level_name = 'ПРЕДУПРЕЖДЕНИЕ',
            case 30:
                level_name = 'ОСТАНОВКА ВЫПОЛНЕНИЯ',
            case 31:
                level_name = 'КРИТИЧЕСКАЯ ОШИБКА',
            case 39:
                level_name = 'ОШИБКА',
            case 100:
                level_name = 'ЖУРНАЛИРОВАНИЕ НЕ ВЕДЁТСЯ'
            case _:
                level_name = ''
        if context:
            context_str = f" | Контекст: {context}"
        else:
            context_str = ""
        
        return f"[{timestamp}] {level_name}: {message}{context_str}"

Пример 2: Реализация для JSON‑логов

import json
from datetime import datetime

class JsonLogFormatter:
    
    def format_message (self, level: int, message: str, context: dict | None = None) -> str:
        log_entry = {
                "timestamp": datetime.now().isoformat(),
                "level": level.value,
                "message": message
                }
        if context:
            log_entry["context"] = context
        
        return json.dumps(log_entry, ensure_ascii = False)

Сценарии применения

Реализация ILogFormatter полезна в следующих случаях:

  • Форматирование в простой текстовый вид для вывода в консоль или файл.
  • Генерация JSON‑записей для централизованного сбора логов (например, в ELK Stack).
  • Добавление временных меток, идентификаторов запросов или метаданных среды.
  • Цветовое выделение уровней логов в консольном выводе (с использованием ANSI‑кодов).
  • Адаптация формата под требования внешних систем мониторинга и анализа логов.

На главную

Назад