Гайд по логированию

Обзор

Система логирования использует именованные логгеры с цветовым выделением по паттернам. Каждый модуль получает свой именованный логгер через утилиту logger.

Что есть в logger

• Именованные логгеры для каждого модуля
• Цветовое выделение по паттернам (консоль)
• Файловое логирование (logs/core.log)
• Ротация файлов логов
• Умное форматирование с цветами

Уровни логирования

INFO — информационные сообщения

Назначение: Краткое и основное только про текущую функцию. Не описываем функционал "внутри".

Примеры:

• [Tenant-137] Парсинг сценариев...
• [Tenant-1] [Bot-1] Обновлен бот
• Синхронизация {X} групп сценариев...

Правила:

• ✅ Кратко и лаконично
• ✅ Только про текущую функцию
• ✅ Каждая функция самодостаточна в логировании
• ❌ Не описываем, что происходит внутри других функций

WARNING — предупреждения

Назначение: Требует внимания, но не критично.

Примеры:

• Ошибка обновления из GitHub, но продолжаем работу
• Пропуск группы без названия
• Отсутствие токена, пулинг не запущен

Правила:

• Используем когда процесс может продолжаться
• Указываем причину и действие

ERROR — ошибки

Назначение: Критично — нарушена работа процесса.

Примеры:

• [Tenant-137] Ошибка парсинга сценариев: ...
• Ошибка синхронизации сценариев: ...
• Не удалось создать/обновить бота

Правила:

• Пишем при реальных ошибках
• Указываем причину ошибки

DEBUG — отладка

Назначение: Используется только при разборе ошибок и проблем.

Правила:

• ❌ Не используется в продовом коде
• ✅ Только по запросу пользователя для отладки

Паттерны выделения

Система автоматически выделяет цветом паттерны в логах. Доступны следующие типы выделения:

Квадратные скобки [...] — Cyan (голубой)

Назначение: Контекст — ID сущностей, модулей, сервисов.

Примеры:

• [Tenant-137] — ID тенанта
• [Bot-1] — ID бота
• [Queue-action] — имя очереди
• [Service-name] — имя сервиса
• [Module-name] — имя модуля

Правила:

1. Иерархия: Сначала Tenant, потом Bot (если есть)

   # ✅ Правильно
   self.logger.info(f"[Tenant-{tenant_id}] [Bot-{bot_id}] Обновлен бот")
   
   # ❌ Неправильно
   self.logger.info(f"[Bot-{bot_id}] [Tenant-{tenant_id}] Обновлен бот")

2. Формат: [Entity-ID] или [Entity-name]

   [Tenant-137]           # ID сущности
   [Queue-critical]       # Имя сущности
   [Service-bot_hub]      # Имя сервиса

3. Множественные контексты: Разделяем пробелами

   [Tenant-1] [Bot-2] Синхронизация команд
   [Queue-system] Обработка задачи

Круглые скобки (...) — Yellow (жёлтый)

Назначение: Статусы, состояния, дополнительная информация.

Примеры:

• (error) — статус ошибки
• (warning) — предупреждение
• (active) — состояние активности
• (3 groups) — количество групп

Правила:

self.logger.info(f"[Tenant-137] Синхронизация (3 группы)")
self.logger.warning(f"[Bot-1] Отсутствует токен (пулинг не запущен)")

Фигурные скобки {...} — Green (зелёный)

Назначение: Данные, конфигурация, значения.

Примеры:

• {config} — конфигурация
• {tenant_id: 137} — данные
• {status: active} — значения

Правила:

# Обычно используются в плейсхолдерах
self.logger.info(f"Загрузка {count} сценариев")

HTTP коды — Magenta (фиолетовый)

Назначение: HTTP статус коды.

Примеры:

• HTTP 200 — успех
• HTTP 404 — не найдено
• HTTP 500 — ошибка сервера

Сводная таблица паттернов

Паттерн	Цвет	Назначение	Пример
[Entity-ID]	Cyan	Контекст (Tenant, Bot, Service)	[Tenant-137] [Bot-1]
(status)	Yellow	Статусы, состояния	(active), (error)
{data}	Green	Данные, значения	{count}, {config}
HTTP XXX	Magenta	HTTP коды	HTTP 200, HTTP 404

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

Цвета

• Используем встроенное цветовое выделение logger (автоматически)
• Цвета применяются к уровням логирования

Паттерны

• Используем паттерны вида [Entity-ID] для структурирования
• Это помогает в поиске и фильтрации логов

Эмодзи

• ❌ Не используем эмодзи в логах
• Есть цветовое выделение и паттерны

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

# ✅ Хорошо: кратко, про текущую функцию
self.logger.info(f"[Tenant-{tenant_id}] Парсинг сценариев...")

# ✅ Хорошо: начало и конец процесса
self.logger.info(f"[Tenant-{tenant_id}] Обновление данных из GitHub...")
# ... процесс ...
self.logger.info(f"[Tenant-{tenant_id}] Данные из GitHub обновлены")

# ✅ Хорошо: с указанием количества
self.logger.info(f"[Tenant-{tenant_id}] Синхронизация {groups_count} групп сценариев...")

# ✅ Хорошо: ошибка с описанием
self.logger.error(f"[Tenant-{tenant_id}] Ошибка синхронизации сценариев: {error}")

# ❌ Плохо: слишком много деталей о внутреннем процессе
self.logger.info(f"[Tenant-{tenant_id}] Начинаю парсинг сценариев, проверяю файлы, читаю конфигурацию...")

# ❌ Плохо: эмодзи
self.logger.info(f"✅ [Tenant-{tenant_id}] Сценарии успешно синхронизированы")

Итоговые правила

1. Лаконичность: Только основное, без избыточных деталей
2. Самодостаточность: Каждая функция логирует свою работу
3. Иерархия: Сначала Tenant, потом Bot/другие сущности
4. Без эмодзи: Используем цвета и паттерны
5. DEBUG: Только по запросу, не в проде