From e752f88ae28cf14fca41c37514a83d387b5ac6d2 Mon Sep 17 00:00:00 2001 From: Komisar Date: Thu, 16 Apr 2026 15:15:40 +0300 Subject: [PATCH] Add log_manager documentation to doc/ --- doc/src.utils.log_manager.md | 271 +++++++++++++++++++++++++++++++++++ 1 file changed, 271 insertions(+) create mode 100644 doc/src.utils.log_manager.md diff --git a/doc/src.utils.log_manager.md b/doc/src.utils.log_manager.md new file mode 100644 index 0000000..c5737fb --- /dev/null +++ b/doc/src.utils.log_manager.md @@ -0,0 +1,271 @@ +# LogManager + +Модуль логирования с выводом в консоль и файл с поддержкой ротации. + +## Установка + +```python +import src.utils.log_manager as log +``` + +## Быстрый старт + +```python +import src.utils.config_manager as config +import src.utils.log_manager as log + +# Загрузка конфигурации +config.load() + +# Регистрация глобальных параметров логирования +log.register_global_params() + +# Регистрация модулей +log.register(module="my_module", log_console=True, log_file="my_module.log") + +# Инициализация +log.setup() + +# Использование +logger = log.get_logger("my_module") +logger.print("Сообщение") # в консоль +logger.print("Отладочное", level="debug") # с уровнем +logger.print("Ошибка", level="error") # в stderr +``` + +## Константы + +```python +from src.utils.log_manager import ( + LOG_CATEGORY, + LOG_CONSOLE, + LOG_STDERR, + LOG_FILE, + LOG_PATH, + LOG_LEVEL, + LOG_FILE_LEVEL, + LOG_ROTATION, + LOG_ROTATION_SIZE, + LOG_ROTATION_COUNT, + LOG_TIMESTAMP, + LOG_BUFFERED, + MODULE_LOG_CONSOLE, + MODULE_LOG_STDERR, + MODULE_LOG_FILE, + MODULE_LOG_LEVEL, + DEFAULT_TIMESTAMP, + DEFAULT_LOG_LEVEL, + DEFAULT_FILE_LEVEL, + DEFAULT_LOG_PATH, + DEFAULT_LOG_FILE, + DEFAULT_ROTATION, + DEFAULT_ROTATION_SIZE, + DEFAULT_ROTATION_COUNT, +) +``` + +| Константа | Значение | Описание | +|----------|---------|----------| +| `LOG_CATEGORY` | `"logger"` | Категория параметров логера | +| `LOG_CONSOLE` | `"log_console"` | Включить вывод в консоль | +| `LOG_STDERR` | `"log_stderr"` | Включить вывод в stderr | +| `LOG_FILE` | `"log_file"` | Имя файла логов | +| `LOG_PATH` | `"log_path"` | Путь к директории логов | +| `LOG_LEVEL` | `"log_level"` | Уровень логирования | +| `LOG_FILE_LEVEL` | `"log_file_level"` | Уровень для файла | +| `LOG_ROTATION` | `"log_rotation"` | Тип ротации: `size` или `external` | +| `LOG_ROTATION_SIZE` | `"log_rotation_size"` | Размер файла для ротации | +| `LOG_ROTATION_COUNT` | `"log_rotation_count"` | Количество ротированных файлов | +| `LOG_TIMESTAMP` | `"log_timestamp"` | Формат timestamp | +| `LOG_BUFFERED` | `"log_buffered"` | Буферизация записей | +| `DEFAULT_TIMESTAMP` | `"%Y-%m-%d %H:%M:%S"` | Формат времени по умолчанию | + +## Регистрация глобальных параметров + +```python +log.register_global_params() +``` + +Регистрирует параметры в `config_manager`: +- `logger.log_console` - включить вывод в консоль (default: `true`) +- `logger.log_stderr` - включить stderr для ошибок (default: `true`) +- `logger.log_file` - имя файла логов (default: `app.log`) +- `logger.log_path` - путь к директории (default: `./log`) +- `logger.log_level` - уровень для консоли (default: `INFO`) +- `logger.log_file_level` - уровень для файла (default: `DEBUG`) +- `logger.log_rotation` - тип ротации: `size` или `external` (default: `size`) +- `logger.log_rotation_size` - размер для ротации (default: `10MB`) +- `logger.log_rotation_count` - количество файлов (default: `5`) +- `logger.log_timestamp` - формат timestamp (default: `%Y-%m-%d %H:%M:%S`) + +## Регистрация модуля + +```python +log.register( + module="my_module", # имя модуля + log_console=True, # вывод в консоль + log_stderr=False, # вывод в stderr + log_file="my.log", # имя файла (None = не писать в файл) + log_level="INFO" # уровень (None = наследуется) +) +``` + +### Параметры модуля + +Если параметр не указан или `None`, используется глобальное значение. + +## Конфигурация в global.yaml + +```yaml +# Глобальные настройки +logger.log_console: true +logger.log_stderr: true +logger.log_file: "app.log" +logger.log_path: "./log" +logger.log_level: "INFO" +logger.log_file_level: "DEBUG" +logger.log_rotation: "size" +logger.log_rotation_size: "10MB" +logger.log_rotation_count: 5 +logger.log_timestamp: "%Y-%m-%d %H:%M:%S" +logger.log_buffered: false + +# Настройки для конкретного модуля (переопределяют глобальные) +my_module.log_console: false +my_module.log_file: "custom.log" +my_module.log_level: "DEBUG" +``` + +## API + +### Регистрация + +```python +log.register_global_params() # регистрация глобальных параметров +log.register(module, log_console, log_stderr, log_file, log_level) +``` + +### Получение логера + +```python +logger = log.get_logger("module_name") +``` + +### Вывод сообщений + +```python +logger.print("message") # в консоль (stdout) +logger.print("msg", level="debug") # уровень для лога +logger.print("msg", level="info") # default +logger.print("msg", level="warning") # в stderr +logger.print("msg", level="error") # в stderr + +log.print("global message") # от корневого логера +``` + +### Уровни логирования + +- `debug` - stdout + файл (DEBUG) +- `info` - stdout + файл (INFO, default) +- `warning` - stderr + файл (WARNING) +- `error` - stderr + файл (ERROR) + +### Инициализация + +```python +log.setup() # вызывается при старте приложения +``` + +## Ротация логов + +### По размеру (`log_rotation=size`) + +Используется `RotatingFileHandler`. При достижении `log_rotation_size` происходит ротация. + +```yaml +logger.log_rotation: "size" +logger.log_rotation_size: "10MB" +logger.log_rotation_count: 5 +``` + +Файлы: `app.log`, `app.log.1`, `app.log.2`, ... + +### Внешняя (`log_rotation=external`) + +Используется базовый `FileHandler`. Ротацией управляет внешняя система (logrotate). + +```yaml +logger.log_rotation: "external" +``` + +## Правила написания модулей + +### Обязательно использовать `logger.print()` вместо `print()` + +```python +# НЕПРАВИЛЬНО +print("Сообщение") + +# ПРАВИЛЬНО +logger = log.get_logger("my_module") +logger.print("Сообщение") +``` + +### Инициализация модуля + +```python +# my_module/__init__.py +import src.utils.log_manager as log + +def init(): + log.register(module="my_module", log_console=True, log_file="my_module.log") + +def main(): + log.print("Модуль запущен") +``` + +## Примеры + +### Базовое использование + +```python +import src.utils.config_manager as config +import src.utils.log_manager as log + +config.load() +log.register_global_params() +log.register(module="app", log_console=True) +log.setup() + +logger = log.get_logger("app") +logger.print("Application started") +``` + +### С настройками из конфига + +```python +import src.utils.config_manager as config +import src.utils.log_manager as log + +config.load() +log.register_global_params() + +# Регистрация модулей с параметрами из конфига +log.register(module="model") +log.register(module="ui", log_console=True) + +log.setup() +``` + +### Разные форматы timestamp + +```yaml +# Короткий +logger.log_timestamp: "%H:%M:%S" + +# Полный +logger.log_timestamp: "%Y-%m-%d %H:%M:%S" + +# С микросекундами +logger.log_timestamp: "%Y-%m-%d %H:%M:%S.%f" +```