Add log_manager documentation to doc/
This commit is contained in:
271
doc/src.utils.log_manager.md
Normal file
271
doc/src.utils.log_manager.md
Normal file
@@ -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"
|
||||
```
|
||||
Reference in New Issue
Block a user