trustgraph/docs/tech-specs/logging-strategy.ru.md

---
layout: default
title: "Стратегия логирования TrustGraph"
parent: "Russian (Beta)"
---

# Стратегия логирования TrustGraph

> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

## Обзор

TrustGraph использует встроенный модуль `logging` Python для всех операций логирования, с централизованной конфигурацией и опциональной интеграцией с Loki для агрегации логов. Это обеспечивает стандартизированный и гибкий подход к логированию для всех компонентов системы.

## Параметры конфигурации по умолчанию

### Уровень логирования
- **Уровень по умолчанию**: `INFO`
- **Указывается через**: аргумент командной строки `--log-level`
- **Возможные значения**: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`

### Направления вывода
1. **Консоль (stdout)**: Всегда включено - обеспечивает совместимость с контейнерными средами
2. **Loki**: Опциональная централизованная агрегация логов (включена по умолчанию, может быть отключена)

## Модуль централизованного логирования

Вся конфигурация логирования управляется модулем `trustgraph.base.logging`, который предоставляет:
- `add_logging_args(parser)` - Добавляет стандартные аргументы командной строки для логирования
- `setup_logging(args)` - Настраивает логирование на основе предоставленных аргументов

Этот модуль используется всеми серверными компонентами:
- Сервисы, основанные на AsyncProcessor
- API Gateway
- Сервер MCP

## Рекомендации по реализации

### 1. Инициализация логгера

Каждый модуль должен создавать свой собственный логгер, используя `__name__` модуля:

```python
import logging

logger = logging.getLogger(__name__)
```

Имя логгера автоматически используется как метка в Loki для фильтрации и поиска.

### 2. Инициализация сервиса

Все серверные сервисы автоматически получают конфигурацию логирования через централизованный модуль:

```python
from trustgraph.base import add_logging_args, setup_logging
import argparse

def main():
    parser = argparse.ArgumentParser()

    # Добавляем стандартные аргументы логирования (включая конфигурацию Loki)
    add_logging_args(parser)

    # Добавляем свои аргументы для сервиса
    parser.add_argument('--port', type=int, default=8080)

    args = parser.parse_args()
    args = vars(args)

    # Настраиваем логирование в начале запуска
    setup_logging(args)

    # Остальная часть инициализации сервиса
    logger = logging.getLogger(__name__)
    logger.info("Сервис запущен...")
```

### 3. Аргументы командной строки

Все сервисы поддерживают следующие аргументы логирования:

**Уровень логирования:**
```bash
--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
```

**Конфигурация Loki:**
```bash
--loki-enabled              # Включить Loki (по умолчанию)
--no-loki-enabled           # Отключить Loki
--loki-url URL              # URL для отправки логов в Loki (по умолчанию: http://loki:3100/loki/api/v1/push)
--loki-username USERNAME    # Необязательное имя пользователя для аутентификации
--loki-password PASSWORD    # Необязательный пароль для аутентификации
```

**Примеры:**
```bash
# По умолчанию - уровень INFO, Loki включен
./my-service

# Режим отладки, только консоль
./my-service --log-level DEBUG --no-loki-enabled

# Пользовательский сервер Loki с аутентификацией
./my-service --loki-url http://loki.prod:3100/loki/api/v1/push \
             --loki-username admin --loki-password secret
```

### 4. Переменные окружения

Конфигурация Loki поддерживает использование переменных окружения:

```
export LOKI_URL=http://loki.prod:3100/loki/api/v1/push
export LOKI_USERNAME=admin
export LOKI_PASSWORD=secret
```

Аргументы командной строки имеют приоритет над переменными окружения.

### 5. Рекомендации по логированию

#### Использование уровней логирования
- **DEBUG**: Детальная информация для диагностики проблем (значения переменных, вход/выход функций)
- **INFO**: Общие информационные сообщения (запуск сервиса, загрузка конфигурации, этапы обработки)
- **WARNING**: Предупреждающие сообщения о потенциально опасных ситуациях (устаревшие функции, восстанавливаемые ошибки)
- **ERROR**: Сообщения об ошибках о серьезных проблемах (неудачные операции, исключения)
- **CRITICAL**: Критические сообщения о системных сбоях, требующих немедленного внимания

#### Формат сообщений
```python
# Хорошо - включает контекст
logger.info(f"Обработка документа: {doc_id}, размер: {doc_size} байт")
logger.error(f"Не удалось подключиться к базе данных: {error}", exc_info=True)

# Плохо - не включает контекст
logger.info("Обработка документа")
logger.error("Не удалось подключиться")
```

#### Соображения производительности
```python
# Используйте ленивую адресацию для дорогостоящих операций
logger.debug("Результат дорогостоящей операции: %s", expensive_function())

# Проверяйте уровень логирования для очень дорогих операций DEBUG
if logger.isEnabledFor(logging.DEBUG):
    debug_data = compute_expensive_debug_info()
    logger.debug(f"Данные для отладки: {debug_data}")
```

### 6. Структурированное логирование с использованием Loki

Для сложных данных используйте структурированное логирование с дополнительными метками для Loki:

```python
logger.info("Запрос обработан", extra={
    'tags': {
        'request_id': request_id,
        'user_id': user_id,
        'status': 'успешно'
    }
})
```

Эти метки становятся поисковыми метками в Loki, а также автоматически создаваемыми:
- `severity` - Уровень логирования (DEBUG, INFO, WARNING, ERROR, CRITICAL)
- `logger` - Имя модуля (из `__name__`)

### Зависимости

Модуль централизованного логирования требует:
- `python-logging-loki` - Для интеграции с Loki (необязательно, функционирует без него)

Уже включен в `trustgraph-base/pyproject.toml` и `requirements.txt`.

## Переход

Для существующего кода:

1. **Сервисы, уже использующие AsyncProcessor**: Не требуется никаких изменений, интеграция с Loki автоматическая
2. **Сервисы, которые не используют AsyncProcessor** (api-gateway, mcp-server): Уже обновлены
3. **Инструменты командной строки**: Не относится - продолжайте использовать `print()` или простое логирование

### Переход от `print()` к `logging`:
```python
# Предыдущий код
print(f"Обработка документа {doc_id}")

# Новый код
import logging
logger = logging.getLogger(__name__)
logger.info(f"Обработка документа {doc_id}")
```

## Безопасность

- **Никогда не логируйте конфиденциальную информацию** (пароли, API-ключи, персональные данные, токены)
- **Фильтруйте пользовательский ввод** перед логированием
- **Используйте плейсхолдеры** для конфиденциальных полей: `user_id=****1234`
- **Используйте аутентификацию** для Loki с помощью `--loki-username` и `--loki-password` в производственной среде
- **Безопасный транспорт**: Используйте HTTPS для URL Loki в производственной среде: `https://loki.prod:3100/loki/api/v1/push`

## Обзор конфигурации

| Аргумент | Значение по умолчанию | Переменная окружения | Описание |
|---|---|---|---|
| `--log-level` | `INFO` | - | Уровень логирования в консоли и Loki |
| `--loki-enabled` | `True` | - | Включить логирование Loki |
| `--loki-url` | `http://loki:3100/loki/api/v1/push` | `LOKI_URL` | URL для отправки логов в Loki |
| `--loki-username` | `None` | `LOKI_USERNAME` | Имя пользователя для аутентификации Loki |
| `--loki-password` | `None` | `LOKI_PASSWORD` | Пароль для аутентификации Loki |